往期鸿蒙全套实战文章必看：（附带鸿蒙全栈学习资料）

传感器振动开发指南(ArkTS)

场景介绍

当设备需要设置不同的振动效果时，可以调用Vibrator模块，例如：设备的按键可以设置不同强度和不同时长的振动，闹钟和来电可以设置不同强度和时长的单次或周期振动。

接口说明

名称 描述
startVibration(effect: VibrateEffect, attribute: VibrateAttribute): Promise<void> 根据指定振动效果和振动属性触发马达振动，使用Promise异步回调。
startVibration(effect: VibrateEffect, attribute: VibrateAttribute, callback: AsyncCallback<void>): void 根据指定振动效果和振动属性触发马达振动，使用Callback异步回调。
stopVibration(stopMode: VibratorStopMode): Promise<void> 按照指定模式停止马达的振动，使用Promise异步回调。
stopVibration(stopMode: VibratorStopMode, callback: AsyncCallback<void>): void 按照指定模式停止马达的振动，使用Callback异步回调。
stopVibration(): Promise<void> 停止所有模式的马达振动，使用Promise异步回调。
stopVibration(param?: VibratorInfoParam): Promise<void> 不传参则停止本地设备所有马达的振动，也可传参停止指定马达振动，使用Promise异步回调。
stopVibration(callback: AsyncCallback<void>): void 停止所有模式的马达振动，使用Callback异步回调。
isSupportEffect(effectId: string): Promise<boolean> 查询是否支持传入的参数effectId。返回true则表示支持，否则不支持，使用Promise异步回调。
isSupportEffect(effectId: string, callback: AsyncCallback<boolean>): void 查询是否支持传入的参数effectId。返回true则表示支持，否则不支持，使用Callback异步回调。
getEffectInfoSync(effectId: string, param?: VibratorInfoParam): EffectInfo 同步查询是否支持传入的参数effectId，param可指定具体马达。返回EffectInfo中isEffectSupported字段可判断是否支持。
getVibratorInfoSync(param?: VibratorInfoParam): Array<VibratorInfo> 同步查询一个或所有设备的马达信息列表。返回VibratorInfo包含设备ID、马达ID、设备名称、是否支持高清振动、是否本地设备等信息。
on(type: 'vibratorStateChange', callback: Callback<VibratorStatusEvent>): void 注册马达设备上线下状态变化的监听。callback参数VibratorStatusEvent可返回事件时间戳、设备ID、马达数量、上线或下线等信息。
off(type: 'vibratorStateChange', callback?: Callback<VibratorStatusEvent>): void 注销马达设备上线下状态变化的监听。

振动效果说明

目前支持三类振动效果，如下所示：

名称 说明
固定时长振动 传入一个固定时长，马达按照默认强度和频率触发振动，振动效果描述请参考VibrateTime。
预置振动 系统中的预置振动效果，这些效果适用于某些固定场景，比如效果"haptic.clock.timer"通常用于用户调整计时器时的振感反馈，振动效果描述请参考VibratePreset。
自定义振动 自定义振动提供给用户设计自己所需振动效果的能力，用户可通过自定义振动配置文件，并遵循相应规则编排所需振动形式，使能更加开放的振感交互体验。

自定义振动配置文件为Json格式，在形式上如下所示：

{
    "MetaData": {
        "Create": "2023-01-09",
        "Description": "a haptic case",
        "Version": 1.0,
        "ChannelNumber": 1
    },
    "Channels": [
        {
            "Parameters": {
                "Index": 0
            },
            "Pattern": [
                {
                    "Event": {
                        "Type": "transient",
                        "StartTime": 0,
                        "Parameters": {
                            "Frequency": 31,
                            "Intensity": 100
                        }
                    }
                },
                {
                    "Event": {
                        "Type": "continuous",
                        "StartTime": 40,
                        "Duration": 54,
                        "Parameters": {
                            "Frequency": 30,
                            "Intensity": 38,
                            "Curve": [
                                {
                                    "Time": 0,
                                    "Frequency": 0,
                                    "Intensity": 0
                                },
                                {
                                    "Time": 1,
                                    "Frequency": 15,
                                    "Intensity": 0.5
                                },
                                {
                                    "Time": 40,
                                    "Frequency": -8,
                                    "Intensity": 1.0
                                },
                                {
                                    "Time": 54,
                                    "Frequency": 0,
                                    "Intensity": 0
                                }
                            ]
                        }
                    }
                }
            ]
        }
    ]
}

