npm package: @luqi_test/cordova-plugin-dialogs
Description: Cordova dialogs Plugin
Author: Huawei Device, Inc. Ltd. and
Latest version: 2.0.2

# cordova-plugin-dialogs

## 1. 插件介绍

`cordova-plugin-dialogs` 是一款专为 Apache Cordova/PhoneGap 应用设计的对话框插件，旨在帮助开发者快速实现跨平台的系统级对话框功能。通过该插件，开发者无需关注不同平台对话框的原生实现差异，即可轻松调用警告框、确认框、输入框和进度指示器等常用交互组件，为用户提供统一且符合平台设计规范的交互体验，本文档主要说明该插件在OHOS系统中的应用。

该插件完全遵循 Cordova 插件开发标准，API 设计简洁直观，支持多平台自适应，可无缝集成到各类 Cordova 移动应用中，适用于消息提示、用户确认、信息输入等多种业务场景。

## 2. 支持平台

该插件已针对以下操作系统和平台进行适配，确保功能稳定性和交互一致性：

* **Android** (API 级别 21 及以上，覆盖 Android 5.0 及更高版本)

* **iOS** (iOS 10.0 及以上，支持 iPhone、iPad 等全系列 iOS 设备)

* **Windows** (Windows 10 及以上，包含 UWP 通用应用场景)

* **Browser** (主流桌面及移动浏览器，如 Chrome、Firefox、Safari、Edge 等)

* **OHOS** (5.0+ )

## 3. 安装步骤

### 3.1 前提条件

在安装插件前，请确保开发环境满足以下基础要求：



1. 已安装 Node.js (v14.0.0 及以上) 和 npm (v6.0.0 及以上)，可通过 `node -v` 和 `npm -v` 命令验证版本。

2. 已全局安装 Cordova CLI (v10.0.0 及以上)，若未安装，可执行以下命令：



```bash
npm install -g hcordova
```



1. 已创建 Cordova 项目（若尚未创建，可通过 `hcordova create MyDialogApp com.example.dialogapp 对话框示例应用` 命令快速创建项目）。

### 3.2 插件安装命令

在 Cordova 项目根目录下，根据需求选择以下方式安装插件：

#### 直接安装

```bash
hcordova plugin add cordova-plugin-dialogs
```

#### 指定平台安装

```bash
hcordova plugin add cordova-plugin-dialogs --platform ohos
```


#### 从 GitCode 源码安装

若需使用最新开发版本（可能包含未发布的新功能或修复），可从 GitHub 源码安装：



```bash
hcordova plugin add https://github.com/apache/cordova-plugin-dialogs.git --platform ohos
```

### 3.3 插件卸载命令

若需移除插件，在项目根目录执行以下命令：

```bash
hcordova plugin remove cordova-plugin-dialogs
```

### 3.3 插件卸载命令，指定平台

若需移除插件，在项目根目录执行以下命令：

```
hcordova plugin remove cordova-plugin-dialogs --platform ohos
```


### 3.4 插件查看命令

安装完成后，可通过以下命令验证插件是否成功添加到项目中：

```bash
hcordova plugin list
```

若输出结果包含 `cordova-plugin-dialogs`，则表示插件已成功安装。

## 4. 核心 API 说明

插件通过全局对象 `navigator.notification` 暴露所有对话框相关 API，所有方法均支持回调函数，便于处理用户交互结果。以下是各核心功能的详细说明：

### 4.1 警告框（Alert）

用于向用户展示纯提示性信息，仅包含 “确认” 按钮，用户点击后关闭对话框，适用于告知用户操作结果、系统通知等场景。

#### 方法签名



```bash
navigator.notification.alert(message, alertCallback, title, buttonName);
```

#### 参数说明

| 参数名             | 类型       | 是否必选 | 说明                                         |
| --------------- | -------- | ---- | ------------------------------------------ |
| `message`       | String   | 是    | 对话框中显示的提示内容，支持换行符（`n`）实现多行文本。             |
| `alertCallback` | Function | 否    | 用户点击确认按钮后的回调函数，无参数，仅用于执行后续逻辑。              |
| `title`         | String   | 否    | 对话框标题，默认值为 “Alert”（不同平台可能有差异，如 iOS 默认无标题）。 |
| `buttonName`    | String   | 否    | 确认按钮文本，默认值为 “OK”。                          |

