Cordova - 对话框

Cordova - 对话框

Cordova 对话框（Dialogs）插件（cordova-plugin-dialogs）提供了访问原生平台（native platform）UI 元素（UI elements）的功能，例如弹窗（alerts）、确认框（confirmations）、输入框（prompts）和蜂鸣声（beeps）。这为通知（notifications）和用户交互（user interactions）提供了更原生的用户体验（user experience）。

步骤 1 - 安装对话框插件

在您的项目根目录（root directory）中使用 Cordova CLI（命令行界面）安装该插件：

your-cordova-project/ cordova plugin add cordova-plugin-dialogs

步骤 2 - 添加 UI 元素（按钮）

让我们向 index.html 文件中添加一些按钮，用于触发不同类型的对话框：

<body>
    <button id="showAlertBtn">Show Alert</button>
    <button id="showConfirmBtn">Show Confirm</button>
    <button id="showPromptBtn">Show Prompt</button>
    <button id="playBeepBtn">Play Beep</button>
    <div id="dialogResult">Dialog results will appear here.</div>
</body>

步骤 3 - 添加事件监听器

在 www/js/index.js 文件中，在 onDeviceReady 方法内，为这些按钮附加事件监听器（event listeners）：

// 在 www/js/index.js 的 onDeviceReady 方法内
document.getElementById("showAlertBtn").addEventListener("click", showCustomAlert);
document.getElementById("showConfirmBtn").addEventListener("click", showCustomConfirm);
document.getElementById("showPromptBtn").addEventListener("click", showCustomPrompt);
document.getElementById("playBeepBtn").addEventListener("click", playBeepNotification);

步骤 4 - 实现对话框功能

现在，定义将使用该插件提供的 navigator.notification API 的 JavaScript 函数。

const dialogResultDisplay = document.getElementById('dialogResult');

// 4A - 弹窗对话框
function showCustomAlert() {
    navigator.notification.alert(
        'This is a native alert message!', // 消息内容
        () => { dialogResultDisplay.textContent = 'Alert dismissed.'; }, // 弹窗回调函数
        'Alert Title',                     // 标题
        'Done'                             // 按钮名称
    );
}

// 4B - 确认对话框
function showCustomConfirm() {
    navigator.notification.confirm(
        'Do you want to proceed?', // 消息内容
        (buttonIndex) => { // 确认回调函数
            // buttonIndex 是从 1 开始的。第一个按钮为 1，第二个按钮为 2，以此类推。
            // 如果为 0，则表示对话框在没有按下按钮的情况下被关闭（例如，Android 上的返回按钮）
            if (buttonIndex === 1) {
                dialogResultDisplay.textContent = 'User chose: Yes!';
            } else if (buttonIndex === 2) {
                dialogResultDisplay.textContent = 'User chose: No.';
            } else {
                dialogResultDisplay.textContent = 'Confirm dialog dismissed.';
            }
        },
        'Confirmation',           // 标题
        ['Yes', 'No']             // 按钮标签（字符串数组）
    );
}

// 4C - 输入对话框
function showCustomPrompt() {
    navigator.notification.prompt(
        'Please enter your name:', // 消息内容
        (results) => { // 输入框回调函数
            // results.buttonIndex：按下按钮的 1-based 索引。
            // results.input1：用户输入的文本。
            if (results.buttonIndex === 1 && results.input1) {
                dialogResultDisplay.textContent = `Hello, ${results.input1}!`;
            } else if (results.buttonIndex === 2) {
                dialogResultDisplay.textContent = 'Prompt cancelled.';
            } else {
                 dialogResultDisplay.textContent = `Prompt dismissed. Input: ${results.input1}`;
            }
        },
        'User Input',             // 标题
        ['OK', 'Cancel'],         // 按钮标签（字符串数组）
        'Your name here'          // 默认文本
    );
}

// 4D - 蜂鸣通知
function playBeepNotification() {
    const times = 2; // 重复蜂鸣的次数
    navigator.notification.beep(times);
    dialogResultDisplay.textContent = `Played beep ${times} times.`;
}

理解对话框行为

弹窗（Alert）：点击“Show Alert”按钮将显示一个原生弹窗对话框。例如，它会显示一个弹窗，标题为“Alert Title”，消息内容为“This is a native alert message!”，以及一个标签为“Done”的按钮。关闭弹窗后，“Alert dismissed.”（弹窗已关闭）将显示在 dialogResult div 中。

确认框（Confirm）：点击“Show Confirm”按钮将显示一个对话框，其中包含一个问题，如“Do you want to proceed?”（您想继续吗？）以及“Yes”（是）和“No”（否）按钮。如果点击“Yes”，dialogResult div 将显示“User chose: Yes!”（用户选择了：是！）。如果点击“No”，将显示“User chose: No.”（用户选择了：否）。

输入框（Prompt）：点击“Show Prompt”按钮将打开一个要求输入的对话框，例如“Please enter your name:”（请输入您的姓名：），其中包含一个输入字段（input field），预填充文本为“Your name here”，以及“OK”（确定）和“Cancel”（取消）按钮。如果用户输入“Alex”并点击“OK”，dialogResult div 将显示“Hello, Alex!”（您好，Alex！）。

蜂鸣声（Beep）：点击“Play Beep”按钮将使设备播放其原生通知蜂鸣声两次（因为 times 设置为 2）。dialogResult div 将指示“Played beep 2 times.”（播放了 2 次蜂鸣声）。

要点

• 原生 UI：这些对话框使用平台的原生 UI 元素（UI elements），提供一致的用户体验（user experience）。
• 异步：所有对话框方法（methods）都是异步的（asynchronous）。当用户与对话框交互时，将调用回调函数（callback function）。
• 自定义：您可以为大多数对话框自定义标题、消息内容和按钮标签（button labels）。
• 按钮索引（Button Indexing）：对于 confirm 和 prompt 的回调（callbacks），buttonIndex 是从 1 开始的。值为 0 或没有 buttonIndex 通常表示对话框是通过按下按钮以外的方式关闭的（例如，Android 的返回按钮），尽管这种行为可能因平台而异。