Json文件共包含3个属性。

  1. "MetaData"属性中为文件头信息，可在如下属性中添加描述：

    名称 必填项 说明
    Version 是 文件格式的版本号，向前兼容，目前支持版本1.0。
    ChannelNumber 是 表示马达振动的通道数，最大支持双马达通道。
    Create 否 可记录文件创作时间。
    Description 否 可指明振动效果、创建信息等附加说明。

  2. "Channels"属性中为马达振动通道的相关信息。

    "Channels"是Json数组，表示各个通道的信息，包含2个属性。

    名称 必填项 说明
    Parameters 是 为通道参数。其中"Index"表示通道编号，0表示全通道发送，1、2分别对应左右马达。
    Pattern 否 马达振动序列。

    "Pattern"是Json数组，包含振动事件序列，每个"Event"属性代表1个振动事件，支持添加2种振动类型。

    振动类型 说明
    transient 瞬态短振动，干脆有力。
    continuous 稳态长振动，具备长时间输出强劲有力振动的能力。

    "Event"表示一个振动事件，包含如下属性：

    名称 必填项 说明
    Type 是 振动事件类型，为"transient" 或"continuous"。
    StartTime 是 振动的起始时间，单位ms，有效范围为[0, 1800,000]。
    Duration 是 振动持续时间，仅当类型为"continuous"时有效，单位ms，有效范围为[0, 5000]。

  3. "Parameters"表示振动事件参数设置，必填项，可设置以下属性参数：

    名称 必填项 说明
    Intensity 是 振动事件强度，有效范围为[0, 100]。
    Frequency 是 振动事件频率，有效范围为[0, 100]。
    Curve 否

    振动曲线，当振动事件类型为"continuous"时有效，为Json数组，支持设置一组调节点，调节点数量最大支持16个，最小为4个，每个调节点需包含如下属性：

    "Time"：相对事件起始时间的偏移，最小为0，最大不能超过事件振动时长；

    "Intensity"：相对事件振动强度的增益，范围为[0, 1]，此值乘上振动事件强度为对应时间点调节后的强度；

    "Frequency"：相对事件振动频率的变化，范围为[-100, 100]，此值加上振动事件频率为对应时间点调节后的频率。

其他要求：

参数 要求
振动事件(event)的数量 不得超过128个。
振动配置文件长度 不得超过64KB。

开发步骤

  1. 控制设备上的振动器，需要申请权限ohos.permission.VIBRATE。

  2. 振动器查询。

情形一 查询所有马达信息：

 import { vibrator } from '@kit.SensorServiceKit';
 import { BusinessError } from '@kit.BasicServicesKit';