#### 示例代码



```js
// 等待 Cordova 环境就绪
document.addEventListener('deviceready', function() {
   // 显示警告框
   navigator.notification.alert(
       '操作已成功完成！n请返回首页继续操作',  // 提示内容
       function() {
           console.log('用户已确认警告信息');
           // 此处可添加确认后的逻辑，如跳转页面
           // window.location.href = 'index.html';
       },  // 回调函数
       '操作成功',  // 对话框标题
       '确定'       // 按钮文本
   );
}, false);
```

### 4.2 确认框（Confirm）
用于获取用户的二元选择（如 “是 / 否”“确认 / 取消”），包含多个按钮，用户点击后通过回调函数返回选择结果，适用于删除操作确认、权限申请确认等场景。

#### 方法签名

```bash
navigator.notification.confirm(message, confirmCallback, title, buttonLabels);
```

#### 参数说明

| 参数名               | 类型           | 是否必选 | 说明                                                                       |
| ----------------- | ------------ | ---- | ------------------------------------------------------------------------ |
| `message`         | String       | 是    | 对话框提示内容，支持多行文本。                                                          |
| `confirmCallback` | Function     | 是    | 用户点击按钮后的回调函数，参数为用户选择的按钮索引（从 0 开始）。                                       |
| `title`           | String       | 否    | 对话框标题，默认值为 “Confirm”。                                                    |
| `buttonLabels`    | Array/String | 否    | 按钮文本列表，可传入字符串（逗号分隔，如 “确定，取消”）或数组（如 ["确定","取消"]），默认值为 ["OK", "Cancel"]。 |

#### 示例代码

```js
document.addEventListener('deviceready', function() {
   // 显示确认框（删除操作确认）
   navigator.notification.confirm(
       '确定要删除该条数据吗？删除后无法恢复！',  // 提示内容
       function(buttonIndex) {
           // buttonIndex 为用户点击的按钮索引（0：第一个按钮，1：第二个按钮）
           if (buttonIndex === 1) {
               console.log('用户选择：确定删除');
               // 执行删除逻辑
               // deleteData();
           } else {
               console.log('用户选择：取消删除');
           }
       },  // 回调函数
       '删除确认',  // 对话框标题
       ['确定', '取消']  // 按钮列表
   );

}, false);
```

### 4.3 输入框（Prompt）

用于获取用户输入的文本信息，包含输入框和确认 / 取消按钮，用户提交后通过回调函数返回输入内容，适用于获取用户名、备注信息等场景。

#### 方法签名

```bash
navigator.notification.prompt(message, promptCallback, title, buttonLabels, defaultText);
```

#### 参数说明


| 参数名              | 类型           | 是否必选 | 说明                                                       |
| ---------------- | ------------ | ---- | -------------------------------------------------------- |
| `message`        | String       | 是    | 输入提示文本，告知用户需输入的内容类型。                                     |
| `promptCallback` | Function     | 是    | 用户操作后的回调函数，参数为包含 `buttonIndex`（按钮索引）和 `input1`（输入内容）的对象。 |
| `title`          | String       | 否    | 对话框标题，默认值为 “Prompt”。                                     |
| `buttonLabels`   | Array/String | 否    | 按钮文本列表，默认值为 ["OK", "Cancel"]。                           |
| `defaultText`    | String       | 否    | 输入框默认填充文本，适用于预填默认值（如常用用户名）。                              |


### 4.4 嘟嘟（Beep）

用户设置响铃，嘟嘟声音。

#### 方法签名

```bash
navigator.notification.beep(1);
```

#### 参数说明


| 参数名              | 类型           | 是否必选 | 说明                                                       |
| ---------------- | ------------ | ---- | -------------------------------------------------------- |
| `count`        | 响几次铃声       | 是    | 设置1：响一次，2：响二次 n：响n次                                   |


#### 示例代码

