@capacitor/dialog

本项目基于 @capacitor/[email protected] 开发。

简介

@capacitor/dialog是capacitor生态系统中的核心插件，提供了触发本地对话窗口的标准化方法，可实现警告弹窗、确认选择框、输入提示框三类核心交互场景。插件兼容Android、iOS原生平台特性，同时支持浏览器环境，本文档主要说明在OpenHarmony系统中使用。

API提供了触发本地对话窗口的方法，用于显示警告、确认和输入提示。

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm install @capacitor/dialog

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/dialog

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，通过 target 字段找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

{
  "pkg": "@capacitor/dialog",
  "classpath": "Dialog"
}

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，通过 modules-name 字段找到模块 capacitor，路径为 target 字段的 CMakeLists.txt 文件，并根据 param 标签添加 add_subdirectory 和 target_link_libraries 如下：

#START_ADD_SUBDIRECTORY
// ...
add_subdirectory(Dialog)
// ...
#END_ADD_SUBDIRECTORY

// ...

target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  Dialog
  // ...
  "-Wl,--no-whole-archive"
)

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并根据 modules-name 字段和 target-dir 字段找到文件复制的具体模块和目录：

将源码中src/main/cpp/Dialog目录下的Dialog.h、Dialog.cpp、CMakeLists.txt文件引入到capacitor模块中src/main/cpp/Dialog目录下。

将源码中src/main/ets/components/Dialog目录下的Dialog.ets文件引入到capacitor模块中src/main/ets/components/Dialog目录下。

4. 添加 ArkTS 配置

在capacitor模块的build-profile.json5文件中，buildOption/arkOptions/runtimeOnly/sources配置项数组中加入步骤 3 中拷贝的 ets 文件路径：

{
  "buildOption": {
    "arkOptions": {
      "runtimeOnly": {
        "sources": [
          "./src/main/ets/components/Dialog/Dialog.ets"
        ]
      }
    }
  }
}

卸载

# 卸载 dialog 插件
hionic plugin remove @capacitor/dialog

约束与限制

兼容性

在以下版本中已测试通过：

1. capacitor: 8.0.0-ohos-8.0.0;SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

无需额外申请权限。

使用示例

示例1：警告弹窗（Alert）

实现基础警告提示功能，点击按钮后关闭弹窗。

// 导入 Dialog 模块
import { Dialog } from '@capacitor/dialog';

// 警告弹窗方法
const showAlert = async () => {
  try {
    // 调用 alert 方法，传入标题与消息
    await Dialog.alert({
      title: '操作提示',
      message: '功能已执行完成',
      buttonTitle: '确定'
    });
    console.log('警告弹窗关闭');
  } catch (error) {
    console.error('警告弹窗调用失败：', error);
  }
};

示例2：确认选择框（Confirm）

实现确认交互，根据用户选择执行不同逻辑。

// 导入 Dialog 模块
import { Dialog } from '@capacitor/dialog';

// 确认框方法
const showConfirm = async () => {
  try {
    // 调用 confirm 方法，获取用户选择结果
    const { value } = await Dialog.confirm({
      title: '确认操作',
      message: '是否确认删除当前数据？',
      okButtonTitle: '删除',
      cancelButtonTitle: '取消'
    });

    if (value) {
      console.log('用户确认执行删除操作');
      // 执行删除逻辑
    } else {
      console.log('用户取消删除操作');
    }
  } catch (error) {
    console.error('确认框调用失败：', error);
  }
};

示例3：输入提示框（Prompt）

实现带输入框的交互，获取用户输入内容。

// 导入 Dialog 模块
import { Dialog } from '@capacitor/dialog';

// 输入框方法
const showPrompt = async () => {
  try {
    // 调用 prompt 方法，获取输入结果
    const { value, cancelled } = await Dialog.prompt({
      title: '输入信息',
      message: '请输入您的昵称：',
      inputPlaceholder: '请输入昵称',
      inputText: '',
      okButtonTitle: '确认',
      cancelButtonTitle: '取消'
    });

    if (cancelled) {
      console.log('用户取消输入操作');
      return;
    }

    if (value && value.trim()) {
      console.log('用户输入昵称：', value.trim());
      // 执行昵称保存逻辑
    } else {
      console.log('用户输入内容为空');
    }
  } catch (error) {
    console.error('输入框调用失败：', error);
  }
};