try {
  const vibratorInfoList: vibrator.VibratorInfo[] = vibrator.getVibratorInfoSync();
  console.log(`vibratorInfoList: ${JSON.stringify(vibratorInfoList)}`);
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

情形二 查询指定设备的一个或多个马达信息：

 import { vibrator } from '@kit.SensorServiceKit';
 import { BusinessError } from '@kit.BasicServicesKit';


try {
  const vibratorParam: vibrator.VibratorInfoParam = {
    deviceId: 1    // deviceid 需要是查询出来真实存在的设备
  }
  const vibratorInfoList: vibrator.VibratorInfo[] = vibrator.getVibratorInfoSync(vibratorParam);
  console.log(`vibratorInfoList: ${JSON.stringify(vibratorInfoList)}`);
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

  1. 根据指定振动效果和振动属性触发马达振动。

    情形一 按照指定持续时间触发马达振动：

    import { vibrator } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';


try {
  // 触发马达振动
  vibrator.startVibration({
    type: 'time',
    duration: 1000,
  }, {
    id: 0,
    usage: 'alarm'
  }, (error: BusinessError) => {
    if (error) {
      console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    console.info('Succeed in starting vibration');
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

    情形二 按照预置振动效果触发马达振动，可先查询振动效果是否被支持，再调用振动接口：

    import { vibrator } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';


try {
  // 查询是否支持'haptic.effect.soft'
  vibrator.isSupportEffect('haptic.effect.soft', (err: BusinessError, state: boolean) => {
    if (err) {
      console.error(`Failed to query effect. Code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info('Succeed in querying effect');
    if (state) {
      try {
        // 触发马达振动
        vibrator.startVibration({
          type: 'preset',
          effectId: 'haptic.effect.soft',
          count: 1,
          intensity: 50,
        }, {
          usage: 'unknown'
        }, (error: BusinessError) => {
          if (error) {
            console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`);
          } else {
            console.info('Succeed in starting vibration');
          }
        });
      } catch (error) {
        let e: BusinessError = error as BusinessError;
        console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
      }
    }
  })
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

    情形三 按照自定义振动配置文件触发马达振动：

    import { vibrator } from '@kit.SensorServiceKit';
import { resourceManager } from '@kit.LocalizationKit';
import { BusinessError } from '@kit.BasicServicesKit';


const fileName: string = 'xxx.json';


@Entry
@Component
struct Index {
  uiContext = this.getUIContext();


  build() {
    Row() {
      Column() {
        Button('alarm-file')
          .onClick(() => {
            // 获取文件资源描述符
            let rawFd: resourceManager.RawFileDescriptor | undefined = this.uiContext.getHostContext()?.resourceManager.getRawFdSync(fileName);
            if (rawFd != undefined) {
              // 触发马达振动
              try {
                vibrator.startVibration({
                  type: "file",
                  hapticFd: { fd: rawFd.fd, offset: rawFd.offset, length: rawFd.length }
                }, {
                  id: 0,
                  usage: 'alarm' // 根据实际选择类型归属不同的开关管控
                }, (error: BusinessError) => {
                  if (error) {
                    console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`);
                    return;
                  }
                  console.info('Succeed in starting vibration');
                });
              } catch (err) {
                let e: BusinessError = err as BusinessError;
                console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
              }
            }
            // 关闭文件资源描述符
            this.uiContext.getHostContext()?.resourceManager.closeRawFdSync(fileName);
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

  2. 停止马达的振动。

    方式一 按照指定模式停止对应的马达振动，自定义振动不支持此类停止方式：

    ​ 停止固定时长振动：

    import { vibrator } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';


try {
  // 按照VIBRATOR_STOP_MODE_TIME模式停止振动
  vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_TIME, (error: BusinessError) => {
    if (error) {
      console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    console.info('Succeed in stopping vibration');
  })
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

    ​ 停止预置振动：

    import { vibrator } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';


try {
  // 按照VIBRATOR_STOP_MODE_PRESET模式停止振动
  vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET, (error: BusinessError) => {
    if (error) {
      console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    console.info('Succeed in stopping vibration');
  })
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

    方式二 停止所有模式的马达振动，包括自定义振动：

    import { vibrator } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';


try {
  // 停止所有模式的马达振动
  vibrator.stopVibration((error: BusinessError) => {
    if (error) {
      console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    console.info('Succeed in stopping vibration');
  })
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

    方式三 停止指定设备的振动：

    import { vibrator } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';


const vibratorInfoParam: vibrator.VibratorInfoParam = {
  deviceId: 1   // deviceid 需要是查询出来真实存在的设备
}
try {
  vibrator.stopVibration(vibratorInfoParam).then(() => {
    console.info('Succeed in stopping vibration');
  }, (error: BusinessError) => {
    console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

  3. 动态马达状态变化监听。

    注册监听。

    import { vibrator } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';


// 回调函数 
const vibratorStateChangeCallback = (data: vibrator.VibratorStatusEvent) => {
  console.log('vibrator state callback info:', JSON.stringify(data));
}


try {
  // 订阅 vibratorStateChange事件
  vibrator.on('vibratorStateChange', vibratorStateChangeCallback);
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

    取消监听,取消传入的callback需与注册的一致。

    import { vibrator } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';


// 回调函数 
const vibratorStateChangeCallback = (data: vibrator.VibratorStatusEvent) => {
  console.log('vibrator state callback info:', JSON.stringify(data));
}
try {
  // 取消订阅 vibratorStateChange事件
  vibrator.off('vibratorStateChange', vibratorStateChangeCallback);
  // 取消订阅所有 vibratorStateChange事件
  // vibrator.off('vibratorStateChange');
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

​

# harmonyos # 华为 # 鸿蒙系统
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

[鸿蒙2025领航者闯关]HarmonyOS中开发高德地图第二篇：显示第一个地图

avatar HarmonyOS开发者社区
cover

[鸿蒙2025领航者闯关]HarmonyOS中开发高德地图第十篇：综合实战案例

avatar HarmonyOS开发者社区
cover

[鸿蒙2025领航者闯关]HarmonyOS中高德地图第一篇：高德地图SDK集成与初始化

avatar HarmonyOS开发者社区