harmony 鸿蒙Vibrator开发指导

  • 2022-08-09
  • 浏览 (852)

Vibrator开发指导

场景介绍

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

详细的接口介绍请参考Vibrator接口

接口说明

模块 接口名 描述
ohos.vibrator startVibration(effect: VibrateEffect, attribute: VibrateAttribute): Promise<void> 根据指定振动效果和振动属性触发马达振动,使用Promise异步回调。
ohos.vibrator startVibration(effect: VibrateEffect, attribute: VibrateAttribute, callback: AsyncCallback<void>): void 根据指定振动效果和振动属性触发马达振动,使用Callback异步回调。
ohos.vibrator stopVibration(stopMode: VibratorStopMode): Promise<void> 按照指定模式停止马达的振动。
ohos.vibrator stopVibration(stopMode: VibratorStopMode, callback: AsyncCallback<void>): void 按照指定模式停止马达的振动。
ohos.vibrator stopVibration(): Promise<void> 停止所有模式的马达振动。
ohos.vibrator stopVibration(callback: AsyncCallback<void>): void 停止所有模式的马达振动。
ohos.vibrator isSupportEffect(effectId: string): Promise<boolean> 查询是否支持传入的参数effectId。返回true则表示支持,否则不支持
ohos.vibrator isSupportEffect(effectId: string, callback: AsyncCallback<boolean>): void 查询是否支持传入的参数effectId。返回true则表示支持,否则不支持

振动效果说明

目前支持3类振动效果,如下所示。

固定时长振动

传入一个固定时长,马达按照默认强度和频率触发振动,振动效果描述请参考VibrateTime

预置振动

系统中的预置振动效果,这些效果适用于某些固定场景,比如效果”haptic.clock.timer”通常用于用户调整计时器时的振感反馈,振动效果描述请参考VibratePreset

自定义振动

自定义振动提供给用户设计自己所需振动效果的能力,用户可通过自定义振动配置文件,并遵循相应规则编排所需振动形式,使能更加开放的振感交互体验,效果描述请参考VibrateFromFile

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

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

Json文件共包含2个属性。 - “MetaData”属性中为文件头信息,可在如下属性中添加描述。
“Version”:必填项,文件格式的版本号,向前兼容,目前起步仅支持版本1.0;
“ChannelNumber”:必填项,表示马达振动的通道数,目前仅支持单通道,规定为1;
“Create”:可选项,可记录文件创作时间;
“Description”:可选项,可指明振动效果、创建信息等附加说明。
- “Channels”属性中为马达振动通道的相关信息。

“Channels”是Json数组,表示各个通道的信息,包含2个属性。 - “Parameters”属性中为通道参数。
“Index”:必填项,表示通道编号,单通道下规定为1。
- “Pattern”属性中为马达振动序列。

“Pattern”是Json数组,每个”Event”属性代表1个振动事件,支持添加2种振动类型。 - 类型1:”transient”类型,瞬态短振动,干脆有力;
- 类型2:”continuous”类型,稳态长振动,具备长时间输出强劲有力振动的能力。

振动事件参数信息具体如下表:

参数 说明 范围
Type 振动事件类型,必填 “transient” 或”continuous”
StartTime 振动的起始时间,必填 单位ms,有效范围为[0, 1800 000],振动事件不能重叠
Duration 振动持续时间,仅当类型为”continuous”时有效 单位ms,有效范围为(10, 1600)
Intensity 振动强度,必填 有效范围为[0, 100],这里的强度值为相对值,并不代表真实强度
Frequency 振动频率,必填 有效范围为[0, 100],这里的频率值为相对值,并不代表真实频率

其他要求:

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

开发步骤

  1. 控制设备上的振动器,需要申请权限ohos.permission.VIBRATE。具体配置方式请参考权限申请声明

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

  3. 情形一,按照指定持续时间触发马达振动:

import vibrator from '@ohos.vibrator';
import { BusinessError } from '@ohos.base';

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 '@ohos.vibrator';
import { BusinessError } from '@ohos.base';

try {
  // 查询是否支持'haptic.clock.timer'
  vibrator.isSupportEffect('haptic.clock.timer', (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.clock.timer',
          count: 1,
        }, {
          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 '@ohos.vibrator';
import resourceManager from '@ohos.resourceManager';
import { BusinessError } from '@ohos.base';

const fileName: string = 'xxx.json';

// 获取文件资源描述符
let rawFd: resourceManager.RawFileDescriptor = getContext().resourceManager.getRawFdSync(fileName);

// 触发马达振动
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}`);
}

// 关闭文件资源描述符
getContext().resourceManager.closeRawFdSync(fileName);
  1. 停止马达的振动。

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

停止固定时长振动:

import vibrator from '@ohos.vibrator';
import { BusinessError } from '@ohos.base';

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 '@ohos.vibrator';
import { BusinessError } from '@ohos.base';

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 '@ohos.vibrator';
import { BusinessError } from '@ohos.base';

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}`);
}

相关实例

针对振动开发,有以下相关实例可供参考:

你可能感兴趣的鸿蒙文章

harmony 鸿蒙设备管理

harmony 鸿蒙扩展外设管理开发指导

harmony 鸿蒙输入设备开发指导

harmony 鸿蒙位置服务开发指南

harmony 鸿蒙鼠标光标开发指导

harmony 鸿蒙示例服务器开发指导

harmony 鸿蒙示例服务器开发概述

harmony 鸿蒙传感器开发指导

harmony 鸿蒙传感器开发概述

harmony 鸿蒙Stationary开发指导

0  赞