使用说明

@capacitor/dialog所有API均基于Promise实现，支持异步调用。

1. 警告弹窗（Alert）

展示包含标题、消息内容和单个按钮的提示弹窗，主要用于操作结果提示、信息告知等场景。

方法签名

alert(options:AlertOptions):Promise<void>

参数说明

| 参数名 | 类型 | 说明 | |---------|-------------------------------|-----------------------------------------------| | options | AlertOptions | 必选，警告弹窗配置参数，包含title、message、buttonTitle三个核心属性 |

AlertOptions

| 属性名 | 类型 | 说明 | 默认值 | |-------------|--------|----------------|------| | title | string | 弹窗标题，显示在弹窗顶部 | 无 | | message | string | 弹窗正文内容，显示在标题下方 | 无 | | buttonTitle | string | 按钮文字，点击后关闭弹窗 | "OK" |

2. 确认选择框（Confirm）

展示包含标题、消息内容、确认按钮和取消按钮的选择弹窗，主要用于用户决策确认场景。

方法签名

confirm(options:ConfirmOptions):Promise<ConfirmResult>

参数说明

| 参数名 | 类型 | 说明 | |---------|-----------------------------------|------------------------------------------------------------------| | options | ConfirmOptions | 必选，确认框配置参数，包含title、message、okButtonTitle、cancelButtonTitle四个核心属性 |

ConfirmOptions

| 属性名 | 类型 | 说明 | 默认值 | |-------------------|--------|----------------|----------| | title | string | 弹窗标题，显示在弹窗顶部 | 无 | | message | string | 弹窗正文内容，显示在标题下方 | 无 | | okButtonTitle | string | 确认按钮文字 | "OK" | | cancelButtonTitle | string | 取消按钮文字 | "Cancel" |

ConfirmResult

| 属性名 | 类型 | 说明 | |-------|---------|----------------------------| | value | boolean | 点击确认按钮返回true，点击取消按钮返回false |

3. 输入提示框（Prompt）

展示包含标题、消息内容、输入框、确认按钮和取消按钮的弹窗，主要用于获取用户输入信息。

方法签名

prompt(options:PromptOptions):Promise<PromptResult>

参数说明

| 参数名 | 类型 | 说明 | |---------|---------------------------------|---------------------------------------------------------------------------------------------| | options | PromptOptions | 必选，输入框配置参数，包含title、message、inputPlaceholder、inputText、okButtonTitle、cancelButtonTitle六个核心属性 |

PromptOptions

| 属性名 | 类型 | 说明 | 默认值 | |-------------------|--------|------------------|----------| | title | string | 弹窗标题，显示在弹窗顶部 | 无 | | message | string | 弹窗正文内容，显示在输入框上方 | 无 | | inputPlaceholder | string | 输入框占位提示文字，未输入时显示 | 无 | | inputText | string | 输入框默认预填内容 | 无 | | okButtonTitle | string | 确认按钮文字 | "OK" | | cancelButtonTitle | string | 取消按钮文字 | "Cancel" |

PromptResult

| 属性名 | 类型 | 说明 | |-----------|---------|----------------------------| | value | string | 用户输入的内容，取消输入时返回空字符串 | | cancelled | boolean | 点击取消按钮返回true，点击确认按钮返回false |

目录结构

|---- 目录
|     |---- src/main  # 插件的实现代码
|           |----cpp  # C++ 代码
|           |----ets   # ArkTS 代码
|     |---- README.md          # 说明文档
|     |---- package.json       # 配置文件
|     |---- plugin.xml       # 插件配置文件

贡献代码

使用过程中发现任何问题都可以提 Issue ，当然，也非常欢迎发 PR 共建。

许可证

本插件基于 MIT License 开源，详见 LICENSE 文件。