{"_id":"@capacitor-ohos/haptics","_rev":"2-b36b411f2363afbaaacff7d8a5511874","name":"@capacitor-ohos/haptics","dist-tags":{"latest":"8.0.2"},"versions":{"8.0.1":{"name":"@capacitor-ohos/haptics","version":"8.0.1","keywords":["capacitor","plugin","native"],"author":{"url":"Group","name":"Huawei Device Co., Ltd and iSoftStone Information Technology"},"license":"MIT","_id":"@capacitor-ohos/haptics@8.0.1","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"bugs":{"url":"https://gitcode.com/CPF-Ionic/capacitor-haptics/issues"},"dist":{"shasum":"ada0725f60341123ced18fe7a915fc3b6e025822","tarball":"https://registry.npmjs.org/@capacitor-ohos/haptics/-/haptics-8.0.1.tgz","fileCount":10,"integrity":"sha512-XI1ZRXRrEc5uK31W6ilSVSTNS7MAkpoeL+8Zs3X4etSr7NOAAXopuGP/kz9nPbiB7MFg5pGcz5eJqNmYa8d1OQ==","signatures":[{"sig":"MEYCIQDWVGfM9M+1QzSd7I3JSrVF+yx7Tn3OL7BMz4BqpCHNBwIhAN/fko5sZCQlSLPpA5FGeLUBXCElS4POf3MPHTMCXV2g","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":47977},"gitHead":"121310aaf5b2c1fb618c593142c8a1ff34a7e641","_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"capacitor":{"id":"@capacitor/haptics","platforms":["openharmony"]},"repository":{"url":"gitcode:CPF-Ionic/capacitor-haptics","type":"git"},"_npmVersion":"10.5.1","description":"The Haptics API provides physical feedback to the user through touch or vibration.","directories":{},"_nodeVersion":"22.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/haptics_8.0.1_1777541774812_0.22404391650320266","host":"s3://npm-registry-packages-npm-production"}},"8.0.2":{"name":"@capacitor-ohos/haptics","version":"8.0.2","description":"The Haptics API provides physical feedback to the user through touch or vibration.","capacitor":{"id":"@capacitor/haptics","platforms":["openharmony"]},"repository":{"type":"git","url":"gitcode:CPF-Ionic/capacitor-haptics"},"bugs":{"url":"https://gitcode.com/CPF-Ionic/capacitor-haptics/issues"},"keywords":["capacitor","plugin","native"],"author":{"name":"Huawei Device Co., Ltd and iSoftStone Information Technology","url":"Group"},"license":"MIT","_id":"@capacitor-ohos/haptics@8.0.2","gitHead":"75705f3b52d3dfe9063493dc7305ea15ea08ded0","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-I1QMYcVCHS5xKTDqDEoDad3Vrg+JSMmwhuJwsVX3cwmPfxKp0hOLIto1RQLkb9FCxF0CzvYxdVwyM4mDlNjy8Q==","shasum":"8f45e1eeea82738caac91f19f47815af5d0432f7","tarball":"https://registry.npmjs.org/@capacitor-ohos/haptics/-/haptics-8.0.2.tgz","fileCount":10,"unpackedSize":48001,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCVD5nAGtlqJWOePYd659tegHbqjZUzMqJtNX5bHCBYuQIgHZ3rm3LpQ44Z4/2U885cq6kiSPIsij+57FoTldkoOW0="}]},"_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"directories":{},"maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/haptics_8.0.2_1784791993416_0.940494265585865"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-30T09:36:14.738Z","modified":"2026-07-23T07:33:13.701Z","8.0.1":"2026-04-30T09:36:14.974Z","8.0.2":"2026-07-23T07:33:13.545Z"},"bugs":{"url":"https://gitcode.com/CPF-Ionic/capacitor-haptics/issues"},"author":{"name":"Huawei Device Co., Ltd and iSoftStone Information Technology","url":"Group"},"license":"MIT","keywords":["capacitor","plugin","native"],"repository":{"type":"git","url":"gitcode:CPF-Ionic/capacitor-haptics"},"description":"The Haptics API provides physical feedback to the user through touch or vibration.","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"readme":"# <center>@capacitor/haptics</center>\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本项目基于 [@capacitor/haptics@8.0.0](https://www.npmjs.com/package/@capacitor/haptics/v/8.0.0) 开发。\r\n\r\n## 简介\r\n\r\n@capacitor/haptics是capacitor生态系统中的核心插件，提供了调用设备震动反馈功能的标准化方法，可实现撞击反馈、通知反馈、自定义时长震动、选择器反馈四类核心交互场景。插件兼容Android、iOS原生平台特性，同时支持浏览器环境，本文档主要说明在OpenHarmony系统中使用。\r\n\r\nAPI提供了触发设备震动反馈的方法，用于实现物理触感交互增强。\r\n\r\n## 支持平台\r\n\r\n- **OpenHarmony**：5.0+\r\n\r\n## 下载安装\r\n\r\n通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。\r\n\r\n### 命令行安装（推荐）\r\n\r\n安装hionic CLI：\r\n\r\n```bash\r\nnpm install -g hionic\r\n```\r\n\r\n以下两种方式中**任选其一**即可，无需重复操作：\r\n\r\nnpm安装：\r\n\r\n```bash\r\n# 安装插件\r\nnpm install @capacitor/haptics\r\n\r\n# 同步插件\r\nhionic sync openharmony\r\n```\r\n\r\nhionic CLI安装：\r\n\r\n```bash\r\nhionic plugin add @capacitor/haptics\r\n```\r\n\r\n### 手动引入安装\r\n\r\n根据插件源码中 `plugin.xml` 配置在项目中引入插件：\r\n\r\n#### 1. 添加插件配置\r\n\r\n根据 `plugin.xml` 的 `config-json` 项，通过 `target` 字段找到 `entry` 模块中 `capacitor.plugins.json` 文件，并根据 `param`\r\n标签添加配置如下：\r\n\r\n```json\r\n{\r\n  \"pkg\": \"@capacitor/haptics\",\r\n  \"classpath\": \"Haptics\"\r\n}\r\n```\r\n\r\n#### 2. 修改 CMake 配置\r\n\r\n根据 `plugin.xml` 的 `CMakeLists` 项，通过 `modules-name` 字段找到模块 `capacitor`，路径为 `target` 字段的\r\n`CMakeLists.txt` 文件，并添加 `add_subdirectory` 和 `target_link_libraries` 如下：\r\n\r\n```cmake\r\n#START_ADD_SUBDIRECTORY\r\n// ...\r\nadd_subdirectory(Haptics)\r\n// ...\r\n#END_ADD_SUBDIRECTORY\r\n\r\n// ...\r\n\r\ntarget_link_libraries(capacitor PUBLIC\r\n  \"-Wl,--whole-archive\"\r\n  // ...\r\n  Haptics\r\n  // ...\r\n  \"-Wl,--no-whole-archive\"\r\n)\r\n```\r\n\r\n#### 3. 复制源码文件\r\n\r\n根据 `plugin.xml` 的 `source-file` 项，根据 `src` 字段找到需要复制的文件，并根据 `modules-name` 字段和 `target-dir`\r\n字段找到文件复制的具体模块和目录：\r\n\r\n将源码中src/main/cpp/Haptics目录下的Haptics.h、Haptics.cpp、CMakeLists.txt文件引入到capacitor模块中src/main/cpp/Haptics目录下，\r\n\r\n将源码中src/main/ets/components/Haptics目录下的Haptics.ets文件引入到capacitor模块中src/main/ets/components/Haptics目录下。\r\n\r\n#### 4. 添加 ArkTS 配置\r\n\r\n在`capacitor`模块的`build-profile.json5`文件中，`buildOption/arkOptions/runtimeOnly/sources`配置项数组中加入步骤 3 中拷贝的\r\nets 文件路径：\r\n\r\n```json\r\n{\r\n  \"buildOption\": {\r\n    // ...\r\n    \"arkOptions\": {\r\n      \"runtimeOnly\": [\r\n        // ...\r\n        \"./src/main/ets/components/Haptics/Haptics.ets\"\r\n        // ...\r\n      ]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## 卸载\r\n\r\n```bash\r\n# 卸载 haptics 插件\r\nhionic plugin remove @capacitor/haptics\r\n```\r\n\r\n## 约束与限制\r\n\r\n### 兼容性\r\n\r\n在以下版本中已测试通过：\r\n\r\n1. capacitor: 8.0.0-ohos-8.0.0;SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;\r\n\r\n### 权限要求\r\n\r\nOpenHarmony应用权限添加参考[申请应用权限](https://docs.openharmony.cn/pages/v6.0/zh-cn/application-dev/security/AccessToken/declare-permissions.md)\r\n，在主工程的\r\n`module.json5`的requestPermissions添加ohos.permission.VIBRATE权限,示例如下：\r\n\r\n```json\r\n{\r\n  \"name\": \"ohos.permission.VIBRATE\"\r\n}\r\n```\r\n\r\n## 使用示例\r\n\r\n### 示例1：撞击类震动反馈（Impact）\r\n\r\n实现轻/中/重三种强度的撞击震动，适用于按钮点击、元素碰撞等场景。\r\n\r\n```typescript\r\n// 导入 Haptics 模块\r\nimport { Haptics, ImpactStyle } from '@capacitor/haptics';\r\n\r\n// 重型撞击震动\r\nconst triggerHeavyImpact = async () => {\r\n  try {\r\n    await Haptics.impact({ style: ImpactStyle.Heavy });\r\n    console.log('重型撞击震动已触发');\r\n  } catch (error) {\r\n    console.error('震动触发失败：', error);\r\n  }\r\n};\r\n\r\n// 轻型撞击震动\r\nconst triggerLightImpact = async () => {\r\n  try {\r\n    await Haptics.impact({ style: ImpactStyle.Light });\r\n    console.log('轻型撞击震动已触发');\r\n  } catch (error) {\r\n    console.error('震动触发失败：', error);\r\n  }\r\n};\r\n```\r\n\r\n### 示例2：通知类震动反馈（Notification）\r\n\r\n实现成功、警告、错误三种类型的通知震动，适用于操作结果提示场景。\r\n\r\n```typescript\r\n// 导入 Haptics 模块\r\nimport { Haptics, NotificationType } from '@capacitor/haptics';\r\n\r\n// 成功通知震动\r\nconst triggerSuccessNotification = async () => {\r\n  try {\r\n    await Haptics.notification({ type: NotificationType.Success });\r\n    console.log('成功通知震动已触发');\r\n  } catch (error) {\r\n    console.error('震动触发失败：', error);\r\n  }\r\n};\r\n\r\n// 错误通知震动\r\nconst triggerErrorNotification = async () => {\r\n  try {\r\n    await Haptics.notification({ type: NotificationType.Error });\r\n    console.log('错误通知震动已触发');\r\n  } catch (error) {\r\n    console.error('震动触发失败：', error);\r\n  }\r\n};\r\n```\r\n\r\n### 示例3：自定义时长震动（Vibrate）\r\n\r\n自定义震动持续时间，满足个性化震动需求。\r\n\r\n```typescript\r\n// 导入 Haptics 模块\r\nimport { Haptics } from '@capacitor/haptics';\r\n\r\n// 触发 500ms 的自定义震动\r\nconst triggerCustomVibration = async () => {\r\n  try {\r\n    await Haptics.vibrate({ duration: 500 });\r\n    console.log('500ms 自定义震动已触发');\r\n  } catch (error) {\r\n    console.error('震动触发失败：', error);\r\n  }\r\n};\r\n```\r\n\r\n### 示例4：选择操作的震动反馈\r\n\r\n适用于选择器、滚轮切换等连续选择场景的轻量反馈。\r\n\r\n```typescript\r\n// 导入 Haptics 模块\r\nimport { Haptics } from '@capacitor/haptics';\r\n\r\n// 开始选择操作\r\nconst startSelection = async () => {\r\n  try {\r\n    await Haptics.selectionStart();\r\n    console.log('选择操作已开始');\r\n  } catch (error) {\r\n    console.error('选择开始失败：', error);\r\n  }\r\n};\r\n\r\n// 选择项切换时触发震动\r\nconst onSelectionChange = async () => {\r\n  try {\r\n    await Haptics.selectionChanged();\r\n    console.log('选择项切换，触发轻震反馈');\r\n  } catch (error) {\r\n    console.error('选择切换震动失败：', error);\r\n  }\r\n};\r\n\r\n// 结束选择操作\r\nconst endSelection = async () => {\r\n  try {\r\n    await Haptics.selectionEnd();\r\n    console.log('选择操作已结束');\r\n  } catch (error) {\r\n    console.error('选择结束失败：', error);\r\n  }\r\n};\r\n```\r\n\r\n## 使用说明\r\n\r\n引入@capacitor/haptics插件的Haptics模块使用，所有API均基于Promise实现，支持异步调用。\r\n\r\n### 1. 撞击震动（Impact）\r\n\r\n触发不同强度的撞击类震动反馈，适配按钮点击、UI元素碰撞等场景。\r\n\r\n#### 方法签名\r\n\r\n```\r\nimpact(options: ImpactOptions): Promise<void>\r\n```\r\n\r\n#### 参数说明\r\n\r\n| 参数名     | 类型                              | 说明                 |\r\n|---------|---------------------------------|--------------------|\r\n| options | [ImpactOptions](#impactoptions) | 必选，撞击震动配置参数，包含风格属性 |\r\n\r\n#### ImpactOptions\r\n\r\n| 属性名   | 类型                          | 说明     | 默认值               |\r\n|-------|-----------------------------|--------|-------------------|\r\n| style | [ImpactStyle](#impactstyle) | 撞击震动风格 | ImpactStyle.Heavy |\r\n\r\n### 2. 通知震动（Notification）\r\n\r\n触发任务结果类的通知震动，区分成功、警告、错误三种类型。\r\n\r\n#### 方法签名\r\n\r\n```\r\nnotification(options: NotificationOptions): Promise<void>\r\n```\r\n\r\n#### 参数说明\r\n\r\n| 参数名     | 类型                                          | 说明                 |\r\n|---------|---------------------------------------------|--------------------|\r\n| options | [NotificationOptions](#notificationoptions) | 必选，通知震动配置参数，包含类型属性 |\r\n\r\n#### NotificationOptions\r\n\r\n| 属性名  | 类型                                    | 说明     | 默认值                      |\r\n|------|---------------------------------------|--------|--------------------------|\r\n| type | [NotificationType](#notificationtype) | 通知震动类型 | NotificationType.Success |\r\n\r\n### 3. 自定义震动（Vibrate）\r\n\r\n触发指定时长的基础震动，支持毫秒级自定义配置。\r\n\r\n#### 方法签名\r\n\r\n```\r\nvibrate(options: VibrateOptions): Promise<void>\r\n```\r\n\r\n#### 参数说明\r\n\r\n| 参数名     | 类型                                | 说明                  |\r\n|---------|-----------------------------------|---------------------|\r\n| options | [VibrateOptions](#vibrateoptions) | 必选，自定义震动配置参数，包含时长属性 |\r\n\r\n#### VibrateOptions\r\n\r\n| 属性名      | 类型     | 说明                            | 默认值 |\r\n|----------|--------|-------------------------------|-----|\r\n| duration | number | 震动持续时间，单位：毫秒。若传入值 <= 0 则使用默认值 | 300 |\r\n\r\n### 4. 选择器反馈（Selection）\r\n\r\n专为连续选择操作设计的轻量震动反馈，包含三个关联方法。\r\n\r\n#### 方法签名\r\n\r\n```\r\nselectionStart(): Promise<void>\r\nselectionChanged(): Promise<void>\r\nselectionEnd(): Promise<void>\r\n```\r\n\r\n#### 使用规则\r\n\r\n1. 先调用selectionStart()标记选择开始；\r\n\r\n2. 切换选项时调用selectionChanged()触发震动；\r\n\r\n3. 选择完成后调用selectionEnd()标记结束。\r\n\r\n## 枚举类型\r\n\r\n### ImpactStyle\r\n\r\n撞击震动风格枚举\r\n\r\n| 成员名    | 值        | 说明             |\r\n|--------|----------|----------------|\r\n| Heavy  | 'HEAVY'  | 重型撞击，适用于大元素交互  |\r\n| Medium | 'MEDIUM' | 中型撞击，通用型交互反馈   |\r\n| Light  | 'LIGHT'  | 轻型撞击，适用于小元素/轻触 |\r\n\r\n### NotificationType\r\n\r\n通知震动类型枚举\r\n\r\n| 成员名     | 值         | 说明        |\r\n|---------|-----------|-----------|\r\n| Success | 'SUCCESS' | 操作成功反馈    |\r\n| Warning | 'WARNING' | 操作警告反馈    |\r\n| Error   | 'ERROR'   | 操作失败/错误反馈 |\r\n\r\n## 目录结构\r\n\r\n```plaintext\r\n|---- 目录\r\n|     |---- src/main  # 插件的实现代码\r\n|           |----cpp  # C++ 代码\r\n|           |----ets   # ArkTS 代码\r\n|     |---- README.md          # 说明文档\r\n|     |---- package.json       # 配置文件\r\n|     |---- plugin.xml       # 插件配置文件\r\n```\r\n\r\n## 贡献代码\r\n\r\n使用过程中发现任何问题都可以提 [Issue](https://gitcode.com/CPF-Ionic/capacitor-haptics/issues)\r\n，当然，也非常欢迎发 [PR](https://gitcode.com/CPF-Ionic/capacitor-haptics/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **MIT License** 开源，详见 [LICENSE](./LICENSE) 文件。","readmeFilename":"README.md"}