{"_id":"@cordova-ohos/cordova-plugin-spinnerdialog","_rev":"3-a6c015ce886e40e64c06704038a1c137","name":"@cordova-ohos/cordova-plugin-spinnerdialog","dist-tags":{"latest":"1.3.3"},"versions":{"1.3.2":{"name":"@cordova-ohos/cordova-plugin-spinnerdialog","version":"1.3.2","keywords":["cordova","spinnerdialog","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-spinnerdialog@1.3.2","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-spinnerdialog/issues"},"dist":{"shasum":"68d3fe562613db0f646385bafa26a5e47d871b6f","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-spinnerdialog/-/cordova-plugin-spinnerdialog-1.3.2.tgz","fileCount":9,"integrity":"sha512-XvKdTs0IgqeKqH0CCQ+SdM/MPs44WMsAPBPmEqomTnFQNXOZ2y0HXVSm2cYxxxfTBurLgoxIyGXdLeQoaZs8JA==","signatures":[{"sig":"MEUCIEyzzlfGVKK1BuKk2IPPdV+5lAzDmxea1lPoE0ZkvsUZAiEA3lLkZ14/030FxGDM/ZYaq88elCnUJG7ROeEtjGoMHAI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":38873},"cordova":{"id":"cordova-plugin-spinnerdialog","platforms":["ohos"]},"engines":{"cordovaDependencies":{"1.3.2":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"26563742a141edc8647757bdfa6a66d99e86405f","_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/cordova-plugin-spinnerdialog","type":"git"},"_npmVersion":"10.5.1","description":"Cordova spinnerdialog Plugin","directories":{},"_nodeVersion":"22.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cordova-plugin-spinnerdialog_1.3.2_1774227755352_0.6465124616414144","host":"s3://npm-registry-packages-npm-production"}},"1.3.3":{"name":"@cordova-ohos/cordova-plugin-spinnerdialog","version":"1.3.3","description":"Cordova Spinner Dialog Plugin","cordova":{"id":"cordova-plugin-spinnerdialog","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-spinnerdialog"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-spinnerdialog/issues"},"keywords":["cordova","spinnerdialog","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"1.3.3":{"@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-spinnerdialog@1.3.3","gitHead":"4a0a0a44bda88b593f70ffdff28bc54bd233e30c","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-nBlIiImJV+4H4MLS7z7BtFiEzuWp7ZMXBarZAuZZkMUjnGSccOmz5BmTRJesg8OYYFgns6+W5oupysXFeNodbg==","shasum":"4746db11391b2aeeacf111e5c7da99d90b30e395","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-spinnerdialog/-/cordova-plugin-spinnerdialog-1.3.3.tgz","fileCount":10,"unpackedSize":64247,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD9Bfz2IGkHbqK5wQvWzWXKnDAELXaaPuk/JgzWgM3+2wIgL9LYqD0fuuQO+WlB/IAimVh0NFSI9hDl99YN7xvX7I8="}]},"_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-spinnerdialog_1.3.3_1785151957143_0.45175679901274"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-23T01:02:35.298Z","modified":"2026-07-27T11:32:37.552Z","1.3.2":"2026-03-23T01:02:35.501Z","1.3.3":"2026-07-27T11:32:37.289Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-spinnerdialog/issues"},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","spinnerdialog","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-spinnerdialog"},"description":"Cordova Spinner Dialog 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-spinnerdialog</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-spinnerdialog@1.3.2](https://www.npmjs.com/package/cordova-plugin-spinnerdialog/v/1.3.2) 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。\r\n\r\n- [cordova-plugin-spinnerdialog](#cordova-plugin-spinnerdialog)\r\n  - [简介](#简介)\r\n  - [功能特性](#功能特性)\r\n  - [支持平台](#支持平台)\r\n  - [下载安装](#下载安装)\r\n    - [1. 基础版安装（推荐）](#1-基础版安装推荐)\r\n    - [2. 从 GitCode 仓库安装开发版](#2-从-gitcode-仓库安装开发版)\r\n    - [离线安装（本地包）](#离线安装本地包)\r\n    - [安装后验证](#安装后验证)\r\n    - [卸载](#卸载)\r\n  - [约束与限制](#约束与限制)\r\n    - [兼容性](#兼容性)\r\n  - [核心概念](#核心概念)\r\n    - [1. 插件命名空间](#1-插件命名空间)\r\n    - [2. 核心使用场景](#2-核心使用场景)\r\n    - [3. 调用前提](#3-调用前提)\r\n  - [使用示例](#使用示例)\r\n    - [1. 完整使用流程示例](#1-完整使用流程示例)\r\n    - [2. 单独功能调用示例](#2-单独功能调用示例)\r\n  - [使用说明](#使用说明)\r\n    - [核心说明](#核心说明)\r\n    - [API 及参数说明](#api-及参数说明)\r\n      - [1. 核心 API 说明](#1-核心-api-说明)\r\n        - [1.1 显示加载对话框](#11-显示加载对话框)\r\n        - [1.2 关闭加载对话框](#12-关闭加载对话框)\r\n      - [2. 补充说明](#2-补充说明)\r\n  - [目录结构](#目录结构)\r\n  - [贡献代码](#贡献代码)\r\n  - [许可证](#许可证)\r\n  - [官方资源](#官方资源)\r\n\r\n\r\n## 简介\r\n\r\ncordova-plugin-spinnerdialog 是一款为 Cordova 应用打造的轻量级加载对话框插件，支持在应用执行耗时操作（如网络请求、数据处理）时显示原生风格的加载指示器与提示文本，提升用户等待体验。插件适配多平台原生设计规范，支持自定义对话框样式、文字、遮罩层等属性，满足不同应用的视觉需求。\r\n\r\n## 功能特性\r\n\r\n- **原生视觉体验**：遵循 Android（Material Design）、iOS（Human Interface Guidelines）、Windows、OHOS 平台原生设计规范，对话框风格与系统一致\r\n\r\n- **高度可定制**：支持自定义提示文本、加载指示器样式（如圆形旋转、线性进度）、对话框背景色、文字颜色、遮罩层透明度等\r\n\r\n- **轻量级设计**：插件体积小（仅几十 KB），无冗余依赖，集成后不影响应用启动速度与运行性能\r\n\r\n- **灵活控制**：支持显示/隐藏对话框、更新提示文本、设置进度值（部分平台）等操作，满足复杂加载场景\r\n\r\n- **跨平台统一**：统一多平台 API 调用方式，无需针对不同平台编写差异化代码\r\n\r\n- **兼容性强**：支持低版本系统（Android 4.4+、iOS 9.0+、OHOS 5.0+），覆盖绝大多数移动设备\r\n\r\n该插件广泛应用于网络请求加载、文件上传下载、数据解析、页面初始化等耗时操作场景，是提升应用交互流畅度与用户体验的关键工具。\r\n\r\n## 支持平台\r\n\r\n- **Android**：API 19 及以上（Android 4.4+）\r\n\r\n- **iOS**：9.0 及以上\r\n\r\n- **Windows**：适配对应系统版本\r\n\r\n- **OHOS**：5.0+\r\n\r\n## 下载安装\r\n\r\n确保已创建 Cordova 项目，进入项目根目录后通过 hcordova CLI 安装插件，支持从 npm 仓库或 GitCode 仓库获取，安装后插件会自动处理各平台依赖与基础配置。\r\n\r\n### 1. 基础版安装（推荐）\r\n\r\n适用于大多数场景，直接从 npm 仓库安装稳定版：\r\n\r\n```bash\r\n# 安装 hcordova 命令化工具\r\nnpm install -g hcordova\r\n\r\n# 安装最新稳定版插件\r\nhcordova plugin add cordova-plugin-spinnerdialog \r\n\r\n# 安装指定版本（示例：1.0.0 版本）\r\nhcordova plugin add cordova-plugin-spinnerdialog@1.0.0 --platform ohos\r\n```\r\n\r\n### 2. 从 GitCode 仓库安装开发版\r\n\r\n若需使用开发中的最新功能，可直接从 GitCode 仓库安装：\r\n\r\n```bash\r\n# 安装开发版插件（仅 OHOS 平台）\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-spinnerdialog.git --platform ohos\r\n\r\n# 指定标签/分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-spinnerdialog.git@develop --platform ohos\r\n```\r\n\r\n### 离线安装（本地包）\r\n\r\n适用于无网络环境，先下载插件包到本地，再执行离线安装：\r\n\r\n```bash\r\n# 下载插件包到本地（示例路径：../Downloads/cordova-plugin-spinnerdialog）\r\n# 执行离线安装\r\nhcordova plugin add ../Downloads/cordova-plugin-spinnerdialog  --platform ohos\r\n```\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\r\n```bash\r\n# 全平台卸载\r\nhcordova plugin remove cordova-plugin-spinnerdialog\r\n\r\n# 指定 OHOS 平台卸载\r\nhcordova plugin remove cordova-plugin-spinnerdialog --platform ohos\r\n```\r\n\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### 1. 插件命名空间\r\n\r\n插件通过全局对象 `window.plugins.spinnerDialog` 暴露所有 API 方法，所有操作均需通过该命名空间调用，避免与不相关插件冲突。\r\n\r\n### 2. 核心使用场景\r\n\r\n插件主要用于应用执行耗时操作时，显示加载对话框以提示用户等待，常见应用场景包括：\r\n\r\n- 网络请求加载（如接口请求、数据拉取）\r\n\r\n- 文件操作（如文件上传、下载、解析）\r\n\r\n- 数据处理（如大量数据解析、格式化）\r\n\r\n- 页面初始化（如复杂页面渲染、资源加载）\r\n\r\n### 3. 调用前提\r\n\r\n所有 API 需在 Cordova 的 `deviceready` 事件触发后调用，避免因原生接口未初始化导致的调用失败。\r\n\r\n## 使用示例\r\n\r\n插件通过全局对象 `window.plugins.spinnerDialog` 调用所有方法，以下为各核心功能的纯代码使用示例，可直接复制到项目中使用（API 及参数详情见「使用说明」章节）。\r\n\r\n### 1. 完整使用流程示例\r\n\r\n```javascript\r\n// 等待 deviceready 事件触发后调用插件 API\r\ndocument.addEventListener(\"deviceready\", function() {\r\n    // 1. 显示有标题有提示信息的加载对话框\r\n    window.plugins.spinnerDialog.show(\"加载中\", \"正在处理数据，请稍候...\", function(){\r\n        document.getElementById(\"spinnerInfo\").innerHTML = \"加载对话框已关闭\";\r\n    });\r\n\r\n    // 模拟耗时操作（如网络请求、数据处理）\r\n    setTimeout(function() {\r\n        // 2. 耗时操作完成后，关闭加载对话框\r\n        window.plugins.spinnerDialog.hide();\r\n    }, 3000);\r\n}, false);\r\n```\r\n\r\n### 2. 单独功能调用示例\r\n\r\n```javascript\r\n// 1. 显示有标题有信息的 spinner\r\nwindow.plugins.spinnerDialog.show(\"title\", \"message\", function(){\r\n    document.getElementById(\"spinner\").innerHTML = \"关闭成功\";\r\n});\r\n\r\n// 2. 显示有标题、无提示信息的 spinner\r\nwindow.plugins.spinnerDialog.show(\"title\", null, function(){\r\n    document.getElementById(\"spinner\").innerHTML = \"关闭成功\";\r\n});\r\n\r\n// 3. 显示无标题、无提示信息的 spinner\r\nwindow.plugins.spinnerDialog.show(null, null, function(){\r\n    document.getElementById(\"spinner\").innerHTML = \"关闭成功\";\r\n});\r\n\r\n// 4. 关闭加载对话框\r\nwindow.plugins.spinnerDialog.hide();\r\n```\r\n\r\n## 使用说明\r\n\r\n### 核心说明\r\n1. 插件调用：所有 API 均通过全局对象 `window.plugins.spinnerDialog` 调用，无需额外引入，直接调用对应方法即可。\r\n2. 调用前提：所有 API 必须在 `deviceready` 事件触发后调用，否则会因原生接口未初始化导致调用失败。\r\n3. 跨平台说明：插件遵循各平台原生设计规范，无需编写差异化代码，调用方式统一，加载对话框风格与当前系统保持一致。\r\n4. 样式定制：支持自定义提示文本、加载指示器样式、对话框背景色、文字颜色、遮罩层透明度等，可根据应用视觉风格灵活配置。\r\n5. 性能说明：插件体积轻量（仅几十 KB），无冗余依赖，集成后不影响应用启动速度与运行性能，适合各类 Cordova 应用使用。\r\n6. 兼容性说明：确保项目中 Cordova 版本、DevEco Studio 版本及各平台系统版本符合兼容性要求，避免因版本不兼容导致功能异常。\r\n7. 异常处理：若出现 API 调用失败，需检查是否在 `deviceready` 事件后调用，以及插件是否正确安装、权限是否配置到位。\r\n\r\n### API 及参数说明\r\n\r\n#### 1. 核心 API 说明\r\n\r\n##### 1.1 显示加载对话框\r\n\r\nAPI：window.plugins.spinnerDialog.show(title, message, callback)\r\n\r\n说明：用于显示原生风格的加载对话框，可根据需求设置标题、提示信息及关闭回调。\r\n\r\n参数：\r\n\r\n- **title**：可选参数，字符串类型，加载对话框的标题，传 null 则不显示标题\r\n\r\n- **message**：可选参数，字符串类型，加载对话框的提示文本，传 null 则不显示提示信息\r\n\r\n- **callback**：可选参数，回调函数，当对话框关闭时触发，可用于处理关闭后的逻辑（如更新页面提示）\r\n\r\n调用示例：\r\n\r\n- 显示有标题有信息：show(\"加载中\", \"正在处理，请稍候\", callback)\r\n\r\n- 显示有标题无信息：show(\"加载中\", null, callback)\r\n\r\n- 显示无标题无信息：show(null, null, callback)\r\n\r\n##### 1.2 关闭加载对话框\r\n\r\nAPI：window.plugins.spinnerDialog.hide()\r\n\r\n说明：用于关闭已显示的加载对话框，无参数，调用后立即隐藏对话框。\r\n\r\n注意：若未显示对话框，调用该方法不会报错，也不会有任何效果。\r\n\r\n#### 2. 补充说明\r\n\r\n- 加载指示器样式：不同平台默认加载指示器样式不同，遵循各平台原生设计规范，暂不支持自定义指示器类型（部分平台可通过原生配置调整）。\r\n\r\n- 遮罩层：默认显示半透明遮罩层，点击遮罩层不会关闭对话框，避免用户误操作打断耗时操作。\r\n\r\n- 更新提示文本：目前插件暂不支持单独更新提示文本，若需修改提示信息，需先关闭对话框，再重新显示新的提示文本。\r\n\r\n## 目录结构\r\n\r\n```\r\ncordova-plugin-spinnerdialog         # [根目录] 加载对话框插件项目根目录\r\n├── src                              # [源码目录] 存放原生平台代码\r\n│   └── main                         # [主目录] 主代码目录\r\n│       ├── cpp                      # [C++ 目录] C++ 原生代码目录\r\n│       │   └── SpinnerDialog        # [C++ 模块] 加载对话框 C++ 模块文件夹\r\n│       │       ├── SpinnerDialog.cpp # [C++ 实现] C++ 源文件，实现对话框显示/隐藏逻辑\r\n│       │       └── SpinnerDialog.h   # [C++ 声明] C++ 头文件，定义对话框接口\r\n│       └── ets                      # [ArkTS 目录] ArkTS/ETS 代码目录\r\n│           └── components           # [组件目录] 存放 UI 组件\r\n│               └── SpinnerDialog    # [TS 模块] 加载对话框组件文件夹\r\n│                   └── SpinnerDialog.ets # [ETS 文件] 加载框的 UI 界面与交互实现\r\n├── www                              # [前端目录] 存放供 Web 端调用的 JS 接口文件\r\n│   └── spinner.js                   # [JS 文件] 暴露给 Web 端的 JS 接口，用于调用原生加载框\r\n├── .gitignore                       # [配置] Git 版本控制忽略文件配置\r\n├── LICENSE                          # [文本] 开源许可证文件\r\n├── OAT.xml                          # [配置] 门禁配置文件\r\n├── package.json                     # [配置] npm 包配置文件，定义项目元数据和依赖\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-spinnerdialog/issues) ，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/cordova-plugin-spinnerdialog/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **Apache License 2.0** 开源，详见 [LICENSE](LICENSE) 文件。\r\n\r\n## 官方资源\r\n\r\n- **Android 和 iOS**：[cordova-plugin-spinnerdialog 官方指南](https://www.npmjs.com/package/cordova-plugin-spinnerdialog)\r\n\r\n- **GitCode 仓库**：[CPF-Cordova/cordova-plugin-spinnerdialog](https://gitcode.com/CPF-Cordova/cordova-plugin-spinnerdialog)\r\n","readmeFilename":"README.md"}