@cordova-ohos/cordova-plugin-dialogs
v2.0.2
Published
Cordova dialogs Plugin
Downloads
153
Readme
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 前提条件
在安装插件前，请确保开发环境满足以下基础要求：
已安装 Node.js (v14.0.0 及以上) 和 npm (v6.0.0 及以上)，可通过
node -v和npm -v命令验证版本。已全局安装 Cordova CLI (v10.0.0 及以上)，若未安装，可执行以下命令：
npm install -g hcordova- 已创建 Cordova 项目（若尚未创建，可通过
hcordova create MyDialogApp com.example.dialogapp 对话框示例应用命令快速创建项目）。
3.2 插件安装命令
在 Cordova 项目根目录下，根据需求选择以下方式安装插件：
直接安装
hcordova plugin add cordova-plugin-dialogs指定平台安装
hcordova plugin add cordova-plugin-dialogs --platform ohos从 GitCode 源码安装
若需使用最新开发版本（可能包含未发布的新功能或修复），可从 GitHub 源码安装：
hcordova plugin add https://github.com/apache/cordova-plugin-dialogs.git --platform ohos3.3 插件卸载命令
若需移除插件，在项目根目录执行以下命令：
hcordova plugin remove cordova-plugin-dialogs3.3 插件卸载命令，指定平台
若需移除插件，在项目根目录执行以下命令：
hcordova plugin remove cordova-plugin-dialogs --platform ohos3.4 插件查看命令
安装完成后，可通过以下命令验证插件是否成功添加到项目中：
hcordova plugin list若输出结果包含 cordova-plugin-dialogs，则表示插件已成功安装。
4. 核心 API 说明
插件通过全局对象 navigator.notification 暴露所有对话框相关 API，所有方法均支持回调函数，便于处理用户交互结果。以下是各核心功能的详细说明：
4.1 警告框（Alert）
用于向用户展示纯提示性信息，仅包含 “确认” 按钮，用户点击后关闭对话框，适用于告知用户操作结果、系统通知等场景。
方法签名
navigator.notification.alert(message, alertCallback, title, buttonName);参数说明
| 参数名 | 类型 | 是否必选 | 说明 |
| --------------- | -------- | ---- | ------------------------------------------ |
| message | String | 是 | 对话框中显示的提示内容，支持换行符（n）实现多行文本。 |
| alertCallback | Function | 否 | 用户点击确认按钮后的回调函数，无参数，仅用于执行后续逻辑。 |
| title | String | 否 | 对话框标题，默认值为 “Alert”（不同平台可能有差异，如 iOS 默认无标题）。 |
| buttonName | String | 否 | 确认按钮文本，默认值为 “OK”。 |
示例代码
// 等待 Cordova 环境就绪
document.addEventListener('deviceready', function() {
// 显示警告框
navigator.notification.alert(
'操作已成功完成！n请返回首页继续操作', // 提示内容
function() {
console.log('用户已确认警告信息');
// 此处可添加确认后的逻辑，如跳转页面
// window.location.href = 'index.html';
}, // 回调函数
'操作成功', // 对话框标题
'确定' // 按钮文本
);
}, false);4.2 确认框（Confirm）
用于获取用户的二元选择（如 “是 / 否”“确认 / 取消”），包含多个按钮，用户点击后通过回调函数返回选择结果，适用于删除操作确认、权限申请确认等场景。
方法签名
navigator.notification.confirm(message, confirmCallback, title, buttonLabels);参数说明
| 参数名 | 类型 | 是否必选 | 说明 |
| ----------------- | ------------ | ---- | ------------------------------------------------------------------------ |
| message | String | 是 | 对话框提示内容，支持多行文本。 |
| confirmCallback | Function | 是 | 用户点击按钮后的回调函数，参数为用户选择的按钮索引（从 0 开始）。 |
| title | String | 否 | 对话框标题，默认值为 “Confirm”。 |
| buttonLabels | Array/String | 否 | 按钮文本列表，可传入字符串（逗号分隔，如 “确定，取消”）或数组（如 ["确定","取消"]），默认值为 ["OK", "Cancel"]。 |
示例代码
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）
用于获取用户输入的文本信息，包含输入框和确认 / 取消按钮，用户提交后通过回调函数返回输入内容，适用于获取用户名、备注信息等场景。
方法签名
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）
用户设置响铃，嘟嘟声音。
方法签名
navigator.notification.beep(1);参数说明
| 参数名 | 类型 | 是否必选 | 说明 |
| ---------------- | ------------ | ---- | -------------------------------------------------------- |
| count | 响几次铃声 | 是 | 设置1：响一次，2：响二次 n：响n次 |
示例代码
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 文件中使用：
<!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('已取消邮箱输入');
}
},
'输入框示例',
['验证', '取消'],
'[email protected]'
);
}
</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 文件。
你可以自由地：
使用、复制、修改本插件的源代码；
将修改后的代码用于商业或非商业项目；
分发本插件的源代码或二进制文件。
10. 联系方式与支持
若你在使用过程中遇到问题或有功能建议，可通过以下渠道获取支持：
OHOS官方仓库
GitCode 仓库：https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-dialogs
提交 Issue：在仓库的 Issues 页面提交问题描述（需包含平台版本、插件版本、复现步骤），官方团队会在 1-3 个工作日内回复。
Apache 社区支持(Android/iOS)
- Apache Cordova (Android/iOS)官方论坛：https://cordova.apache.org/community/