openharmony 鸿蒙 js-apis-vibrator

2025-06-16 浏览 (1)

@ohos.vibrator (振动)

vibrator模块提供控制设备马达振动的能力。包括启动指定时长、预置效果、自定义文件等模式的振动；停止指定时长、预置效果或所有模式的振动。

说明：

本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

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

vibrator.startVibration9+

startVibration(effect: VibrateEffect, attribute: VibrateAttribute, callback: AsyncCallback<void>): void

根据指定的振动效果和振动属性触发马达振动。使用callback异步回调。

需要权限：ohos.permission.VIBRATE

原子化服务API：从API Version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Sensors.MiscDevice

参数：

参数名类型必填说明
effectVibrateEffect是马达振动效果，支持四种：
1、VibratePreset：按照预置振动效果触发马达振动，适用于交互反馈类的短振场景（如点击长按，滑动，拖拽等），为确保与系统整体振感反馈体验风格一致，推荐使用此接口；
2、VibrateFromFile：按照文件形式定制自定义振动效果触发马达振动，适用于匹配复杂场景效果的交互反馈（如表情包触发的拟真效果、游戏场景/操作反馈）；
3、VibrateTime：按照指定时长触发马达振动，仅对振动时长进行启动或停止控制，满足基础功能，无法对振动强度、频率等维度进行个性化设置，此种振动调节不够细腻，无法满足精致体验；
4、VibrateFromPattern18+：按照自定义振动效果触发马达振动。使用场景和VibrateFromFile一致。VibrateFromFile是面向文件中提前定制好的效果，将具体的振动事件以文件描述符形式传递到接口中；VibrateFromPattern提供更加灵活的振动事件排列组合，将振动事件以振动事件数组的形式传递到接口中。
attributeVibrateAttribute是马达振动属性。
callbackAsyncCallback<void>是回调函数。当马达振动成功，err为undefined；否则为错误对象，包含错误码和错误信息。

错误码：

以下错误码的详细介绍请参见振动错误码和通用错误码。

错误码ID错误信息
201Permission denied.
401Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed.
801Capability not supported.
14600101Device operation failed.

示例：

1.按照预置振动效果触发马达振动：

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

try {
  // 查询是否支持'haptic.notice.success'
  vibrator.isSupportEffect('haptic.notice.success', (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.notice.success',
          count: 1,
        }, {
          usage: 'notification' // 根据实际选择类型归属不同的开关管控
        }, (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}`);
      }
    }
  })
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

2.按照自定义振动配置文件触发马达振动：

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%')
  }
}

3.按照指定时长触发马达振动：

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

vibrator.startVibration9+

startVibration(effect: VibrateEffect, attribute: VibrateAttribute): Promise<void>

根据指定的振动效果和振动属性触发马达振动。使用promise异步回调。

需要权限：ohos.permission.VIBRATE

原子化服务API：从API Version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Sensors.MiscDevice

参数：

参数名类型必填说明
effectVibrateEffect是马达振动效果，支持四种：
1、VibrateTime：按照预置振动效果触发马达振动，适用于交互反馈类的短振场景（如点击长按，滑动，拖拽等），为确保与系统整体振感反馈体验风格一致，推荐使用此接口；
2、VibratePreset：按照文件形式定制自定义振动效果触发马达振动，适用于匹配复杂场景效果的交互反馈（如表情包触发的拟真效果、游戏场景/操作反馈）；
3、VibrateFromFile：按照指定时长触发马达振动，仅对振动时长进行启动或停止控制，满足基础功能，无法对振动强度、频率等维度进行个性化设置，此种振动调节不够细腻，无法满足精致体验；
4、VibrateFromPattern18+：按照自定义振动效果触发马达振动。使用场景和VibrateFromFile一致。VibrateFromFile是面向文件中提前定制好的效果，将具体的振动事件以文件描述符形式传递到接口中；VibrateFromPattern提供更加灵活的振动事件排列组合，将振动事件以振动事件数组的形式传递到接口中。
attributeVibrateAttribute是马达振动属性。

返回值：

类型说明
Promise<void>无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见振动错误码和通用错误码。

错误码ID错误信息
201Permission denied.
401Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed.
801Capability not supported.
14600101Device operation failed.

示例：

1.按照预置振动效果触发马达振动：

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

try {
  // 查询是否支持'haptic.notice.success'
  vibrator.isSupportEffect('haptic.notice.success', (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.notice.success',
          count: 1,
        }, {
          usage: 'notification' // 根据实际选择类型归属不同的开关管控
        }, (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}`);
      }
    }
  })
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

