@capacitor/haptics

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

简介

@capacitor/haptics是capacitor生态系统中的核心插件，提供了调用设备震动反馈功能的标准化方法，可实现撞击反馈、通知反馈、自定义时长震动、选择器反馈四类核心交互场景。插件兼容Android、iOS原生平台特性，同时支持浏览器环境，本文档主要说明在OpenHarmony系统中使用。

API提供了触发设备震动反馈的方法，用于实现物理触感交互增强。

支持平台

• OpenHarmony：5.0+

下载安装

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

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

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

npm安装：

# 安装插件
npm install @capacitor/haptics

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/haptics

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

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

{
  "pkg": "@capacitor/haptics",
  "classpath": "Haptics"
}

2. 修改 CMake 配置

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

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

// ...

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

3. 复制源码文件

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

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

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

4. 添加 ArkTS 配置

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

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

卸载

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

约束与限制

兼容性

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

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;

权限要求

OpenHarmony应用权限添加参考申请应用权限 ，在主工程的 module.json5的requestPermissions添加ohos.permission.VIBRATE权限,示例如下：

{
  "name": "ohos.permission.VIBRATE"
}

使用示例

示例1：撞击类震动反馈（Impact）

实现轻/中/重三种强度的撞击震动，适用于按钮点击、元素碰撞等场景。

// 导入 Haptics 模块
import { Haptics, ImpactStyle } from '@capacitor/haptics';

// 重型撞击震动
const triggerHeavyImpact = async () => {
  try {
    await Haptics.impact({ style: ImpactStyle.Heavy });
    console.log('重型撞击震动已触发');
  } catch (error) {
    console.error('震动触发失败：', error);
  }
};

// 轻型撞击震动
const triggerLightImpact = async () => {
  try {
    await Haptics.impact({ style: ImpactStyle.Light });
    console.log('轻型撞击震动已触发');
  } catch (error) {
    console.error('震动触发失败：', error);
  }
};

示例2：通知类震动反馈（Notification）

实现成功、警告、错误三种类型的通知震动，适用于操作结果提示场景。

// 导入 Haptics 模块
import { Haptics, NotificationType } from '@capacitor/haptics';

// 成功通知震动
const triggerSuccessNotification = async () => {
  try {
    await Haptics.notification({ type: NotificationType.Success });
    console.log('成功通知震动已触发');
  } catch (error) {
    console.error('震动触发失败：', error);
  }
};

// 错误通知震动
const triggerErrorNotification = async () => {
  try {
    await Haptics.notification({ type: NotificationType.Error });
    console.log('错误通知震动已触发');
  } catch (error) {
    console.error('震动触发失败：', error);
  }
};

示例3：自定义时长震动（Vibrate）

自定义震动持续时间，满足个性化震动需求。

// 导入 Haptics 模块
import { Haptics } from '@capacitor/haptics';

// 触发 500ms 的自定义震动
const triggerCustomVibration = async () => {
  try {
    await Haptics.vibrate({ duration: 500 });
    console.log('500ms 自定义震动已触发');
  } catch (error) {
    console.error('震动触发失败：', error);
  }
};

示例4：选择操作的震动反馈

适用于选择器、滚轮切换等连续选择场景的轻量反馈。

// 导入 Haptics 模块
import { Haptics } from '@capacitor/haptics';

// 开始选择操作
const startSelection = async () => {
  try {
    await Haptics.selectionStart();
    console.log('选择操作已开始');
  } catch (error) {
    console.error('选择开始失败：', error);
  }
};

// 选择项切换时触发震动
const onSelectionChange = async () => {
  try {
    await Haptics.selectionChanged();
    console.log('选择项切换，触发轻震反馈');
  } catch (error) {
    console.error('选择切换震动失败：', error);
  }
};

// 结束选择操作
const endSelection = async () => {
  try {
    await Haptics.selectionEnd();
    console.log('选择操作已结束');
  } catch (error) {
    console.error('选择结束失败：', error);
  }
};

使用说明

引入@capacitor/haptics插件的Haptics模块使用，所有API均基于Promise实现，支持异步调用。

1. 撞击震动（Impact）

触发不同强度的撞击类震动反馈，适配按钮点击、UI元素碰撞等场景。

方法签名

impact(options: ImpactOptions): Promise<void>

参数说明

| 参数名 | 类型 | 说明 | |---------|---------------------------------|--------------------| | options | ImpactOptions | 必选，撞击震动配置参数，包含风格属性 |

ImpactOptions

| 属性名 | 类型 | 说明 | 默认值 | |-------|-----------------------------|--------|-------------------| | style | ImpactStyle | 撞击震动风格 | ImpactStyle.Heavy |

2. 通知震动（Notification）

触发任务结果类的通知震动，区分成功、警告、错误三种类型。

方法签名

notification(options: NotificationOptions): Promise<void>

参数说明

| 参数名 | 类型 | 说明 | |---------|---------------------------------------------|--------------------| | options | NotificationOptions | 必选，通知震动配置参数，包含类型属性 |

NotificationOptions

| 属性名 | 类型 | 说明 | 默认值 | |------|---------------------------------------|--------|--------------------------| | type | NotificationType | 通知震动类型 | NotificationType.Success |

3. 自定义震动（Vibrate）

触发指定时长的基础震动，支持毫秒级自定义配置。

方法签名

vibrate(options: VibrateOptions): Promise<void>

参数说明

| 参数名 | 类型 | 说明 | |---------|-----------------------------------|---------------------| | options | VibrateOptions | 必选，自定义震动配置参数，包含时长属性 |

VibrateOptions

| 属性名 | 类型 | 说明 | 默认值 | |----------|--------|-------------------------------|-----| | duration | number | 震动持续时间，单位：毫秒。若传入值 <= 0 则使用默认值 | 300 |

4. 选择器反馈（Selection）

专为连续选择操作设计的轻量震动反馈，包含三个关联方法。

方法签名

selectionStart(): Promise<void>
selectionChanged(): Promise<void>
selectionEnd(): Promise<void>

使用规则

1. 先调用selectionStart()标记选择开始；

2. 切换选项时调用selectionChanged()触发震动；

3. 选择完成后调用selectionEnd()标记结束。

枚举类型

ImpactStyle

撞击震动风格枚举

| 成员名 | 值 | 说明 | |--------|----------|----------------| | Heavy | 'HEAVY' | 重型撞击，适用于大元素交互 | | Medium | 'MEDIUM' | 中型撞击，通用型交互反馈 | | Light | 'LIGHT' | 轻型撞击，适用于小元素/轻触 |

NotificationType

通知震动类型枚举

| 成员名 | 值 | 说明 | |---------|-----------|-----------| | Success | 'SUCCESS' | 操作成功反馈 | | Warning | 'WARNING' | 操作警告反馈 | | Error | 'ERROR' | 操作失败/错误反馈 |

目录结构

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

贡献代码

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

许可证

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