@cordova-ohos/cordova-plugin-x-toast

v2.7.3

Published

4 months ago

Cordova x-toast Plugin

0High
0Medium
0Low

cordova x-toast ecosystem:cordova cordova-openharmony

cordova-plugin-x-toast

npm version

cordova-plugin-x-toast 是一款为 Cordova 应用打造的跨平台原生提示框插件，支持显示通知型、操作型、输入型等多种类型的 toast 与对话框，适配各平台原生设计规范。插件具备高度可定制性，可灵活配置提示内容、样式、交互逻辑，满足应用在不同场景下的消息反馈需求，提升用户交互体验。

1. 插件概述

作为 Cordova 生态中消息提示领域的主流插件，cordova-plugin-x-toast 基于原生平台提示框能力开发，具备以下核心优势：

多类型提示支持：覆盖通知型 toast（短/长提示）
高度可定制化：支持自定义提示文本、字体大小、颜色、背景样式、按钮文案、弹窗位置、显示时长等属性，匹配应用视觉风格
灵活交互控制：支持配置按钮点击回调、输入内容校验、选择结果返回等交互逻辑，满足复杂业务场景
轻量级架构：插件体积小巧（约 50KB），无冗余依赖，集成后不影响应用启动速度与运行性能
跨平台统一：统一多平台 API 调用方式，无需针对不同平台编写差异化代码，降低开发成本
兼容性广泛：支持低版本系统（Android 4.4+、iOS 9.0+、Windows 10+、HarmonyOS5.0+），覆盖绝大多数移动设备与浏览器环境

2. 安装方式

2.1 基础安装（推荐）

在 Cordova 项目根目录执行以下命令，插件会自动处理各平台依赖与基础配置：

# 安装hcordova
npm install -g hcordova

# 安装最新版本
hcordova plugin add cordova-plugin-x-toast

# 安装指定版本
hcordova plugin add [email protected] --platform ohos

3.2 从 GitCode 源码安装

若需使用开发中的最新功能，可直接从 GitHub 仓库安装：

hcordova plugin add https://github.com/OpenHarmony-Cordova/cordova-plugin-x-toast.git --platform ohos

3.4 卸载插件

如需移除插件，执行以下命令即可清理相关配置与依赖：

# 全平台卸载
hcordova plugin remove cordova-plugin-x-toast

# 指定HarmonyOS卸载
hcordova plugin remove cordova-plugin-x-toast --platform ohos

4. API 文档

插件通过全局对象 window.plugins.toast 暴露所有 API，支持 Promise 与回调函数两种调用方式（推荐使用 Promise 简化异步逻辑）。所有 API 需在 deviceready 事件触发后调用，避免因原生接口未初始化导致错误。

4.1 通知型 Toast（短提示）

用于显示简短操作反馈（如 “保存成功”），无交互按钮，自动消失。

4.1.1 显示基础通知型 Toast

/**

* 显示基础通知型 Toast
* @param {Object} options - 配置参数
* @returns {Promise<void>} - 无返回值，Promise  resolved 表示显示完成
*/

window.plugins.toast.showWithOptions({
    message: "hey there",
    duration: "short", //short 2000 ms long 5000 ms
    position: "center",
    data:{top:5},
    styling: {
        opacity: 0.75, // 鸿蒙系统默认，此参数无效
        backgroundColor: '#FF0000', // 背景色 默认： #ffffff
        textColor: '#FFFF00', // 文本颜色 默认 #000000
        textSize: 20.5, // 文字大小：默认14.
        cornerRadius: 16, //圆角：默认：16
        horizontalPadding: 20, // 左边水平边距
        verticalPadding: -16 // 垂直边距
    }
},
function(args) {
    console.log(args);
},
function(error) {
    console.error('toast error: ', error);
});

4.1.2 辅助API


//short 2000ms
window.plugins.toast.showShortTop('Hello there!', function(a){
    console.log('toast success: ' + a)
}, function(b){
    alert('toast error: ' + b)
})

window.plugins.toast.showShortCenter('Hello there!', function(a){
    console.log('toast success: ' + a)
}, function(b){
    alert('toast error: ' + b)
})

window.plugins.toast.showShortBottom('Hello there!', function(a){
    console.log('toast success: ' + a)
}, function(b){
    alert('toast error: ' + b)
})

//long 5000ms
window.plugins.toast.showLongTop('Hello there!', function(a){
    console.log('toast success: ' + a)
}, function(b){
    alert('toast error: ' + b)
})

window.plugins.toast.showLongCenter('Hello there!', function(a){
    console.log('toast success: ' + a)
}, function(b){
    alert('toast error: ' + b)
})

window.plugins.toast.showLongBottom('Hello there!', function(a){
    console.log('toast success: ' + a)
}, function(b){
    alert('toast error: ' + b)
})

4.1.3 隐藏API

window.plugins.toast.hide();

许可证

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

参考资源

Android和iOS：cordova-plugin-x-toast 官方指南
GitCode 仓库：OpenHarmony-Cordova/cordova-plugin-x-toast