michael@0: <!---
michael@0:     Licensed to the Apache Software Foundation (ASF) under one
michael@0:     or more contributor license agreements.  See the NOTICE file
michael@0:     distributed with this work for additional information
michael@0:     regarding copyright ownership.  The ASF licenses this file
michael@0:     to you under the Apache License, Version 2.0 (the
michael@0:     "License"); you may not use this file except in compliance
michael@0:     with the License.  You may obtain a copy of the License at
michael@0: 
michael@0:       http://www.apache.org/licenses/LICENSE-2.0
michael@0: 
michael@0:     Unless required by applicable law or agreed to in writing,
michael@0:     software distributed under the License is distributed on an
michael@0:     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
michael@0:     KIND, either express or implied.  See the License for the
michael@0:     specific language governing permissions and limitations
michael@0:     under the License.
michael@0: -->
michael@0: 
michael@0: # org.apache.cordova.dialogs
michael@0: 
michael@0: 這個外掛程式提供了對一些本機對話方塊的使用者介面元素的訪問。
michael@0: 
michael@0: ## 安裝
michael@0: 
michael@0:     cordova plugin add org.apache.cordova.dialogs
michael@0:     
michael@0: 
michael@0: ## 方法
michael@0: 
michael@0: *   `navigator.notification.alert`
michael@0: *   `navigator.notification.confirm`
michael@0: *   `navigator.notification.prompt`
michael@0: *   `navigator.notification.beep`
michael@0: 
michael@0: ## navigator.notification.alert
michael@0: 
michael@0: 顯示一個自訂的警報或對話方塊框。 大多數科爾多瓦實現使用本機對話方塊中的此項功能，但一些平臺使用瀏覽器的 `alert` 函數，這是通常不那麼可自訂。
michael@0: 
michael@0:     navigator.notification.alert(message, alertCallback, [title], [buttonName])
michael@0:     
michael@0: 
michael@0: *   **消息**： 消息對話方塊。*（字串）*
michael@0: 
michael@0: *   **alertCallback**： 當警報對話方塊的被解雇時要調用的回檔。*（函數）*
michael@0: 
michael@0: *   **標題**： 標題對話方塊。*（字串）*（可選，預設值為`Alert`)
michael@0: 
michael@0: *   **buttonName**： 按鈕名稱。*（字串）*（可選，預設值為`OK`)
michael@0: 
michael@0: ### 示例
michael@0: 
michael@0:     function alertDismissed() {
michael@0:         // do something
michael@0:     }
michael@0:     
michael@0:     navigator.notification.alert(
michael@0:         'You are the winner!',  // message
michael@0:         alertDismissed,         // callback
michael@0:         'Game Over',            // title
michael@0:         'Done'                  // buttonName
michael@0:     );
michael@0:     
michael@0: 
michael@0: ### 支援的平臺
michael@0: 
michael@0: *   亞馬遜火 OS
michael@0: *   Android 系統
michael@0: *   黑莓 10
michael@0: *   火狐瀏覽器作業系統
michael@0: *   iOS
michael@0: *   Tizen
michael@0: *   Windows Phone 7 和 8
michael@0: *   Windows 8
michael@0: 
michael@0: ### Windows Phone 7 和 8 怪癖
michael@0: 
michael@0: *   有沒有內置瀏覽器警報，但你可以綁定一個，如下所示調用 `alert()` 在全球範圍內：
michael@0:     
michael@0:         window.alert = navigator.notification.alert;
michael@0:         
michael@0: 
michael@0: *   兩個 `alert` 和 `confirm` 的非阻塞的調用，其中的結果才是可用的非同步。
michael@0: 
michael@0: ### 火狐瀏覽器作業系統怪癖：
michael@0: 
michael@0: 這兩個本機阻止 `window.alert()` 和非阻塞 `navigator.notification.alert()` 可用。
michael@0: 
michael@0: ## navigator.notification.confirm
michael@0: 
michael@0: 顯示一個可自訂的確認對話方塊。
michael@0: 
michael@0:     navigator.notification.confirm(message, confirmCallback, [title], [buttonLabels])
michael@0:     
michael@0: 
michael@0: *   **消息**： 消息對話方塊。*（字串）*
michael@0: 
michael@0: *   **confirmCallback**: 要用索引 （1、 2 或 3） 按下的按鈕，或者在沒有按下按鈕 (0) 駁回了對話方塊中時調用的回檔。*（函數）*
michael@0: 
michael@0: *   **標題**： 標題對話方塊。*（字串）*（可選，預設值為`Confirm`)
michael@0: 
michael@0: *   **buttonLabels**： 指定按鈕標籤的字串陣列。*（陣列）*（可選，預設值為 [ `OK,Cancel` ])
michael@0: 
michael@0: ### confirmCallback
michael@0: 
michael@0: `confirmCallback`當使用者按下確認對話方塊中的按鈕之一的時候執行。
michael@0: 
michael@0: 回檔將參數 `buttonIndex` *（編號）*，它是按下的按鈕的索引。 請注意索引使用基於 1 的索引，所以值是 `1` ， `2` ， `3` ，等等。
michael@0: 
michael@0: ### 示例
michael@0: 
michael@0:     function onConfirm(buttonIndex) {
michael@0:         alert('You selected button ' + buttonIndex);
michael@0:     }
michael@0:     
michael@0:     navigator.notification.confirm(
michael@0:         'You are the winner!', // message
michael@0:          onConfirm,            // callback to invoke with index of button pressed
michael@0:         'Game Over',           // title
michael@0:         ['Restart','Exit']     // buttonLabels
michael@0:     );
michael@0:     
michael@0: 
michael@0: ### 支援的平臺
michael@0: 
michael@0: *   亞馬遜火 OS
michael@0: *   Android 系統
michael@0: *   黑莓 10
michael@0: *   火狐瀏覽器作業系統
michael@0: *   iOS
michael@0: *   Tizen
michael@0: *   Windows Phone 7 和 8
michael@0: *   Windows 8
michael@0: 
michael@0: ### Windows Phone 7 和 8 怪癖
michael@0: 
michael@0: *   有沒有內置的瀏覽器功能的 `window.confirm` ，但你可以將它綁定通過分配：
michael@0:     
michael@0:         window.confirm = navigator.notification.confirm;
michael@0:         
michael@0: 
michael@0: *   調用到 `alert` 和 `confirm` 的非阻塞，所以結果就是只可用以非同步方式。
michael@0: 
michael@0: ### 火狐瀏覽器作業系統怪癖：
michael@0: 
michael@0: 這兩個本機阻止 `window.confirm()` 和非阻塞 `navigator.notification.confirm()` 可用。
michael@0: 
michael@0: ## navigator.notification.prompt
michael@0: 
michael@0: 顯示本機的對話方塊，更可自訂的瀏覽器比 `prompt` 函數。
michael@0: 
michael@0:     navigator.notification.prompt(message, promptCallback, [title], [buttonLabels], [defaultText])
michael@0:     
michael@0: 
michael@0: *   **消息**： 消息對話方塊。*（字串）*
michael@0: 
michael@0: *   **promptCallback**: 要用索引 （1、 2 或 3） 按下的按鈕，或者在沒有按下按鈕 (0) 駁回了對話方塊中時調用的回檔。*（函數）*
michael@0: 
michael@0: *   **標題**： 對話方塊的標題*（字串）* （可選，預設值為`Prompt`)
michael@0: 
michael@0: *   **buttonLabels**： 陣列，這些字串指定按鈕標籤*（陣列）* （可選，預設值為`["OK","Cancel"]`)
michael@0: 
michael@0: *   **defaultText**: 預設文字方塊中輸入值 （ `String` ） （可選，預設值: 空字串）
michael@0: 
michael@0: ### promptCallback
michael@0: 
michael@0: `promptCallback`當使用者按下一個提示對話方塊中的按鈕時執行。`results`物件傳遞給回檔的包含以下屬性：
michael@0: 
michael@0: *   **buttonIndex**： 按下的按鈕的索引。*（人數）*請注意索引使用基於 1 的索引，所以值是 `1` ， `2` ， `3` ，等等。
michael@0: 
michael@0: *   **輸入 1**： 在提示對話方塊中輸入的文本。*（字串）*
michael@0: 
michael@0: ### 示例
michael@0: 
michael@0:     function onPrompt(results) {
michael@0:         alert("You selected button number " + results.buttonIndex + " and entered " + results.input1);
michael@0:     }
michael@0:     
michael@0:     navigator.notification.prompt(
michael@0:         'Please enter your name',  // message
michael@0:         onPrompt,                  // callback to invoke
michael@0:         'Registration',            // title
michael@0:         ['Ok','Exit'],             // buttonLabels
michael@0:         'Jane Doe'                 // defaultText
michael@0:     );
michael@0:     
michael@0: 
michael@0: ### 支援的平臺
michael@0: 
michael@0: *   亞馬遜火 OS
michael@0: *   Android 系統
michael@0: *   火狐瀏覽器作業系統
michael@0: *   iOS
michael@0: *   Windows Phone 7 和 8
michael@0: 
michael@0: ### Android 的怪癖
michael@0: 
michael@0: *   Android 支援最多的三個按鈕，並忽略任何更多。
michael@0: 
michael@0: *   關於 Android 3.0 及更高版本，使用全息主題的設備按相反的順序顯示按鈕。
michael@0: 
michael@0: ### 火狐瀏覽器作業系統怪癖：
michael@0: 
michael@0: 這兩個本機阻止 `window.prompt()` 和非阻塞 `navigator.notification.prompt()` 可用。
michael@0: 
michael@0: ## navigator.notification.beep
michael@0: 
michael@0: 該設備播放提示音聲音。
michael@0: 
michael@0:     navigator.notification.beep(times);
michael@0:     
michael@0: 
michael@0: *   **時間**： 的次數重複發出蜂鳴音。*（人數）*
michael@0: 
michael@0: ### 示例
michael@0: 
michael@0:     // Beep twice!
michael@0:     navigator.notification.beep(2);
michael@0:     
michael@0: 
michael@0: ### 支援的平臺
michael@0: 
michael@0: *   亞馬遜火 OS
michael@0: *   Android 系統
michael@0: *   黑莓 10
michael@0: *   iOS
michael@0: *   Tizen
michael@0: *   Windows Phone 7 和 8
michael@0: *   Windows 8
michael@0: 
michael@0: ### 亞馬遜火 OS 怪癖
michael@0: 
michael@0: *   亞馬遜火 OS 播放預設**設置/顯示 & 聲音**面板下指定的**通知聲音**。
michael@0: 
michael@0: ### Android 的怪癖
michael@0: 
michael@0: *   Android 系統播放的預設**通知鈴聲****設置/聲音和顯示**面板下指定。
michael@0: 
michael@0: ### Windows Phone 7 和 8 怪癖
michael@0: 
michael@0: *   依賴泛型蜂鳴音檔從科爾多瓦分佈。
michael@0: 
michael@0: ### Tizen 怪癖
michael@0: 
michael@0: *   Tizen 通過播放音訊檔通過媒體 API 實現會發出蜂鳴聲。
michael@0: 
michael@0: *   蜂鳴音檔必須很短，必須設在 `sounds` 子目錄中的應用程式的根目錄中，並且必須命名`beep.wav`.