@capacitor/toast

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

简介

@capacitor/toast提供了一个通知弹窗，用于向用户显示信息，兼容capacitor的Android、iOS等主流移动平台，本文档只说明在OpenHarmony系统中的使用。

本插件用于在屏幕上显示短暂的消息提示，常用于显示简短的通知或反馈信息，适配OpenHarmony系统的消息提示场景，调用便捷、轻量。

支持平台

• OpenHarmony：5.0+

下载安装

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

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

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

npm安装：

# 安装插件
npm install @capacitor/toast

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/toast

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件，步骤如下：

1. 添加插件配置

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

{
  "pkg": "@capacitor/toast",
  "classpath": "Toast"
}

2. 修改 CMake 配置

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

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

// ...

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

3. 复制源码文件

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

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

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

4. 添加 ArkTS 配置

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

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

卸载

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

约束与限制

兼容性

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

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：显示简单文本消息

import { Toast } from '@capacitor/toast';

const showHelloToast = async () => {
  await Toast.show({
    text: 'Hello!',
  });
};

示例2：自定义时长和位置

import { Toast } from '@capacitor/toast';

// 显示底部、长时间的提示消息
const showLongBottomToast = async () => {
  await Toast.show({
    text: '操作成功！',
    duration: 'long',
    position: 'bottom'
  });
};

// 显示顶部、短时间的提示消息
const showShortTopToast = async () => {
  await Toast.show({
    text: '请检查输入',
    duration: 'short',
    position: 'top'
  });
};

使用说明

Toast是插件导出对象，可直接导入使用，导入后即可调用插件提供的所有方法，调用便捷高效，所有API均基于Promise实现，支持异步调用，适用于各类简短消息提示场景。

核心 API：Toast 对象

Toast 是插件导出对象，可直接导入使用，导入后即可调用插件提供的所有方法，调用便捷高效。

方法列表与说明

| 方法名 | 调用方式 | 入参类型 | 功能描述 | |-----------|-------------------------|-----------------------------|----------------------------------| | show(...) | Toast.show(ShowOptions) | ShowOptions | 在屏幕上显示一个 Toast 消息，支持配置显示文本、时长和位置 |

接口定义

ShowOptions

调用 show 方法时的入参对象，用于配置Toast的显示效果和内容。

| 参数 | 类型 | 描述 | 必填 | 默认值 | |----------|-------------------------|----------------------------------------------|----|----------| | text | string | 在 Toast 上显示的文本，建议简洁明了，避免过长 | 是 | 无 | | duration | 'short'丨'long' | Toast 显示的持续时间，'short'对应2000ms，'long'对应3500ms | 否 | 'short' | | position | 'top'丨'center'丨'bottom' | Toast 在屏幕上的显示位置，支持顶部、中间、底部三种 | 否 | 'bottom' |

目录结构

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

贡献代码

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

许可证

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