{"_id":"@cordova-ohos/cordova-plugin-x-toast","_rev":"3-4c0a9ef92bff06aa0a2caf05ad824fc0","name":"@cordova-ohos/cordova-plugin-x-toast","dist-tags":{"latest":"2.7.4"},"versions":{"2.7.3":{"name":"@cordova-ohos/cordova-plugin-x-toast","version":"2.7.3","keywords":["cordova","x-toast","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-x-toast@2.7.3","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"}],"bugs":{"url":"https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-x-toast/issues"},"dist":{"shasum":"9e897035a8eb2d6b58d7645bb191853fd173d22a","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-x-toast/-/cordova-plugin-x-toast-2.7.3.tgz","fileCount":10,"integrity":"sha512-ODwq3cPBZiQQAdNxMLHCHD+GO0s9crSl1yfqiQDDGVXZaW/EalxV9A253wFWBqTNkAVj2N0o/rVB1hiYtVFf0w==","signatures":[{"sig":"MEUCIQDvrukjnAr7YRYR/3tRnWAjVhzLD2Md4oUeHRaWSBoqWAIgU0An27WivG/RKS0Gx45y5IL2J3pvdz04pxkvkrpH1z8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":42197},"cordova":{"id":"cordova-plugin-x-toast","platforms":["ohos"]},"engines":{"cordovaDependencies":{"2.7.3":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"74bc3f00d42323485b79c26caea2c3ce70991cce","_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/cordova-plugin-x-toast","type":"git"},"_npmVersion":"10.5.1","description":"Cordova x-toast Plugin","directories":{},"_nodeVersion":"22.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cordova-plugin-x-toast_2.7.3_1774228621126_0.6363206798917107","host":"s3://npm-registry-packages-npm-production"}},"2.7.4":{"name":"@cordova-ohos/cordova-plugin-x-toast","version":"2.7.4","description":"Cordova X-Toast Plugin","cordova":{"id":"cordova-plugin-x-toast","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-x-toast"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-x-toast/issues"},"keywords":["cordova","x-toast","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"2.7.4":{"@cordova-ohos/ohos":">=2.0.0","hcordova":">=1.0.0"}}},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-x-toast@2.7.4","gitHead":"7a9b89e139055363133380d0694ba84513ae89b5","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-WudGeDuoHozL3NxKRmg65H6Sd67Qv1dduQV/S+O9RF1tU8aKWTJDotr5elANytElw8xosemmLp/cEEyyrXMcZQ==","shasum":"f949a807e3573aeade5c3f99302d1fbe406e56f6","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-x-toast/-/cordova-plugin-x-toast-2.7.4.tgz","fileCount":11,"unpackedSize":89504,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD5wGTtERynWloqb4usglzmWozfl3Wz9F0rKnXvEHiOjAIgUU1Bbk+UCDQSU18VJy/YgxwaaikyBKWz+aBuMW6rhyI="}]},"_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"directories":{},"maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cordova-plugin-x-toast_2.7.4_1785152260307_0.1336377428703468"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-23T01:17:01.049Z","modified":"2026-07-27T11:37:40.710Z","2.7.3":"2026-03-23T01:17:01.260Z","2.7.4":"2026-07-27T11:37:40.456Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-x-toast/issues"},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","x-toast","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-x-toast"},"description":"Cordova X-Toast Plugin","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"readme":"# <center>cordova-plugin-x-toast</center>\r\n\r\n[![zh-CN](https://img.shields.io/badge/lang-中文-blue.svg)](README.md)\r\n[![en](https://img.shields.io/badge/lang-English-blue.svg)](README.en.md)\r\n\r\n本项目基于 [cordova-plugin-x-toast@2.7.3](https://www.npmjs.com/package/cordova-plugin-x-toast/v/2.7.3) 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。\r\n\r\n- [cordova-plugin-x-toast](#cordova-plugin-x-toast)\r\n  - [简介](#简介)\r\n  - [功能特性](#功能特性)\r\n  - [OHOS 平台特性](#ohos-平台特性)\r\n  - [支持平台](#支持平台)\r\n  - [前置准备](#前置准备)\r\n  - [下载安装](#下载安装)\r\n    - [前提条件](#前提条件)\r\n    - [基础安装（推荐）](#基础安装推荐)\r\n    - [从 GitCode 源码安装](#从-gitcode-源码安装)\r\n    - [安装后验证](#安装后验证)\r\n    - [离线安装（本地包）](#离线安装本地包)\r\n    - [安装后验证](#安装后验证-1)\r\n    - [卸载插件](#卸载插件)\r\n  - [OHOS 配置](#ohos-配置)\r\n    - [1. 基础配置](#1-基础配置)\r\n    - [2. 样式参数限制说明](#2-样式参数限制说明)\r\n  - [约束与限制](#约束与限制)\r\n    - [兼容性](#兼容性)\r\n  - [使用示例](#使用示例)\r\n    - [1. 显示基础通知型 Toast（自定义样式）](#1-显示基础通知型-toast自定义样式)\r\n    - [2. 快捷显示 Toast（固定时长与位置）](#2-快捷显示-toast固定时长与位置)\r\n    - [3. 手动隐藏 Toast](#3-手动隐藏-toast)\r\n  - [使用说明](#使用说明)\r\n    - [1. 核心 API 说明](#1-核心-api-说明)\r\n      - [1.1 自定义样式 Toast（核心 API）](#11-自定义样式-toast核心-api)\r\n      - [1.2 快捷显示 Toast API](#12-快捷显示-toast-api)\r\n      - [1.3 手动隐藏 Toast API](#13-手动隐藏-toast-api)\r\n    - [2. 常见问题（FAQ）](#2-常见问题faq)\r\n      - [Q1: 调用插件 API 后无反应怎么办？](#q1-调用插件-api-后无反应怎么办)\r\n      - [Q2: OHOS 平台配置 opacity 参数后无效果怎么办？](#q2-ohos-平台配置-opacity-参数后无效果怎么办)\r\n      - [Q3: toast 显示样式异常（如文字过大、背景色不生效）怎么办？](#q3-toast-显示样式异常如文字过大背景色不生效怎么办)\r\n      - [Q4: 调用 hide() 方法后，toast 未立即隐藏怎么办？](#q4-调用-hide-方法后toast-未立即隐藏怎么办)\r\n      - [Q5: toast 文本过长导致显示异常怎么办？](#q5-toast-文本过长导致显示异常怎么办)\r\n    - [3. 注意事项](#3-注意事项)\r\n  - [目录结构](#目录结构)\r\n  - [贡献代码](#贡献代码)\r\n  - [许可证](#许可证)\r\n  - [官方资源](#官方资源)\r\n\r\n## 简介\r\n\r\n`cordova-plugin-x-toast` 是一款为 Cordova 应用打造的跨平台原生提示框插件，支持显示通知型、操作型、输入型等多种类型的 toast 与对话框，适配各平台原生设计规范。插件具备高度可定制性，可灵活配置提示内容、样式、交互逻辑，满足应用在不同场景下的消息反馈需求，提升用户交互体验。在 OHOS 系统中，插件适配系统原生提示框规范，部分样式参数存在平台特殊性，本文档主要介绍该插件在 OHOS 系统中的应用、安装、配置、使用方法及注意事项，帮助开发者快速集成提示框功能。\r\n\r\n## 功能特性\r\n\r\n- **多平台兼容**：支持 Android 4.4+、iOS 9.0+、Windows 10+、OpenHarmony 5.0+，重点适配 OHOS 系统，遵循系统原生提示框设计规范\r\n\r\n- **多类型提示支持**：覆盖通知型 toast（短/长提示），支持自定义显示时长、位置，满足不同场景的消息反馈需求\r\n\r\n- **高度可定制化**：支持自定义提示文本、字体大小、颜色、背景样式、按钮文案、弹窗位置、显示时长等属性，可精准匹配应用视觉风格；OHOS 平台部分样式参数有特殊限制，需重点关注\r\n\r\n- **灵活交互控制**：支持配置按钮点击回调、输入内容校验、选择结果返回等交互逻辑，满足复杂业务场景的交互需求\r\n\r\n- **轻量级架构**：插件体积小巧（约 50KB），无冗余依赖，集成后不影响应用启动速度与运行性能，对设备资源占用极低\r\n\r\n- **跨平台统一**：统一多平台 API 调用方式，无需针对不同平台编写差异化代码，降低开发成本，提升开发效率\r\n\r\n- **兼容性广泛**：支持低版本系统，覆盖绝大多数移动设备与浏览器环境，适配各类 Cordova 应用场景\r\n\r\n- **双调用方式**：支持 Promise 与回调函数两种调用方式，推荐使用 Promise 简化异步逻辑，降低代码复杂度\r\n\r\n## OHOS 平台特性\r\n\r\n该插件在 OHOS 平台的实现有别于 Android/iOS 平台，核心特性及特殊限制如下，需重点关注：\r\n\r\n- 适配 OHOS 系统原生提示框规范，显示效果与系统原生 toast 保持一致，提升用户体验\r\n\r\n- 样式配置存在特殊限制：opacity（透明度）参数在 OHOS 系统中默认无效，采用系统原生透明度设置\r\n\r\n- 支持 OHOS 系统的弹窗位置、背景色、文本颜色、圆角等核心样式配置，可灵活适配应用视觉设计\r\n\r\n- API 调用逻辑与 Android/iOS 平台一致，无需额外修改代码，仅需注意 OHOS 专属样式限制即可正常使用\r\n\r\n- 支持 toast 快速隐藏功能，可手动控制提示框的显示与隐藏，满足特殊业务场景需求\r\n\r\n## 支持平台\r\n\r\n- **OHOS**（5.0+，适配系统原生提示框规范，支持核心样式配置与交互功能）\r\n\r\n- **Android**（4.4+，调用原生 toast 能力，支持全量样式配置与交互功能）\r\n\r\n- **iOS**（9.0+，适配 iOS 原生提示框规范，支持全量样式配置与交互功能）\r\n\r\n- **Windows**（10+，基础提示功能支持，具体适配细节参考官方文档）\r\n\r\n## 前置准备\r\n\r\n在集成插件前，需确保开发环境满足基础要求，完成必要的前置配置，具体步骤如下：\r\n\r\n- 已安装 Node.js（v14.0.0 及以上）和 npm（v6.0.0 及以上），可通过 `node -v` 和 `npm -v` 命令验证版本；\r\n\r\n- 已全局安装 HCordova CLI（v10.0.0 及以上），用于插件的安装、卸载和管理；\r\n\r\n- 已创建 Cordova 项目（若尚未创建，可通过 `hcordova create MyToastApp com.example.toastapp 提示框示例应用` 命令快速创建）；\r\n\r\n- OHOS 平台需确保应用已获取基础弹窗权限，避免因权限不足导致 toast 无法正常显示；\r\n\r\n- 确保项目适配 OHOS 5.0 及以上版本，避免因系统版本过低导致插件功能异常。\r\n\r\n## 下载安装\r\n\r\n通过 HCordova CLI 即可快速安装插件，支持全平台安装或指定 OHOS 平台安装，安装流程简洁高效，安装后可通过命令验证安装结果。\r\n\r\n### 前提条件\r\n\r\n安装插件前，需先安装 HCordova CLI，执行以下命令安装：\r\n\r\n```bash\r\nnpm install -g hcordova\r\n```\r\n\r\n### 基础安装（推荐）\r\n\r\n在 Cordova 项目根目录执行以下命令，插件会自动处理各平台依赖与基础配置，默认安装最新版本：\r\n\r\n```bash\r\n# 安装最新版本（全平台）\r\nhcordova plugin add cordova-plugin-x-toast\r\n\r\n# 安装指定版本 OHOS 平台\r\nhcordova plugin add cordova-plugin-x-toast --platform ohos\r\n\r\n# 安装指定版本（仅 OHOS 平台）\r\nhcordova plugin add cordova-plugin-x-toast@1.0.0 --platform ohos\r\n```\r\n\r\n### 从 GitCode 源码安装\r\n\r\n若需使用开发中的最新功能，可直接从 GitCode 仓库安装，仅适配 OHOS 平台：\r\n\r\n```bash\r\n# 仅支持 OHOS 平台\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-x-toast.git --platform ohos\r\n\r\n# 指定标签/分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-x-toast.git@develop --platform ohos\r\n```\r\n\r\n### 安装后验证\r\n\r\n安装完成后，可通过以下命令验证插件是否成功添加到项目中：\r\n\r\n```bash\r\n# 查看已安装的插件列表\r\nhcordova plugin list\r\n\r\n# 若输出结果包含 cordova-plugin-x-toast 则表示插件已成功安装\r\n```\r\n\r\n### 离线安装（本地包）\r\n\r\n适用于无网络环境，先下载插件包到本地，再执行离线安装：\r\n\r\n```bash\r\n# 下载插件包到本地（示例路径：~/Downloads/cordova-plugin-x-toast）\r\n# 执行离线安装\r\nhcordova plugin add ~/Downloads/cordova-plugin-x-toast --platform ohos\r\n```\r\n### 安装后验证\r\n\r\n安装完成后，可通过以下命令验证插件是否成功添加到项目中：\r\n\r\n```bash\r\n# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装\r\nhcordova plugin list\r\n```\r\n\r\n\r\n### 卸载插件\r\n\r\n如需移除插件，执行以下命令即可清理相关配置与依赖，支持全平台卸载或指定 OHOS 平台卸载：\r\n\r\n```bash\r\n# 全平台卸载\r\nhcordova plugin remove cordova-plugin-x-toast\r\n\r\n# 指定 OHOS 平台卸载\r\nhcordova plugin remove cordova-plugin-x-toast --platform ohos\r\n```\r\n\r\n## OHOS 配置\r\n\r\nOHOS 平台集成插件后，大部分功能可直接使用，无需额外复杂配置，以下为特殊场景的配置说明及样式参数限制：\r\n\r\n### 1. 基础配置\r\n\r\nOHOS 平台无需额外配置权限（基础弹窗权限默认开启），插件安装后即可正常调用 API 显示 toast，无需修改 module.json5 文件。\r\n\r\n### 2. 样式参数限制说明\r\n\r\nOHOS 平台因系统原生规范限制，部分样式参数存在特殊说明，需重点注意，避免配置无效：\r\n\r\n- opacity（透明度）：该参数在 OHOS 系统中默认无效，toast 透明度采用系统原生设置，无法通过插件自定义；\r\n\r\n- textSize（文字大小）：支持自定义，默认值为 14，建议设置范围为 12-24，避免过大或过小导致显示异常；\r\n\r\n- cornerRadius（圆角）：支持自定义，默认值为 16，建议设置为偶数，贴合 OHOS 系统原生设计风格；\r\n\r\n- horizontalPadding（水平边距）、verticalPadding（垂直边距）：支持自定义，负数表示向内缩进，正数表示向外扩展，需合理设置避免显示溢出；\r\n\r\n- backgroundColor（背景色）、textColor（文本颜色）：支持自定义十六进制颜色值，建议与应用整体视觉风格保持一致。\r\n\r\n## 约束与限制\r\n\r\n- 依赖插件：无强制依赖插件，@cordova-ohos/ohos 版本为 2.0.0 及以上；\r\n\r\n- 平台限制：OHOS 平台仅支持 5.0 及以上版本，低于该版本的系统可能出现 toast 显示异常、API 调用失败等问题；\r\n\r\n- 样式限制：OHOS 平台 opacity 参数无效；\r\n\r\n- API 调用时机：所有 JavaScript API 必须在 `deviceready` 事件触发后调用，否则会出现 `window.plugins.toast` 对象未定义、调用失败等异常；\r\n\r\n- 显示优先级：OHOS 系统中，toast 显示优先级低于系统原生通知，若同时存在多个 toast，会按调用顺序依次显示；\r\n\r\n- 隐藏功能限制：手动调用 hide() 方法可隐藏当前显示的 toast，但已触发显示的 toast 无法取消队列，需等待队列执行完成；\r\n\r\n- 文本长度限制：toast 提示文本建议控制在 50 字符以内，过长文本会自动换行，可能影响显示效果。\r\n\r\n### 兼容性\r\n\r\n支持：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| SDK | API12+ |\r\n| IDE | DevEco Studio: 5.0+ |\r\n| ROM | 5.1+ |\r\n| Emulator | OpenHarmony 6.0+ |\r\n\r\n在以下版本中已测试通过：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 |\r\n| SDK | 5.0.0(12) |\r\n| IDE | DevEco Studio: 6.0.13.200 |\r\n| ROM | 5.1.0.120 SP3 |\r\n| Emulator | OpenHarmony 6.0.1(21) |\r\n\r\n## 使用示例\r\n\r\n插件通过全局对象 `window.plugins.toast` 暴露所有 API，支持 Promise 与回调函数两种调用方式（推荐使用 Promise 简化异步逻辑）。所有 API 需在 `deviceready` 事件触发后调用，以下为各核心功能的完整使用示例，可直接复制到项目中使用，重点注意 OHOS 平台的样式参数限制。\r\n\r\n### 1. 显示基础通知型 Toast（自定义样式）\r\n\r\n用于显示简短操作反馈（如“保存成功”），无交互按钮，自动消失，支持自定义样式，适配 OHOS 平台特性：\r\n\r\n```js\r\n// 等待 Cordova 环境就绪\r\ndocument.addEventListener('deviceready', function() {\r\n    /**\r\n     * 显示基础通知型 Toast\r\n     * @param {Object} options - 配置参数\r\n     * @returns {Promise<void>} - 无返回值，Promise resolved 表示显示完成\r\n     */\r\n    window.plugins.toast.showWithOptions({\r\n        message: \"操作成功\", // 提示文本\r\n        duration: \"short\", // 显示时长：short 2000 ms，long 5000 ms\r\n        position: \"center\", // 显示位置：top、center、bottom\r\n        data:{top:5}, // 额外配置参数，OHOS 平台可忽略\r\n        styling: {\r\n            opacity: 0.75, // OHOS 系统默认，此参数无效\r\n            backgroundColor: '#FF0000', // 背景色，默认 #ffffff\r\n            textColor: '#FFFF00', // 文本颜色，默认 #000000\r\n            textSize: 20.5, // 文字大小，默认 14\r\n            cornerRadius: 16, // 圆角，默认 16\r\n            horizontalPadding: 20, // 左边水平边距\r\n            verticalPadding: -16 // 垂直边距，负数表示向内缩进\r\n        }\r\n    },\r\n    function(args) {\r\n        console.log(\"toast 显示完成:\", args);\r\n    },\r\n    function(error) {\r\n        console.error('toast 显示失败: ', error);\r\n    });\r\n}, false);\r\n```\r\n\r\n### 2. 快捷显示 Toast（固定时长与位置）\r\n\r\n插件提供快捷 API，可快速显示固定时长、固定位置的 toast，无需复杂配置，适合简单场景使用：\r\n\r\n```js\r\n// 等待 Cordova 环境就绪\r\ndocument.addEventListener('deviceready', function() {\r\n    // 短提示（2000ms）- 顶部显示\r\n    window.plugins.toast.showShortTop('顶部短提示', function(a){\r\n        console.log('toast 显示成功: ' + a)\r\n    }, function(b){\r\n        alert('toast 显示失败: ' + b)\r\n    })\r\n\r\n    // 短提示（2000ms）- 中间显示\r\n    window.plugins.toast.showShortCenter('中间短提示', function(a){\r\n        console.log('toast 显示成功: ' + a)\r\n    }, function(b){\r\n        alert('toast 显示失败: ' + b)\r\n    })\r\n\r\n    // 短提示（2000ms）- 底部显示\r\n    window.plugins.toast.showShortBottom('底部短提示', function(a){\r\n        console.log('toast 显示成功: ' + a)\r\n    }, function(b){\r\n        alert('toast 显示失败: ' + b)\r\n    })\r\n\r\n    // 长提示（5000ms）- 顶部显示\r\n    window.plugins.toast.showLongTop('顶部长提示', function(a){\r\n        console.log('toast 显示成功: ' + a)\r\n    }, function(b){\r\n        alert('toast 显示失败: ' + b)\r\n    })\r\n\r\n    // 长提示（5000ms）- 中间显示\r\n    window.plugins.toast.showLongCenter('中间长提示', function(a){\r\n        console.log('toast 显示成功: ' + a)\r\n    }, function(b){\r\n        alert('toast 显示失败: ' + b)\r\n    })\r\n\r\n    // 长提示（5000ms）- 底部显示\r\n    window.plugins.toast.showLongBottom('底部长提示', function(a){\r\n        console.log('toast 显示成功: ' + a)\r\n    }, function(b){\r\n        alert('toast 显示失败: ' + b)\r\n    })\r\n}, false);\r\n```\r\n\r\n### 3. 手动隐藏 Toast\r\n\r\n可手动调用隐藏 API，立即隐藏当前显示的 toast，适合特殊业务场景（如用户快速操作时取消提示）：\r\n\r\n```js\r\n// 等待 Cordova 环境就绪\r\ndocument.addEventListener('deviceready', function() {\r\n    // 先显示一个 toast\r\n    window.plugins.toast.showShortCenter('将在 2 秒后隐藏');\r\n    \r\n    // 2 秒后手动隐藏 toast\r\n    setTimeout(function() {\r\n        window.plugins.toast.hide();\r\n        console.log('toast 已手动隐藏');\r\n    }, 2000);\r\n}, false);\r\n```\r\n\r\n## 使用说明\r\n\r\n以下为插件使用的核心说明，包括 API 详解、参数说明、常见问题及注意事项等，帮助开发者快速上手并避免异常，重点突出 OHOS 平台特性与限制。\r\n\r\n### 1. 核心 API 说明\r\n\r\n插件所有方法均挂载在 `window.plugins.toast` 下，无需额外引入，支持 Promise 与回调函数两种调用方式，所有 API 均需在 `deviceready` 事件触发后调用。\r\n\r\n#### 1.1 自定义样式 Toast（核心 API）\r\n\r\n功能：显示自定义样式的通知型 toast，支持配置显示文本、时长、位置、样式等参数，是插件最核心的 API。\r\n\r\n语法：\r\n\r\n```javascript\r\nwindow.plugins.toast.showWithOptions(options, successCallback, errorCallback);\r\n```\r\n\r\n参数说明：\r\n\r\n- options：配置参数对象，必填，包含以下属性：\r\n        \r\n    - message：提示文本，必填，建议控制在 50 字符以内；\r\n\r\n    - duration：显示时长，可选，值为 \"short\"（2000ms）或 \"long\"（5000ms），默认 \"short\"；\r\n\r\n    - position：显示位置，可选，值为 \"top\"、\"center\"、\"bottom\"，默认 \"center\"；\r\n\r\n    - data：额外配置参数，可选，OHOS 平台可忽略；\r\n\r\n    - styling：样式配置对象，可选，包含 opacity、backgroundColor、textColor、textSize、cornerRadius、horizontalPadding、verticalPadding，其中 OHOS 平台 opacity 无效。\r\n\r\n- successCallback：成功回调，参数为 toast 显示完成的相关信息，触发即表示 toast 已成功显示；\r\n\r\n- errorCallback：失败回调，参数为错误信息，触发即表示 toast 显示失败。\r\n\r\n#### 1.2 快捷显示 Toast API\r\n\r\n功能：快速显示固定时长、固定位置的 toast，无需配置复杂样式，适合简单场景使用，共 6 个快捷方法，分为短提示（2000ms）和长提示（5000ms），每种时长对应 3 个位置。\r\n\r\n语法（以短提示顶部显示为例）：\r\n\r\n```javascript\r\nwindow.plugins.toast.showShortTop(message, successCallback, errorCallback);\r\n```\r\n\r\n参数说明：\r\n\r\n- message：提示文本，必填；\r\n\r\n- successCallback：成功回调，参数为 toast 显示完成的相关信息；\r\n\r\n- errorCallback：失败回调，参数为错误信息。\r\n\r\n快捷方法：\r\n\r\n- 短提示：showShortCenter(message, successCallback, errorCallback)、showShortBottom(message, successCallback, errorCallback)\r\n\r\n- 长提示：showLongTop(message, successCallback, errorCallback)、showLongCenter(message, successCallback, errorCallback)、showLongBottom(message, successCallback, errorCallback)\r\n\r\n#### 1.3 手动隐藏 Toast API\r\n\r\n功能：立即隐藏当前显示的 toast，若存在多个 toast 队列，仅隐藏当前显示的一个，后续 toast 继续按顺序显示。\r\n\r\n语法：\r\n\r\n```javascript\r\nwindow.plugins.toast.hide();\r\n```\r\n\r\n参数说明：无参数，调用后立即执行隐藏操作，无回调函数。\r\n\r\n### 2. 常见问题（FAQ）\r\n\r\n#### Q1: 调用插件 API 后无反应怎么办？\r\n\r\n1. 检查 API 调用时机：确保在 `deviceready` 事件触发后调用，否则 `window.plugins.toast` 对象可能未定义；\r\n\r\n2. 检查插件安装：执行 `hcordova plugin list` 确认插件已成功安装，若未安装则重新执行安装命令；\r\n\r\n3. 检查系统版本：OHOS 平台需确保系统版本为 5.0 及以上，低于该版本会导致功能异常；\r\n\r\n4. 重新构建项目：执行 `hcordova build ohos`，确保插件资源和配置正确加载。\r\n\r\n#### Q2: OHOS 平台配置 opacity 参数后无效果怎么办？\r\n\r\n该问题是 OHOS 平台的原生限制，插件的 opacity 参数在 OHOS 系统中无效，toast 透明度采用系统原生设置，无法通过插件自定义，无需额外配置该参数。\r\n\r\n#### Q3: toast 显示样式异常（如文字过大、背景色不生效）怎么办？\r\n\r\n1. 检查样式参数范围：textSize 建议设置为 12-24，cornerRadius 建议设置为偶数，避免超出系统限制；\r\n\r\n2. 检查颜色格式：backgroundColor、textColor 需传入正确的十六进制颜色值（如 #FF0000），避免格式错误；\r\n\r\n3. 检查边距配置：horizontalPadding、verticalPadding 避免设置过大或过小，防止显示溢出或显示不全。\r\n\r\n#### Q4: 调用 hide() 方法后，toast 未立即隐藏怎么办？\r\n\r\nhide() 方法仅能隐藏当前正在显示的 toast，若存在多个 toast 队列，需等待当前 toast 显示完成后才能隐藏，或确保调用 hide() 时当前有 toast 正在显示。\r\n\r\n#### Q5: toast 文本过长导致显示异常怎么办？\r\n\r\n建议将 toast 提示文本控制在 50 字符以内，过长文本会自动换行，可能导致文字重叠、显示不全，可通过精简文本或使用换行符（\\n）优化显示效果。\r\n\r\n### 3. 注意事项\r\n\r\n- API 调用时机：所有 JavaScript API 必须在 `deviceready` 事件触发后调用，否则会出现对象未定义、调用失败等异常。\r\n\r\n- OHOS 样式限制：opacity 参数在 OHOS 系统中无效，无需配置该参数，避免无效操作。\r\n\r\n- 文本长度控制：toast 提示文本建议控制在 50 字符以内，过长文本会影响显示效果，可适当精简或换行。\r\n\r\n- 版本兼容性：确保 HCordova CLI、cordova-openharmony、OHOS 系统版本符合要求，避免因版本不兼容导致插件功能异常。\r\n\r\n- 显示队列：多个 toast 会按调用顺序形成队列，依次显示，手动隐藏仅影响当前显示的 toast，不影响队列后续执行。\r\n\r\n- 样式适配：OHOS 平台建议遵循系统原生设计风格，textSize、cornerRadius 等参数设置需贴合系统规范，提升用户体验。\r\n\r\n- 错误处理：建议为所有 API 调用添加 errorCallback 回调，便于捕获显示失败的异常，及时排查问题。\r\n\r\n## 目录结构\r\n\r\n```\r\ncordova-plugin-x-toast               # [根目录] Toast 提示插件项目根目录\r\n├── src                              # [源码目录] 存放原生平台代码\r\n│   └── main                         # [主目录] 主代码目录\r\n│       ├── cpp                      # [C++ 目录] C++ 原生代码目录\r\n│       │   └── Toast                # [C++ 模块] Toast 功能 C++ 模块文件夹\r\n│       │       ├── Toast.cpp        # [C++ 实现] C++ 源文件，实现 Toast 显示逻辑\r\n│       │       └── Toast.h          # [C++ 声明] C++ 头文件，定义 Toast 接口\r\n│       └── ets                      # [ArkTS 目录] ArkTS/ETS 代码目录\r\n│           └── components           # [组件目录] 存放 UI 组件\r\n│               └── SpinnerDialog    # [TS 模块] 加载对话框 UI 组件文件夹\r\n│                   └── SpinnerDialog.ets # [ETS 文件] 加载对话框的 UI 组件 Toast 弹窗有需要\r\n├── www                              # [前端目录] 存放供 Web 端调用的 JS 接口文件\r\n│   └── Toast.js                     # [JS 文件] 暴露给 Web 端的 JS 接口\r\n├── .gitignore                       # [配置] Git 版本控制忽略文件配置\r\n├── LICENSE                          # [文本] 开源许可证文件\r\n├── OAT.xml                          # [配置] 门禁配置文件\r\n├── package.json                     # [配置] 项目依赖和元信息配置\r\n├── plugin.xml                       # [配置] Cordova 插件配置文件，定义插件结构和权限\r\n└── README.md                        # [文档] 项目说明文档，介绍插件用法和示例\r\n```\r\n\r\n## 贡献代码\r\n\r\n使用过程中发现任何问题都可以提 [Issue](https://gitcode.com/CPF-Cordova/cordova-plugin-x-toast/issues) ，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/cordova-plugin-x-toast/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **Apache License** 开源，详见 [LICENSE](LICENSE) 文件。\r\n\r\n## 官方资源\r\n\r\n- Android 和 iOS：[cordova-plugin-x-toast 官方指南](https://www.npmjs.com/package/cordova-plugin-x-toast)\r\n\r\n- GitCode 仓库：[https://gitcode.com/CPF-Cordova/cordova-plugin-x-toast](https://gitcode.com/CPF-Cordova/cordova-plugin-x-toast)\r\n","readmeFilename":"README.md"}