@capacitor/action-sheet

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

简介

@capacitor/action-sheet 是 capacitor 生态系统中的核心插件，提供对原生操作表的访问，为跨平台应用开发提供设备差异化适配能力，兼容 capacitor 的 Android、iOS 等主流移动平台及浏览器环境，本文档主要说明在 OpenHarmony 系统中的使用。

该插件允许调用原生的操作表组件，展示一系列操作选项供用户选择，常用于分享、更多操作等场景。

支持平台

• OpenHarmony：5.0+

下载安装

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

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

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

npm安装：

# 安装插件
npm install @capacitor/action-sheet

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/action-sheet

手动引入安装

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

1. 添加插件配置

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

{
    "pkg": "@capacitor/action-sheet",
    "classpath": "ActionSheet"
}

2. 修改 CMake 配置

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

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

// ...

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

3. 复制源码文件

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

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

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

4. 添加 ArkTS 配置

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

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

卸载

# 卸载 action-sheet 插件
hionic plugin remove @capacitor/action-sheet

约束与限制

兼容性

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

1. SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

使用示例

基础示例：显示 action sheet

import { ActionSheet, ActionSheetButtonStyle } from '@capacitor/action-sheet';

const showActions = async () => {
  const result = await ActionSheet.showActions({
    title: 'Photo Options',
    message: 'Select an option to perform',
    options: [
      {
        title: 'Upload',
      },
      {
        title: 'Share',
      },
      {
        title: 'Remove',
        style: ActionSheetButtonStyle.Destructive,
      },
    ],
  });

  console.log('Action Sheet result:', result);
};

使用说明

接口方法

| 方法名 | 返回类型 | 描述 | | ---- | ---- | ---- | | showActions(options: ShowActionsOptions) | Promise<ShowActionsResult> | 显示一个操作表样式的模态框，其中包含各种选项供用户选择 |

数据结构

ShowActionsResult

操作表选择结果：

| 属性名 | 类型 | 描述 | | ----------- | ------ | -------------------------- | | index | number | 点击选项的索引（从零开始） |

ShowActionsOptions

操作表配置选项：

| 属性名 | 类型 | 描述 | 备注 | | ------------- | ---------------------- | -------------------- | ---------- | | title | string | 操作表的标题。 | | | message | string | 标题下方显示的消息。 | 仅支持 iOS | | options | ActionSheetButton[] | 用户可选择的选项。 | |

ActionSheetButton

操作表按钮选项：

| 属性名 | 类型 | 描述 | 备注 | | ----------- | ---------------------- | -------------------------- | ----------------- | | title | string | 选项的标题 | | | style | ActionSheetButtonStyle | 该选项的样式。 | 仅在 iOS 上受支持 | | icon | string | 选项图标（图标命名规则）。 | 仅在 Web 上受支持 |

ActionSheetButtonStyle

按钮样式枚举：

| 成员 | 值 | 描述 | 备注 | | ----------------- | --------------- | --------------------------- | ----------------- | | Default | 'DEFAULT' | 选项的默认样式 | 仅在 iOS 上受支持 | | Destructive | 'DESTRUCTIVE' | 用于破坏性选项的样式 | 仅在 iOS 上受支持 | | Cancel | 'CANCEL' | 用于取消操作表的选项的样式 | 仅在 iOS 上受支持 |

目录结构

|---- 项目根目录
|     |---- src
|           |---- main
|                 |---- cpp
|                       |---- ActionSheet   # 插件核心 C++ 实现
|                             |---- ActionSheet.cpp
|                             |---- ActionSheet.h
|                             |---- CMakeLists.txt
|                 |---- ets
|                       |---- components
|                             |---- ActionSheet   # ArkTS 组件实现
|                                   |---- ActionSheet.ets
|     |---- README.md                # 说明文档
|     |---- package.json             # npm 配置文件
|     |---- plugin.xml              # capacitor 插件配置
|     |---- LICENSE                 # 许可证文件

贡献代码

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

许可证

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