2.按照自定义振动配置文件触发马达振动：

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%')
  }
}

3.按照指定时长触发马达振动：

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

try {
  vibrator.startVibration({
    type: 'time',
    duration: 1000
  }, {
    id: 0,
    usage: 'alarm' // 根据实际选择类型归属不同的开关管控
  }).then(() => {
    console.info('Succeed in starting vibration');
  }, (error: BusinessError) => {
    console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`);
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

vibrator.stopVibration9+

stopVibration(stopMode: VibratorStopMode, callback: AsyncCallback<void>): void

按照指定模式停止马达振动。使用callback异步回调。

需要权限：ohos.permission.VIBRATE

系统能力：SystemCapability.Sensors.MiscDevice

参数：

参数名类型必填说明
stopModeVibratorStopMode是指定的停止振动模式，支持两种：
VIBRATOR_STOP_MODE_TIME：停止固定时长振动；
VIBRATOR_STOP_MODE_PRESET：停止预置振动。
此接口无法停止自定义振动，请使用vibrator.stopVibration10+。
callbackAsyncCallback<void>是回调函数，当马达停止振动成功，err为undefined，否则为错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID错误信息
201Permission denied.
401Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed.

示例：

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

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

2.停止预置振动：

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

try {
  // 按照预置效果振动
  vibrator.startVibration({
    type: 'preset',
    effectId: 'haptic.notice.success',
    count: 1,
  }, {
    id: 0,
    usage: 'notification' // 根据实际选择类型归属不同的开关管控
  }, (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}`);
}

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

vibrator.stopVibration9+

stopVibration(stopMode: VibratorStopMode): Promise<void>

按照指定模式停止马达的振动。使用promise异步回调。

需要权限：ohos.permission.VIBRATE

系统能力：SystemCapability.Sensors.MiscDevice

参数：

参数名类型必填说明
stopModeVibratorStopMode是支持停止两种指定的振动模式：
VIBRATOR_STOP_MODE_TIME：停止指定时长振动；
VIBRATOR_STOP_MODE_PRESET：停止预置振动。
此接口无法停止自定义振动，请使用vibrator.stopVibration10+。

返回值：

类型说明
Promise<void>Promise对象。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID错误信息
201Permission denied.
401Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed.

示例：

1.停止指定时长振动：

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

try {
  // 按照指定时长振动
  vibrator.startVibration({
    type: 'time',
    duration: 1000,
  }, {
    id: 0,
    usage: 'alarm' // 根据实际选择类型归属不同的开关管控
  }).then(() => {
    console.info('Succeed in starting vibration');
  }, (error: BusinessError) => {
    console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`);
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

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

2.停止预置振动：

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

try {
  // 按照预置效果振动
  vibrator.startVibration({
    type: 'preset',
    effectId: 'haptic.notice.success',
    count: 1,
  }, {
    id: 0,
    usage: 'notification' // 根据实际选择类型归属不同的开关管控
  }).then(() => {
    console.info('Succeed in starting vibration');
  }, (error: BusinessError) => {
    console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`);
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

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

vibrator.stopVibration10+

stopVibration(callback: AsyncCallback<void>): void

停止所有模式的马达振动。使用callback异步回调。

需要权限：ohos.permission.VIBRATE

原子化服务API：从API Version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Sensors.MiscDevice

参数：

参数名类型必填说明
callbackAsyncCallback<void>是回调函数，当马达停止振动成功，err为undefined，否则为错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID错误信息
201Permission denied.

示例：

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

vibrator.stopVibration10+

stopVibration(): Promise<void>

停止所有模式的马达振动。使用promise异步回调。

需要权限：ohos.permission.VIBRATE

原子化服务API：从API Version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Sensors.MiscDevice

返回值：

类型说明
Promise<void>Promise对象。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID错误信息
201Permission denied.

示例：

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

try {
  // 停止所有模式的马达振动
  vibrator.stopVibration().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}`);
}

vibrator.stopVibrationSync12+

stopVibrationSync(): void

停止任何形式的马达振动。

需要权限：ohos.permission.VIBRATE

原子化服务API：从API Version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Sensors.MiscDevice

错误码：

以下错误码的详细介绍请参见振动错误码和通用错误码。

错误码ID错误信息
201Permission denied.
14600101Device operation failed.

示例：

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

try {
  // 停止任何形式的马达振动
  vibrator.stopVibrationSync()
  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}`);
}

vibrator.isSupportEffect10+

isSupportEffect(effectId: string, callback: AsyncCallback<boolean>): void

查询是否支持传入参数effectId。使用callback异步回调。

系统能力：SystemCapability.Sensors.MiscDevice

参数：

参数名类型必填说明
effectIdstring是待确认的预置振动效果。
callbackAsyncCallback<boolean>是回调函数，当返回true则表示支持该effectId，返回false不支持。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID错误信息
201Permission denied.
401Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed.

示例：

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

try {
  // 查询是否支持'haptic.notice.success'
  vibrator.isSupportEffect('haptic.notice.success', (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 {
        // 使用startVibration需要添加ohos.permission.VIBRATE权限
        vibrator.startVibration({
          type: 'preset',
          effectId: 'haptic.notice.success',
          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}`);
}

vibrator.isSupportEffect10+

isSupportEffect(effectId: string): Promise<boolean>

查询是否支持传入参数effectId。使用promise异步回调。

系统能力：SystemCapability.Sensors.MiscDevice

参数：

参数名类型必填说明
effectIdstring是待确认的预置振动效果。

返回值：

类型说明
Promise<boolean>Promise对象。当返回true则表示支持该effectId，返回false不支持。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID错误信息
201Permission denied.
401Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed.

示例：

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

try {
  // 查询是否支持'haptic.notice.success'
  vibrator.isSupportEffect('haptic.notice.success').then((state: boolean) => {
    console.info(`The query result is ${state}`);
    if (state) {
      try {
        vibrator.startVibration({
          type: 'preset',
          effectId: 'haptic.notice.success',
          count: 1,
        }, {
          usage: 'unknown' // 根据实际选择类型归属不同的开关管控
        }).then(() => {
          console.info('Succeed in starting vibration');
        }).catch((error: BusinessError) => {
          console.error(`Failed to start 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}`);
      }
    }
  }, (error: BusinessError) => {
    console.error(`Failed to query effect. 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}`);
}

vibrator.isSupportEffectSync12+

isSupportEffectSync(effectId: string): boolean

查询是否支持预设的振动效果。

系统能力：SystemCapability.Sensors.MiscDevice

参数：

参数名类型必填说明
effectIdstring是待确认的预置振动效果。

返回值：

类型说明
boolean返回对象。当返回true则表示支持该effectId，返回false不支持。

错误码：

以下错误码的详细介绍请参见振动错误码和通用错误码。

错误码ID错误信息
401Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed.
14600101Device operation failed.

示例：

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

try {
  // 查询是否支持预设'haptic.notice.success'
  let ret = vibrator.isSupportEffectSync('haptic.notice.success');
  console.info(`The query result is ${ret}`);
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

vibrator.isHdHapticSupported12+

isHdHapticSupported(): boolean

查询是否支持高清振动。

系统能力：SystemCapability.Sensors.MiscDevice

返回值：

类型说明
boolean返回对象，当返回true表示支持高清振动，返回false不支持。。

错误码：

以下错误码的详细介绍请参见振动错误码。

错误码ID错误信息
14600101Device operation failed.

示例：

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

try {
  // 查询是否支持高清振动
  let ret = vibrator.isHdHapticSupported();
  console.info(`The query result is ${ret}`);
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

VibratorPatternBuilder18+

vibrator('addContinuousEvent')18+

addContinuousEvent(time: number, duration: number, options?: ContinuousParam): VibratorPatternBuilder;

添加长振事件的方法成VibratorPattern对象。

系统能力：SystemCapability.Sensors.MiscDevice

参数：

参数名类型必填说明
timenumber是长期振动的起始时间。单位ms，取值范围(0,1800000)区间内所有整数。
durationnumber是长期振动的持续时间。单位ms，取值范围(0,5000]区间内所有整数。
optionsContinuousParam否可选参数，可选参数对象。

返回值：

类型说明
VibratorPatternBuilder返回已添加连续振动事件的VibratorPatternBuilder对象。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID错误信息
401Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed.

示例：

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

let builder = new vibrator.VibratorPatternBuilder();
try {
  let pointsMe: vibrator.VibratorCurvePoint[] = [
      { time: 0, intensity: 0, frequency: -7 },
      { time: 42, intensity: 1, frequency: -6 },
      { time: 128, intensity: 0.94, frequency: -4 },
      { time: 217, intensity: 0.63, frequency: -14 },
      { time: 763, intensity: 0.48, frequency: -14 },
      { time: 1125, intensity: 0.53, frequency: -10 },
      { time: 1503, intensity: 0.42, frequency: -14 },
      { time: 1858, intensity: 0.39, frequency: -14 },
      { time: 2295, intensity: 0.34, frequency: -17 },
      { time: 2448, intensity: 0.21, frequency: -14 },
      { time: 2468, intensity: 0, frequency: -21 }
  ] // VibratorCurvePoint参数最少设置4个，最大设置16个
  let param: vibrator.ContinuousParam = {
      intensity: 97,
      frequency: 34,
      points:pointsMe,
      index: 0
  }
  builder.addContinuousEvent(0, 2468, param);
  console.info(`addContinuousEvent builder is ${builder.build()}`);
} catch(error) {
  let e: BusinessError = error as BusinessError;
  console.error(`Exception. Code ${e.code}`);
}

vibrator('addTransientEvent')18+

addTransientEvent(time: number, options?: TransientParam): VibratorPatternBuilder;

添加短振事件的方法成VibratorPattern对象。

系统能力：SystemCapability.Sensors.MiscDevice

参数：

参数名类型必填说明
timenumber是长期振动的起始时间。单位ms，取值范围(0,1800000)区间内所有整数。
optionsTransientParam否可选参数，可选参数对象。

返回值：

类型说明
VibratorPatternBuilder返回已添加短振事件的VibratorPatternBuilder对象。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID错误信息
401Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed.

示例：

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

let builder = new vibrator.VibratorPatternBuilder();
try {
  let param: vibrator.TransientParam = {
      intensity: 80,
      frequency: 70,
      index: 0
  }
  builder.addTransientEvent(0, param);
  console.log(`addTransientEvent builder is ${builder.build()}`);
} catch(error) {
  let e: BusinessError = error as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

vibrator('build')18+

build(): VibratorPattern;

构造组合短事件或长事件的振动序列的方法。

系统能力：SystemCapability.Sensors.MiscDevice

返回值：

类型说明
VibratorPattern构造组合短振或长振的振动序列方法。

示例：

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

let builder = new vibrator.VibratorPatternBuilder();
try {
  let param: vibrator.TransientParam = {
      intensity: 80,
      frequency: 70,
      index: 0
  }
  builder.addTransientEvent(0, param);
  console.log(`addTransientEvent builder is ${builder.build()}`);
} catch(error) {
  let e: BusinessError = error as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}
try {
  vibrator.startVibration({
      type: "pattern",
      pattern: builder.build()
  }, {
    usage: "alarm", // 根据实际选择类型归属不同的开关管控
  }, (error) => {
    if (error) {
      let e: BusinessError = error as BusinessError;
      console.error(`Vibrate fail. Code: ${e.code}, message: ${e.message}`);
    } else {
      console.info(`vibrate success`);
    }
  });
} catch(error) {
  let e: BusinessError = error as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

EffectId

预置的振动效果。在调用vibrator.startVibration9+或vibrator.stopVibration9+接口下发VibratePreset形式振动的时候需要使用此参数类型。此参数值种类多样，'haptic.clock.timer'为其中一种。HapticFeedback12+展示了几种常用的EffectId值。

说明：

由于设备存在多样性，不同的设备可能预置不同的效果，建议使用预置效果前先使用vibrator.isSupportEffect10+接口查询当前设备是否支持该预置效果。

系统能力：SystemCapability.Sensors.MiscDevice

名称值说明
EFFECT_CLOCK_TIMER'haptic.clock.timer'描述用户调整计时器时的振动效果。

HapticFeedback12+

简单而通用的振动效果。根据各设备的马达器件不同，同一振动效果的频率会有差异，但效果的频率趋向是统一的。这几种振动效果是EffectId参数的具体值，使用方法参考vibrator.startVibration9+或vibrator.stopVibration9+接口下发VibratePreset形式振动的示例代码。

系统能力：SystemCapability.Sensors.MiscDevice

名称值说明
EFFECT_SOFT'haptic.effect.soft'较松散的振动效果，频率偏低。
EFFECT_HARD'haptic.effect.hard'较沉重的振动效果，频率居中。
EFFECT_SHARP'haptic.effect.sharp'较尖锐的振动效果，频率偏高。
EFFECT_NOTICE_SUCCESS18+'haptic.notice.success'表达成功通知的振动效果。
EFFECT_NOTICE_FAILURE18+'haptic.notice.fail'表达失败通知的振动效果。
EFFECT_NOTICE_WARNING18+'haptic.notice.warning'表达警告通知的振动效果。

VibratorStopMode

停止振动的模式。在调用vibrator.stopVibration9+或vibrator.stopVibration9+接口时，需要使用此参数类型指定停止的振动模式。停止模式和VibrateEffect9+中下发的模式为对应关系。

系统能力：SystemCapability.Sensors.MiscDevice

名称值说明
VIBRATOR_STOP_MODE_TIME'time'停止duration模式的振动。
VIBRATOR_STOP_MODE_PRESET'preset'停止预置EffectId的振动。

VibrateEffect9+

马达振动效果，支持以下三种。在调用vibrator.startVibration9+或vibrator.startVibration9+接口时，此参数的三种类型表示以三种不同的形式触发振动。

系统能力：SystemCapability.Sensors.MiscDevice

类型说明
VibrateTime按照指定时长触发马达振动。
原子化服务API： 从API Version 11开始，该接口支持在原子化服务中使用。
VibratePreset按照预置振动类型触发马达振动。
VibrateFromFile按照自定义振动配置文件触发马达振动。
VibrateFromPattern18+按照自定义振动效果触发马达振动。

VibrateTime9+

指定时长振动类型。

原子化服务API：从API Version 11开始，该接口在支持原子化服务中使用。

系统能力：SystemCapability.Sensors.MiscDevice

名称类型必填说明
type'time'是值为'time'，按照指定时长触发马达振动。
durationnumber是马达持续振动时长, 单位ms。取值范围(0,1800000]区间内所有整数

VibratePreset9+

预置振动类型。当调用vibrator.startVibration9+或vibrator.startVibration9+时，VibrateEffect9+参数的值可以为VibratePreset，表示触发预置振动类型。

系统能力：SystemCapability.Sensors.MiscDevice

名称类型必填说明
type'preset'是值为'preset'，按照预置振动效果触发马达振动。
effectIdstring是预置的振动效果ID。
countnumber否可选参数，振动的重复次数，默认值为1。
intensity12+number否可选参数，振动调节强度，取值范围(0,100]内所有整数，默认值为100。若振动效果不支持强度调节或设备不支持时，则按默认强度振动。

VibrateFromFile10+

自定义振动类型。仅部分设备支持。当设备不支持此振动类型时，返回设备不支持错误码。当调用vibrator.startVibration9+或vibrator.startVibration9+时，VibrateEffect9+参数的值可以为VibrateFromFile，表示触发自定义振动类型。

系统能力：SystemCapability.Sensors.MiscDevice

名称类型必填说明
type'file'是值为'file'，按照振动配置文件触发马达振动。
hapticFdHapticFileDescriptor10+是振动配置文件的描述符。

HapticFileDescriptor10+

自定义振动配置文件的描述符，必须确认资源文件可用，其参数可通过文件管理API从沙箱路径获取或者通过资源管理API从HAP资源获取。使用场景：振动序列被存储在一个文件中，需要根据偏移量和长度进行振动，振动序列存储格式，请参考自定义振动格式。

系统能力：SystemCapability.Sensors.MiscDevice

名称类型必填说明
fdnumber是资源文件描述符。
offsetnumber否距文件起始位置的偏移量，单位为字节，默认为文件起始位置，不可超出文件有效范围。
lengthnumber否资源长度，单位为字节，默认值为从偏移位置至文件结尾的长度，不可超出文件有效范围。

VibratorEventType18+

振动事件类型。

系统能力：SystemCapability.Sensors.MiscDevice

名称类型必填说明
CONTINUOUSnumber是值为0，表示长振。
TRANSIENTnumber是值为1，表示短振。

VibratorCurvePoint18+

相对事件振动强度的增益。

系统能力：SystemCapability.Sensors.MiscDevice

名称类型必填说明
timenumber是起始时间偏移。
intensitynumber否可选参数，相对事件振动强度增益，取值范围[0,100%]，省略时默认值为1。
frequencynumber否可选参数，相对事件振动频率变化，取值范围[-100,100]内所有整数，省略时默认值为0。

VibratorEvent18+

振动事件。

系统能力：SystemCapability.Sensors.MiscDevice

名称类型必填说明
eventTypeVibratorEventType是振动事件类型。
timenumber是振动起始时间，单位ms。取值范围[0,1800000]区间内所有整数。
durationnumber否可选参数，表示振动持续时间，取值范围（0,5000]区间所有整数，短振默认值为48，长振默认值为1000
intensitynumber否可选参数，表示振动强度，取值范围[0,100]区间所有整数，省略时默认值为100。
frequencynumber否可选参数，表示振动频率，取值范围[0,100]区间内所有整数，省略时默认值为50。
indexnumber否可选参数，表示通道编号，取值范围[0,2]区间内所有整数，省略时默认值为0。
pointsArray<VibratorCurvePoint>否可选参数，表示振动调节曲线数组。

VibratorPattern18+

马达振动序列，每个events代表一个振动事件。

系统能力：SystemCapability.Sensors.MiscDevice

名称类型必填说明
timenumber是振动绝对起始时间。
eventsArray<VibratorEvent>是振动事件数组，build()方法返回的VibratorPattern对象。

ContinuousParam18+

连续振动参数。

系统能力：SystemCapability.Sensors.MiscDevice

名称类型必填说明
intensitynumber否可选参数，表示振动强度，取值范围[0,100]内所有整数，省略时默认值为100。
frequencynumber否可选参数，表示振动频率，取值范围[0,100]内所有整数，省略时默认值为50。
pointsVibratorCurvePoint[]否可选参数，表示振动调节曲线数组。
indexnumber否可选参数，表示通道编号，取值范围[0,2]区间内所有整数，省略时默认值为0。

TransientParam18+

瞬态振动参数。

系统能力：SystemCapability.Sensors.MiscDevice

名称类型必填说明
intensitynumber否可选参数，表示振动强度，取值范围[0,100]内所有整数，省略时默认值为100。
frequencynumber否可选参数，表示振动频率，取值范围[0,100]内所有整数，省略时默认值为50。
indexnumber否可选参数，表示通道编号，取值范围[0,2]区间内所有整数，省略时默认值为0。

VibrateFromPattern18+

自定义振动效果触发马达振动。

系统能力：SystemCapability.Sensors.MiscDevice

名称类型必填说明
type'pattern'是值为“pattern”，根据组合模式触发电机振动。
patternVibratorPattern是振动事件数组，build()方法返回的VibratorPattern对象。

VibrateAttribute9+

马达振动属性。

原子化服务API：从API Version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Sensors.MiscDevice

名称类型必填说明
idnumber否振动器ID， 默认值为0。
usageUsage是马达振动的使用场景。默认值为'unknown'，取值范围只允许在Usage提供的类型中选取。

Usage9+

type Usage = 'unknown'|'alarm'|'ring'|'notification'|'communication'|'touch'|'media'|'physicalFeedback'|'simulateReality'

振动使用场景。

原子化服务API：从API Version 11开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Sensors.MiscDevice

类型说明
'unknown'没有明确使用场景，最低优先级，值固定为'unknown'字符串。
'alarm'用于警报场景，值固定为'alarm'字符串。
'ring'用于铃声场景，值固定为'ring'字符串。
'notification'用于通知场景，值固定为'notification'字符串。
'communication'用于通信场景，值固定为'communication'字符串。
'touch'用于触摸场景，值固定为'touch'字符串。
'media'用于多媒体场景，值固定为'media'字符串。
'physicalFeedback'用于物理反馈场景，值固定为'physicalFeedback'字符串。
'simulateReality'用于模拟现实场景，值固定为'simulateReality'字符串。

vibrator.vibrate(deprecated)

vibrate(duration: number): Promise<void>

按照指定持续时间触发马达振动。

从API version 9 开始不再维护，建议使用 vibrator.startVibration9+代替。

需要权限：ohos.permission.VIBRATE

系统能力：SystemCapability.Sensors.MiscDevice

参数：

参数名类型必填说明
durationnumber是马达振动时长, 单位ms；取值范围是（0,1800000]区间的所有整数。

返回值：

类型说明
Promise<void>Promise对象。

示例：

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

vibrator.vibrate(1000).then(() => {
  console.info('Succeed in vibrating');
}, (error: BusinessError) => {
  console.error(`Failed to vibrate. Code: ${error.code}, message: ${error.message}`);
});

vibrator.vibrate(deprecated)

vibrate(duration: number, callback?: AsyncCallback<void>): void

按照指定持续时间触发马达振动。

从API version 9 开始不再维护，建议使用 vibrator.startVibration9+代替。

需要权限：ohos.permission.VIBRATE

系统能力：SystemCapability.Sensors.MiscDevice

参数：

参数名类型必填说明
durationnumber是马达振动时长, 单位ms。取值范围是（0,1800000]区间的所有整数。
callbackAsyncCallback<void>否回调函数，当马达振动成功，err为undefined，否则为错误对象。

示例：

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

vibrator.vibrate(1000, (error: BusinessError) => {
  if (error) {
    console.error(`Failed to vibrate. Code: ${error.code}, message: ${error.message}`);
  } else {
    console.info('Succeed in vibrating');
  }
})

vibrator.vibrate(deprecated)

vibrate(effectId: EffectId): Promise<void>

按照预置振动效果触发马达振动。

从API version 9 开始不再维护，建议使用 vibrator.startVibration9+代替。

需要权限：ohos.permission.VIBRATE

系统能力：SystemCapability.Sensors.MiscDevice

参数：

参数名类型必填说明
effectIdEffectId是预置的振动效果ID。

返回值：

类型说明
Promise<void>Promise对象。

示例：

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

vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER).then(() => {
  console.info('Succeed in vibrating');
}, (error: BusinessError) => {
  console.error(`Failed to vibrate. Code: ${error.code}, message: ${error.message}`);
});

vibrator.vibrate(deprecated)

vibrate(effectId: EffectId, callback?: AsyncCallback<void>): void

按照指定振动效果触发马达振动。

从API version 9 开始不再维护，建议使用 vibrator.startVibration9+代替。

需要权限：ohos.permission.VIBRATE

系统能力：SystemCapability.Sensors.MiscDevice

参数：

参数名类型必填说明
effectIdEffectId是预置的振动效果ID。
callbackAsyncCallback<void>否回调函数，当马达振动成功，err为undefined，否则为错误对象。

示例：

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

vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER, (error: BusinessError) => {
  if (error) {
    console.error(`Failed to vibrate. Code: ${error.code}, message: ${error.message}`);
  } else {
    console.info('Succeed in vibrating');
  }
})

vibrator.stop(deprecated)

stop(stopMode: VibratorStopMode): Promise<void>

按照指定模式停止马达的振动。

从API version 9 开始不再维护，建议使用 vibrator.stopVibration9+代替。

需要权限：ohos.permission.VIBRATE

系统能力：SystemCapability.Sensors.MiscDevice

参数：

参数名类型必填说明
stopModeVibratorStopMode是马达停止指定的振动模式。

返回值：

类型说明
Promise<void>Promise对象。

示例：

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

// 按照effectId类型启动振动
vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER, (error: BusinessError) => {
  if (error) {
    console.error(`Failed to vibrate. Code: ${error.code}, message: ${error.message}`);
  } else {
    console.info('Succeed in vibrating');
  }
})
// 使用VIBRATOR_STOP_MODE_PRESET模式停止振动
vibrator.stop(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET).then(() => {
  console.info('Succeed in stopping');
}, (error: BusinessError) => {
  console.error(`Failed to stop. Code: ${error.code}, message: ${error.message}`);
});

vibrator.stop(deprecated)

stop(stopMode: VibratorStopMode, callback?: AsyncCallback<void>): void

按照指定模式停止马达的振动。

从API version 9 开始不再维护，建议使用 vibrator.stopVibration9+代替。

需要权限：ohos.permission.VIBRATE

系统能力：SystemCapability.Sensors.MiscDevice

参数：

参数名类型必填说明
stopModeVibratorStopMode是马达停止指定的振动模式。
callbackAsyncCallback<void>否回调函数，当马达停止振动成功，err为undefined，否则为错误对象。

示例：

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

// 按照effectId类型启动振动
vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER, (error: BusinessError) => {
  if (error) {
    console.error(`Failed to vibrate. Code: ${error.code}, message: ${error.message}`);
  } else {
    console.info('Succeed in vibrating');
  }
})
// 使用VIBRATOR_STOP_MODE_PRESET模式停止振动
vibrator.stop(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET, (error: BusinessError) => {
  if (error) {
    console.error(`Failed to stop. Code: ${error.code}, message: ${error.message}`);
  } else {
    console.info('Succeed in stopping');
  }
})

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Sensor Service Kit（传感器服务）

harmony 鸿蒙Sensor

harmony 鸿蒙Vibrator

harmony 鸿蒙Vibrator_Attribute

harmony 鸿蒙Vibrator_FileDescription

harmony 鸿蒙传感器错误码

harmony 鸿蒙振动错误码

harmony 鸿蒙@ohos.sensor (传感器)(系统接口)

harmony 鸿蒙js-apis-sensor

harmony 鸿蒙@system.sensor (传感器)

  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 本文链接 https://seaxiang.com/blog/uEn4WY