提交 bd4996b3 编写于 作者: G Gloria

Update docs against 8737+9514+9704

Signed-off-by: wusongqing<wusongqing@huawei.com>
上级 c66a6bd7
...@@ -2,8 +2,6 @@ ...@@ -2,8 +2,6 @@
The **Vibrator** module provides APIs for triggering or stopping vibration. The **Vibrator** module provides APIs for triggering or stopping vibration.
Misc devices, including vibrators and LED lights, are used to send signals externally. You can call the APIs of this module to control the vibration of vibrators and turning-on/off of LED lights.
> **NOTE** > **NOTE**
> >
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
...@@ -19,25 +17,26 @@ import vibrator from '@ohos.vibrator'; ...@@ -19,25 +17,26 @@ import vibrator from '@ohos.vibrator';
vibrate(duration: number): Promise&lt;void&gt; vibrate(duration: number): Promise&lt;void&gt;
Triggers vibration with a specific duration. This API uses a promise to return the execution result. Triggers vibration with the specified duration. This API uses a promise to return the result.
**Required permissions**: ohos.permission.VIBRATE (a system permission) **Required permissions**: ohos.permission.VIBRATE
**System capability**: SystemCapability.Sensors.MiscDevice **System capability**: SystemCapability.Sensors.MiscDevice
**Parameters** **Parameters**
| Name | Type | Mandatory | Description |
| -------- | ------ | ---- | ------------ | | Name | Type | Mandatory| Description |
| duration | number | Yes | Vibration duration.| | -------- | ------ | ---- | ---------------------- |
| duration | number | Yes | Vibration duration, in ms.|
**Return value** **Return value**
| Type | Description |
| ------------------- | ----------- |
| Promise&lt;void&gt; | Promise used to indicate whether the vibration is triggered successfully.|
| Type | Description |
| ------------------- | -------------------------------------- |
| Promise&lt;void&gt; | Promise that returns no value.|
**Example** **Example**
```js ```js
vibrator.vibrate(1000).then(()=>{ vibrator.vibrate(1000).then(()=>{
console.log("Promise returned to indicate a successful vibration."); console.log("Promise returned to indicate a successful vibration.");
...@@ -46,28 +45,67 @@ Triggers vibration with a specific duration. This API uses a promise to return t ...@@ -46,28 +45,67 @@ Triggers vibration with a specific duration. This API uses a promise to return t
}); });
``` ```
## vibrator.vibrate<sup>9+</sup>
vibrate(effect: VibrateEffect, attribute: VibrateAttribute): Promise&lt;void&gt;
Triggers vibration with the specified effect and attribute. This API uses a promise to return the result.
**Required permissions**: ohos.permission.VIBRATE
**System capability**: SystemCapability.Sensors.MiscDevice
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | -------------------------------------- | ---- | :------------- |
| effect | [VibrateEffect](#vibrateeffect9) | Yes | Vibration effect.|
| attribute | [VibrateAttribute](#vibrateattribute9) | Yes | Vibration attribute.|
**Return value**
| Type | Description |
| ------------------- | -------------------------------------- |
| Promise&lt;void&gt; | Promise that returns no value.|
**Example**
```js
vibrator.vibrate({
type: 'time',
duration: 1000
}, {
id: 0,
usage: 'alarm'
}).then(()=>{
console.log("Promise returned to indicate a successful vibration");
}).catch((error)=>{
console.log("error.code" + error.code + "error.message" + error.message);
})
```
## vibrator.vibrate ## vibrator.vibrate
vibrate(duration: number, callback?: AsyncCallback&lt;void&gt;): void vibrate(duration: number, callback?: AsyncCallback&lt;void&gt;): void
Triggers vibration with a specific duration. This API uses an asynchronous callback to return the execution result. Triggers vibration with the specified duration. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.VIBRATE (a system permission) **Required permissions**: ohos.permission.VIBRATE
**System capability**: SystemCapability.Sensors.MiscDevice **System capability**: SystemCapability.Sensors.MiscDevice
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ----------------------- | | -------- | ------------------------- | ---- | ---------------------------------------------------------- |
| duration | number | Yes | Vibration duration. | | duration | number | Yes | Vibration duration, in ms. |
| callback | AsyncCallback&lt;void&gt; | No | Callback used to indicate whether the vibration is triggered successfully.| | callback | AsyncCallback&lt;void&gt; | No | Callback used to the result. If the vibration starts, **err** is **undefined**. Otherwise, **err** is an error object.|
**Example** **Example**
```js ```js
vibrator.vibrate(1000,function(error){ vibrator.vibrate(1000,function(error){
if(error){ if(error){
console.log("error.code"+error.code+"error.message"+error.message); console.log("error.code" + error.code + "error.message" + error.message);
}else{ }else{
console.log("Callback returned to indicate a successful vibration."); console.log("Callback returned to indicate a successful vibration.");
} }
...@@ -79,28 +117,28 @@ Triggers vibration with a specific duration. This API uses an asynchronous callb ...@@ -79,28 +117,28 @@ Triggers vibration with a specific duration. This API uses an asynchronous callb
vibrate(effectId: EffectId): Promise&lt;void&gt; vibrate(effectId: EffectId): Promise&lt;void&gt;
Triggers vibration with a specific effect. This API uses a promise to return the execution result. Triggers vibration with the specified effect. This API uses a promise to return the result.
**Required permissions**: ohos.permission.VIBRATE (a system permission) **Required permissions**: ohos.permission.VIBRATE
**System capability**: SystemCapability.Sensors.MiscDevice **System capability**: SystemCapability.Sensors.MiscDevice
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory| Description |
| -------- | --------------------- | ---- | ------------- | | -------- | --------------------- | ---- | ------------------ |
| effectId | [EffectId](#effectid) | Yes | Vibration effect. | | effectId | [EffectId](#effectid) | Yes | Preset vibration effect ID.|
**Return value** **Return value**
| Type | Description | | Type | Description |
| ------------------- | ----------- | | ------------------- | -------------------------------------- |
| Promise&lt;void&gt; | Promise used to indicate whether the vibration is triggered successfully.| | Promise&lt;void&gt; | Promise that returns no value.|
**Example** **Example**
```js ```js
vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER).then(()=>{ vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER).then(()=>{
console.log("Promise returned to indicate a successful vibration."); console.log("Promise returned to indicate a successful vibration.");
}, (error)=>{ }, (error)=>{
console.log("error.code"+error.code+"error.message"+error.message); console.log("error.code" + error.code + "error.message" + error.message);
}); });
``` ```
...@@ -109,56 +147,94 @@ Triggers vibration with a specific effect. This API uses a promise to return the ...@@ -109,56 +147,94 @@ Triggers vibration with a specific effect. This API uses a promise to return the
vibrate(effectId: EffectId, callback?: AsyncCallback&lt;void&gt;): void vibrate(effectId: EffectId, callback?: AsyncCallback&lt;void&gt;): void
Triggers vibration with a specific effect. This API uses an asynchronous callback to return the execution result. Triggers vibration with the specified effect. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.VIBRATE (a system permission) **Required permissions**: ohos.permission.VIBRATE
**System capability**: SystemCapability.Sensors.MiscDevice **System capability**: SystemCapability.Sensors.MiscDevice
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ----------------------- | | -------- | ------------------------- | ---- | ---------------------------------------------------------- |
| effectId | [EffectId](#effectid) | Yes | Vibration effect. | | effectId | [EffectId](#effectid) | Yes | Preset vibration effect ID. |
| callback | AsyncCallback&lt;void&gt; | No | Callback used to indicate whether the vibration is triggered successfully.| | callback | AsyncCallback&lt;void&gt; | No | Callback used to the result. If the vibration starts, **err** is **undefined**. Otherwise, **err** is an error object.|
**Example** **Example**
```js ```js
vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER, function(error){ vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER, function(error){
if(error){ if(error){
console.log("error.code"+error.code+"error.message"+error.message); console.log("error.code" + error.code + "error.message" + error.message);
}else{ }else{
console.log("Callback returned to indicate a successful vibration."); console.log("Callback returned to indicate a successful vibration.");
} }
}) })
``` ```
## vibrator.vibrate<sup>9+</sup>
vibrate(effect: VibrateEffect, attribute: VibrateAttribute, callback: AsyncCallback&lt;void&gt;): void
Triggers vibration with the specified effect and attribute. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.VIBRATE
**System capability**: SystemCapability.Sensors.MiscDevice
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | -------------------------------------- | ---- | :--------------------------------------------------------- |
| effect | [VibrateEffect](#vibrateeffect9) | Yes | Vibration effect. |
| attribute | [VibrateAttribute](#vibrateattribute9) | Yes | Vibration attribute. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to the result. If the vibration starts, **err** is **undefined**. Otherwise, **err** is an error object.|
**Example**
```js
vibrator.vibrate({
type:'time',
duration:1000,
},{
id:0,
usage: 'alarm'
}, (error)=>{
if(error){
console.log("vibrate fail, error.code:" + error.code + ",error.message:" + error.message);
}else{
console.log("Callback returned to indicate a successful vibration.");
}
});
```
## vibrator.stop ## vibrator.stop
stop(stopMode: VibratorStopMode): Promise&lt;void&gt; stop(stopMode: VibratorStopMode): Promise&lt;void&gt;
Stops the vibration based on the specified **stopMode**. This API uses a promise to return the execution result. If the specified **stopMode** is different from the mode used to trigger the vibration, this API fails to be called. Stops the vibration with the specified **stopMode**. This API uses a promise to return the result. If the specified **stopMode** is different from the mode used to trigger the vibration, this API fails to be called.
**Required permissions**: ohos.permission.VIBRATE (a system permission) **Required permissions**: ohos.permission.VIBRATE
**System capability**: SystemCapability.Sensors.MiscDevice **System capability**: SystemCapability.Sensors.MiscDevice
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | --------------- | | -------- | ------------------------------------- | ---- | ------------------------ |
| stopMode | [VibratorStopMode](#vibratorstopmode) | Yes | Vibration mode to stop.| | stopMode | [VibratorStopMode](#vibratorstopmode) | Yes | Mode to stop the vibration.|
**Return value** **Return value**
| Type | Description |
| ------------------- | ----------- | | Type | Description |
| Promise&lt;void&gt; | Promise used to indicate whether the vibration is stopped successfully.| | ------------------- | -------------------------------------- |
| Promise&lt;void&gt; | Promise that returns no value.|
**Example** **Example**
```js ```js
vibrator.stop(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET).then(()=>{ vibrator.stop(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET).then(()=>{
console.log("Promise returned to indicate a successful vibration."); console.log("Promise returned to indicate a successful vibration.");
}, (error)=>{ }, (error)=>{
console.log("error.code"+error.code+"error.message"+error.message); console.log("error.code" + error.code + "error.message" + error.message);
}); });
``` ```
...@@ -167,23 +243,24 @@ Stops the vibration based on the specified **stopMode**. This API uses a promise ...@@ -167,23 +243,24 @@ Stops the vibration based on the specified **stopMode**. This API uses a promise
stop(stopMode: VibratorStopMode, callback?: AsyncCallback&lt;void&gt;): void; stop(stopMode: VibratorStopMode, callback?: AsyncCallback&lt;void&gt;): void;
Stops the vibration based on the specified **stopMode**. This API uses an asynchronous callback to return the execution result. If the specified **stopMode** is different from the mode used to trigger the vibration, this API fails to be called. Stops the vibration with the specified **stopMode**. This API uses an asynchronous callback to return the result. If the specified **stopMode** is different from the mode used to trigger the vibration, this API fails to be called.
**Required permissions**: ohos.permission.VIBRATE (a system permission) **Required permissions**: ohos.permission.VIBRATE
**System capability**: SystemCapability.Sensors.MiscDevice **System capability**: SystemCapability.Sensors.MiscDevice
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ----------------------- | | -------- | ------------------------------------- | ---- | ------------------------------------------------------------ |
| stopMode | [VibratorStopMode](#vibratorstopmode) | Yes | Vibration mode to stop. | | stopMode | [VibratorStopMode](#vibratorstopmode) | Yes | Mode to stop the vibration. |
| callback | AsyncCallback&lt;void&gt; | No | Callback used to indicate whether the vibration is stopped successfully.| | callback | AsyncCallback&lt;void&gt; | No | Callback used to the result. If the vibration stops, **err** is **undefined**. Otherwise, **err** is an error object.|
**Example** **Example**
```js ```js
vibrator.stop(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET, function(error){ vibrator.stop(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET, function(error){
if(error){ if(error){
console.log("error.code"+error.code+"error.message"+error.message); console.log("error.code" + error.code + "error.message" + error.message);
}else{ }else{
console.log("Callback returned to indicate a successful stop."); console.log("Callback returned to indicate a successful stop.");
} }
...@@ -193,22 +270,85 @@ Stops the vibration based on the specified **stopMode**. This API uses an asynch ...@@ -193,22 +270,85 @@ Stops the vibration based on the specified **stopMode**. This API uses an asynch
## EffectId ## EffectId
Describes the vibration effect. Describes the vibration effect ID.
**System capability**: SystemCapability.Sensors.MiscDevice **System capability**: SystemCapability.Sensors.MiscDevice
| Name | Default Value | Description | | Name | Default Value | Description |
| ------------------ | -------------------- | --------------- | | ------------------ | -------------------- | ------------------ |
| EFFECT_CLOCK_TIMER | "haptic.clock.timer" | Vibration effect of the vibrator when a user adjusts the timer.| | EFFECT_CLOCK_TIMER | "haptic.clock.timer" | Preset vibration effect ID.|
## VibratorStopMode ## VibratorStopMode
Describes the vibration mode to stop. Enumerates the modes available to stop the vibration.
**System capability**: SystemCapability.Sensors.MiscDevice **System capability**: SystemCapability.Sensors.MiscDevice
| Name | Default Value | Description | | Name | Default Value | Description |
| ------------------------- | -------- | ---------------------------------------- | | ------------------------- | -------- | ------------------------------------------------------------ |
| VIBRATOR_STOP_MODE_TIME | "time" | The vibration to stop is in **duration** mode. This vibration is triggered with the parameter **duration** of the **number** type.| | VIBRATOR_STOP_MODE_TIME | "time" | The vibration to stop is in **duration** mode. This vibration is triggered with the parameter **duration** of the **number** type.|
| VIBRATOR_STOP_MODE_PRESET | "preset" | The vibration to stop is in **EffectId** mode. This vibration is triggered with the parameter **effectId** of the **EffectId** type.| | VIBRATOR_STOP_MODE_PRESET | "preset" | The vibration to stop is in **EffectId** mode. This vibration is triggered with the parameter **effectId** of the **EffectId** type.|
## VibrateEffect<sup>9+</sup>
Describes the vibration effect.
**System capability**: SystemCapability.Sensors.MiscDevice
| Type | Description |
| -------------------------------- | ------------------------------ |
| [VibrateTime](#vibratetime9) | Triggers vibration with the specified duration. This API uses a promise to return the result.|
| [VibratePreset](#vibratepreset9) | Vibration with a preset effect.|
## VibrateTime<sup>9+</sup>
Describes the vibration with the specified duration.
**System capability**: SystemCapability.Sensors.MiscDevice
| Name | Default Value| Description |
| -------- | ------ | ------------------------------ |
| type | "time" | Vibration with the specified duration.|
| duration | - | Vibration duration, in ms. |
## VibratePreset<sup>9+</sup>
Describes the vibration with a preset effect.
**System capability**: SystemCapability.Sensors.MiscDevice
| Name | Default Value | Description |
| -------- | -------- | ------------------------------ |
| type | "preset" | Vibration with the specified effect.|
| effectId | - | Preset vibration effect ID. |
| count | - | Number of vibrations to repeat. |
## VibrateAttribute<sup>9+</sup>
Describes the vibration attribute.
**System capability**: SystemCapability.Sensors.MiscDevice
| Name | Default Value| Description |
| ----- | ------ | -------------- |
| id | 0 | Vibrator ID. |
| usage | - | Vibration scenario.|
## Usage<sup>9+</sup>
Enumerates the vibration scenarios.
**System capability**: SystemCapability.Sensors.MiscDevice
| Name | Type | Description |
| ---------------- | ------ | ------------------------------ |
| unknown | string | Unknown scenario, with the lowest priority.|
| alarm | string | Vibration for alarms. |
| ring | string | Vibration for incoming calls. |
| notification | string | Vibration for notifications. |
| communication | string | Vibration for communication. |
| touch | string | Touch vibration scenario. |
| media | string | Multimedia vibration scenario. |
| physicalFeedback | string | Physical feedback vibration scenario. |
| simulateReality | string | Simulated reality vibration scenario. |
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册