```js
document.addEventListener('deviceready', function() {
   // 显示输入框（获取用户昵称）
   navigator.notification.prompt(
       '请输入您的昵称，将用于显示在个人主页',  // 提示内容
       function(result) {
           // result 对象包含 buttonIndex 和 input1 两个属性
           console.log('用户点击的按钮索引：', result.buttonIndex);
           console.log('用户输入的昵称：', result.input1);
           if (result.buttonIndex === 1 && result.input1.trim() !== '') {
               alert('昵称设置成功：' + result.input1);
               // 保存昵称逻辑
               // saveNickname(result.input1);
           } else if (result.buttonIndex === 1) {
               alert('昵称不能为空，请重新输入');
           } else {
               alert('已取消昵称设置');
           }
       },  // 回调函数
       '设置昵称',  // 对话框标题
       ['确认', '取消'],  // 按钮列表
       '小明'  // 输入框默认文本
   );

}, false);
```

## 5. 完整示例项目

以下是一个包含所有对话框功能的完整 Cordova 页面示例，可直接复制到项目的 `www/index.html` 文件中使用：

```html
<!DOCTYPE html>
<html>
<head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
   <title>cordova-plugin-dialogs 示例</title>
   <style>
       body {
           font-family: Arial, sans-serif;
           padding: 20px;
           max-width: 600px;
           margin: 0 auto;
       }

       .btn {
           display: block;
           width: 100%;
           padding: 12px;
           margin: 10px 0;
           background-color: #2196F3;
           color: white;
           border: none;
           border-radius: 4px;
           font-size: 16px;
           cursor: pointer;
       }

       .btn:hover {
           background-color: #1976D2;
       }
       h1 {
           text-align: center;
           color: #333;
       }
   </style>
   <script type="text/javascript" src="cordova.js"></script>
   <script type="text/javascript">
       // 等待 Cordova 环境就绪
       document.addEventListener('deviceready', onDeviceReady, false);
       function onDeviceReady() {
           console.log('Cordova 环境已就绪，可调用对话框 API');
           // 绑定按钮点击事件
           document.getElementById('btnAlert').addEventListener('click', showAlert);
           document.getElementById('btnConfirm').addEventListener('click', showConfirm);
           document.getElementById('btnPrompt').addEventListener('click', showPrompt);
           document.getElementById('btnProgress').addEventListener('click', showProgress);
       }

       // 显示警告框
       function showAlert() {
           navigator.notification.alert(
               '这是一个警告框示例n用于展示纯提示信息',
               function() { console.log('警告框已确认'); },
               '警告框示例',
               '我知道了'
           );

       }

       // 显示确认框
       function showConfirm() {
           navigator.notification.confirm(
               '您确定要执行此操作吗？',
               function(btnIdx) {
                   const btnText = btnIdx === 1 ? '确认' : '取消';
                   alert(`您选择了：${btnText}`);
               },
               '确认框示例',
               ['确认', '取消']
           );
       }

       // 显示输入框
       function showPrompt() {
           navigator.notification.prompt(
               '请输入您的邮箱地址',
               function(result) {
                   if (result.buttonIndex === 1) {
                       const email = result.input1.trim();
                       if (/^[^s@]+@[^s@]+.[^s@]+$/.test(email)) {
                           alert(`邮箱验证通过：${email}`);
                       } else {
                           alert('请输入有效的邮箱地址');
                       }
                   } else {
                       alert('已取消邮箱输入');
                   }
               },
               '输入框示例',
               ['验证', '取消'],
               'example@xxx.com'
           );
       }
   </script>
</head>

<body>
   <h1>对话框插件示例</h1>
   <button id="btnAlert" class="btn">显示警告框</button>
   <button id="btnConfirm" class="btn">显示确认框</button>
   <button id="btnPrompt" class="btn">显示输入框</button>
</body>

</html>
```


## 9. 许可证

本插件基于 **Apache License 2.0** 开源协议发布，详细许可条款请查看项目根目录下的 [LICENSE](LICENSE) 文件。

你可以自由地：

* 使用、复制、修改本插件的源代码；

* 将修改后的代码用于商业或非商业项目；

* 分发本插件的源代码或二进制文件。


## 10. 联系方式与支持

若你在使用过程中遇到问题或有功能建议，可通过以下渠道获取支持：

### OHOS官方仓库

* GitCode 仓库：[https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-dialogs](https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-dialogs)

* 提交 Issue：在仓库的 Issues 页面提交问题描述（需包含平台版本、插件版本、复现步骤），官方团队会在 1-3 个工作日内回复。

### Apache 社区支持(Android/iOS)

* Apache Cordova (Android/iOS)官方论坛：[https://cordova.apache.org/community/](https://cordova.apache.org/community/)