diff --git a/zh-cn/application-dev/reference/apis/js-apis-vibrator.md b/zh-cn/application-dev/reference/apis/js-apis-vibrator.md index 3e3f5b1c20fb4f61366f3dbea3c689e687f83216..3459cfc51a585e9c87d969bdd5e1bda6acf0e383 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-vibrator.md +++ b/zh-cn/application-dev/reference/apis/js-apis-vibrator.md @@ -1,11 +1,7 @@ # 振动 -## 模块说明 - vibrator模块提供控制马达振动的能力，如通过接口控制马达启动马达振动，停止马达振动等。 -小器件是指用于向外传递信号的设备，包括马达和LED灯，本组件对开发者提供控制马达振动和LED灯开关的能力。 - > **说明：** > > 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 @@ -23,23 +19,24 @@ vibrate(duration: number): Promise<void> 按照指定持续时间触发马达振动。 -**权限列表**：ohos.permission.VIBRATE，该权限为系统权限 +**需要权限**：ohos.permission.VIBRATE，该权限为系统权限 **系统能力**：SystemCapability.Sensors.MiscDevice - **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ------------ | -| duration | number | 是 | 指示马达振动的持续时间。 | + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ---------------------- | +| duration | number | 是 | 马达振动时长, 单位ms。 | **返回值：** -| 类型 | 说明 | -| ------------------- | ----------- | -| Promise<void> | 指示触发振动是否成功。 | +| 类型 | 说明 | +| ------------------- | -------------------------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | **示例：** + ```js vibrator.vibrate(1000).then(()=>{ console.log("Promise returned to indicate a successful vibration."); @@ -48,6 +45,44 @@ vibrate(duration: number): Promise<void> }); ``` +## vibrator.vibrate9+ + +vibrate(effect: VibrateEffect, attribute: VibrateAttribute): Promise<void> + +按照指定振动效果和振动属性触发马达振动。 + +**需要权限**：ohos.permission.VIBRATE，该权限为系统权限 + +**系统能力**：SystemCapability.Sensors.MiscDevice + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------------------- | ---- | :------------- | +| effect | [VibrateEffect](#vibrateeffect) | 是 | 马达振动效果。 | +| attribute | [VibrateAttribute](#vibrateattribute) | 是 | 马达振动属性。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | -------------------------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | + +**示例：** + +```js +vibrator.vibrate({ + type: 'time', + duration: 1000 +}, { + id: 0, + usage: 'alarm' +}).then((result)=>{ + console.log("Promise returned to indicate a successful vibration"); +}).catch((error)=>{ + console.log("error.code"+error.code+"error.message"+error.message); +}) +``` ## vibrator.vibrate @@ -55,17 +90,18 @@ vibrate(duration: number, callback?: AsyncCallback<void>): void 按照指定持续时间触发马达振动。 -**权限列表**：ohos.permission.VIBRATE，该权限为系统权限 +**需要权限**：ohos.permission.VIBRATE，该权限为系统权限 **系统能力**：SystemCapability.Sensors.MiscDevice **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------- | ---- | ----------------------- | -| duration | number | 是 | 指示马达振动的持续时间。 | -| callback | AsyncCallback<void> | 否 | 马达执行振动的回调函数，指示触发振动是否成功。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ---------------------------------------------------------- | +| duration | number | 是 | 马达振动时长, 单位ms。 | +| callback | AsyncCallback<void> | 否 | 回调函数。当马达振动成功，err为undefined，否则为错误对象。 | **示例：** + ```js vibrator.vibrate(1000,function(error){ if(error){ @@ -81,21 +117,21 @@ vibrate(duration: number, callback?: AsyncCallback<void>): void vibrate(effectId: EffectId): Promise<void> -按照指定振动效果触发马达振动。 +按照预置振动效果触发马达振动。 -**权限列表**：ohos.permission.VIBRATE，该权限为系统权限 +**需要权限**：ohos.permission.VIBRATE，该权限为系统权限 **系统能力**：SystemCapability.Sensors.MiscDevice **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------- | ---- | ------------- | -| effectId | [EffectId](#effectid) | 是 | 指示马达振动效果的字符串。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------- | ---- | ------------------ | +| effectId | [EffectId](#effectid) | 是 | 预置的振动效果ID。 | **返回值：** -| 类型 | 说明 | -| ------------------- | ----------- | -| Promise<void> | 指示触发振动是否成功。 | +| 类型 | 说明 | +| ------------------- | -------------------------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | **示例：** ```js @@ -113,17 +149,18 @@ vibrate(effectId: EffectId, callback?: AsyncCallback<void>): void 按照指定振动效果触发马达振动。 -**权限列表**：ohos.permission.VIBRATE，该权限为系统权限 +**需要权限**：ohos.permission.VIBRATE，该权限为系统权限 **系统能力**：SystemCapability.Sensors.MiscDevice **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------- | ---- | ----------------------- | -| effectId | [EffectId](#effectid) | 是 | 指示马达振动效果的字符串。 | -| callback | AsyncCallback<void> | 否 | 马达执行振动的回调函数，指示触发振动是否成功。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ---------------------------------------------------------- | +| effectId | [EffectId](#effectid) | 是 | 预置的振动效果ID。 | +| callback | AsyncCallback<void> | 否 | 回调函数。当马达振动成功，err为undefined，否则为错误对象。 | **示例：** + ```js vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER, function(error){ if(error){ @@ -134,6 +171,41 @@ vibrate(effectId: EffectId, callback?: AsyncCallback<void>): void }) ``` +## vibrator.vibrate9+ + +vibrate(effect: VibrateEffect, attribute: VibrateAttribute, callback: AsyncCallback<void>): void + +按照指定振动效果和振动属性触发马达振动。 + +**需要权限**：ohos.permission.VIBRATE，该权限为系统权限 + +**系统能力**：SystemCapability.Sensors.MiscDevice + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------------------- | ---- | :--------------------------------------------------------- | +| effect | [VibrateEffect](#vibrateeffect) | 是 | 马达振动效果。 | +| attribute | [VibrateAttribute](#vibrateattribute) | 是 | 马达振动属性。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当马达振动成功，err为undefined，否则为错误对象。 | + +示例： + +```js +vibrator.vibrate({ + type:'time', + duration:1000, +},{ + id:0, + usage: 'alarm' +}, (error)=>{ + if(error){ + console.log(TAG + " fail, error.code:"+error.code+",error.message:"+error.message); + }else{ + console.log("Callback returned to indicate a successful vibration."); + } +}); +``` ## vibrator.stop @@ -141,21 +213,23 @@ stop(stopMode: VibratorStopMode): Promise<void> 按照要停止指定的振动模式来停止马达的振动。如果要停止的振动模式与触发马达振动时的模式不相同，则调用本接口会失败。 -**权限列表**：ohos.permission.VIBRATE，该权限为系统权限 +**需要权限**：ohos.permission.VIBRATE，该权限为系统权限 **系统能力**：SystemCapability.Sensors.MiscDevice **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------- | ---- | --------------- | -| stopMode | [VibratorStopMode](#vibratorstopmode) | 是 | 指示马达要停止指定的振动模式。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------- | ---- | ------------------------ | +| stopMode | [VibratorStopMode](#vibratorstopmode) | 是 | 马达停止指定的振动模式。 | **返回值：** -| 类型 | 说明 | -| ------------------- | ----------- | -| Promise<void> | 指示停止振动是否成功。 | + +| 类型 | 说明 | +| ------------------- | -------------------------------------- | +| Promise<void> | Promise对象。无返回结果的Promise对象。 | **示例：** + ```js vibrator.stop(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET).then(()=>{ console.log("Promise returned to indicate a successful vibration."); @@ -171,17 +245,18 @@ stop(stopMode: VibratorStopMode, callback?: AsyncCallback<void>): void; 按照要停止指定的振动模式来停止马达的振动。如果要停止的振动模式与触发马达振动时的模式不相同，则调用本接口会失败。 -**权限列表**：ohos.permission.VIBRATE，该权限为系统权限 +**需要权限**：ohos.permission.VIBRATE，该权限为系统权限 **系统能力**：SystemCapability.Sensors.MiscDevice **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------- | ---- | ----------------------- | -| stopMode | [VibratorStopMode](#vibratorstopmode) | 是 | 指示马达要停止指定的振动模式。 | -| callback | AsyncCallback<void> | 否 | 马达停止振动的回调函数，指示停止振动是否成功。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | +| stopMode | [VibratorStopMode](#vibratorstopmode) | 是 | 马达停止指定的振动模式。 | +| callback | AsyncCallback<void> | 否 | 回调函数。当马达停止振动成功，err为undefined，否则为错误对象。 | **示例：** + ```js vibrator.stop(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET, function(error){ if(error){ @@ -195,22 +270,74 @@ stop(stopMode: VibratorStopMode, callback?: AsyncCallback<void>): void; ## EffectId -表示马达振动效果的字符串。 +马达振动效果的字符串。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.MiscDevice -| 名称 | 默认值 | 说明 | -| ------------------ | -------------------- | --------------- | -| EFFECT_CLOCK_TIMER | "haptic.clock.timer" | 调整定时器时振动器的振动效果。 | +| 名称 | 默认值 | 说明 | +| ------------------ | -------------------- | ------------------ | +| EFFECT_CLOCK_TIMER | "haptic.clock.timer" | 预置的振动效果ID。 | ## VibratorStopMode -表示马达要停止指定的振动模式。 +马达要停止指定的振动模式。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.MiscDevice -| 名称 | 默认值 | 说明 | -| ------------------------- | -------- | ---------------------------------------- | -| VIBRATOR_STOP_MODE_TIME | "time" | 停止模式为duration模式的振动。即触发振动时参数类型为number，参数本身为指示振动持续时间的触发方式。 | -| VIBRATOR_STOP_MODE_PRESET | "preset" | 停止模式为预置EffectId的振动。即触发振动时参数类型为EffectId，参数本身为指示马达振动效果的字符串的触发方式。 | +| 名称 | 默认值 | 说明 | +| ------------------------- | -------- | ------------------------------------------------------------ | +| VIBRATOR_STOP_MODE_TIME | "time" | 停止模式为duration模式的振动。即触发振动时参数类型为number，参数本身为振动持续时间的触发方式。 | +| VIBRATOR_STOP_MODE_PRESET | "preset" | 停止模式为预置EffectId的振动。即触发振动时参数类型为EffectId，参数本身为马达振动效果的字符串的触发方式。 | + +## VibrateEffect9+ + +| 类型 | 说明 | +| ------------------------------- | ------------------------------ | +| [VibrateTime](#vibratetime) | 按照指定持续时间触发马达振动。 | +| [VibratePreset](#vibratepreset) | 按照预置振动类型触发马达振动。 | + +## VibrateTime9+ + +马达振动时长。 + +| 名称 | 默认值 | 说明 | +| -------- | ------ | ------------------------------ | +| type | "time" | 按照指定持续时间触发马达振动。 | +| duration | - | 马达振动时长, 单位ms。 | + +## VibratePreset9+ + +马达预置振动类型。 + +| 名称 | 默认值 | 说明 | +| -------- | -------- | ------------------------------ | +| type | "preset" | 按照预置振动效果触发马达振动。 | +| effectId | - | 预置的振动效果ID。 | +| count | - | 重复振动的次数。 | + +## VibrateAttribute9+ + +马达振动属性。 + +| 名称 | 默认值 | 说明 | +| ----- | ------ | -------------- | +| id | 0 | 振动器id。 | +| usage | - | 马达振动场景。 | + +## Usage9+ + +振动使用场景。 + +| 名称 | 类型 | 说明 | +| ---------------- | ------ | ------------------------------ | +| unknown | string | 没有明确使用场景，最低优先级。 | +| alarm | string | 用于警报振动的场景。 | +| ring | string | 用于铃声振动的场景。 | +| notification | string | 用于通知振动的场景。 | +| communication | string | 用于通信振动的场景。 | +| touch | string | 用于触摸振动的场景。 | +| media | string | 用于多媒体振动的场景。 | +| physicalFeedback | string | 用于物理反馈振动的场景。 | +| simulateReality | string | 用于模拟现实振动的场景。 | +