From 05139a01ecbff4c2163a6c819de1f507fb5502e8 Mon Sep 17 00:00:00 2001 From: Gloria Date: Tue, 14 Mar 2023 20:25:36 +0800 Subject: [PATCH] Update docs against 15402 Signed-off-by: wusongqing --- .../device/vibrator-guidelines.md | 77 ++++++- .../reference/apis/js-apis-vibrator.md | 211 ++++++++++++++++++ .../changelogs-miscdevice.md | 94 ++++++++ 3 files changed, 380 insertions(+), 2 deletions(-) create mode 100644 en/release-notes/changelogs/OpenHarmony_4.0.5.2/changelogs-miscdevice.md diff --git a/en/application-dev/device/vibrator-guidelines.md b/en/application-dev/device/vibrator-guidelines.md index 36b08b2acd..c028f5be48 100644 --- a/en/application-dev/device/vibrator-guidelines.md +++ b/en/application-dev/device/vibrator-guidelines.md @@ -16,6 +16,10 @@ For details about the APIs, see [Vibrator](../reference/apis/js-apis-vibrator.md | ohos.vibrator | startVibration(effect: VibrateEffect, attribute: VibrateAttribute, callback: AsyncCallback<void>): void | Starts vibration with the specified effect and attribute. This API uses an asynchronous callback to return the result.| | ohos.vibrator | stopVibration(stopMode: VibratorStopMode): Promise<void> | Stops vibration in the specified mode. This API uses a promise to return the result. | | ohos.vibrator | stopVibration(stopMode: VibratorStopMode, callback: AsyncCallback<void>): void | Stops vibration in the specified mode. This API uses an asynchronous callback to return the result. | +| ohos.vibrator | stopVibration(): Promise<void> | Stops vibration in all modes. This API uses a promise to return the result. | +| ohos.vibrator | stopVibration(callback: AsyncCallback<void>): void | Stops vibration in all modes. This API uses an asynchronous callback to return the result. | +| ohos.vibrator | isSupportEffect(effectId: string): Promise<boolean> | Checks whether the passed effect ID is supported. This API uses a promise to return the result. The value **true** means that the passed effect ID is supported, and **false** means the opposite. | +| ohos.vibrator | isSupportEffect(effectId: string, callback: AsyncCallback<boolean>): void | Checks whether the passed effect ID is supported. This API uses an asynchronous callback to return the result. The value **true** means that the passed effect ID is supported, and **false** means the opposite. | ## How to Develop @@ -27,7 +31,7 @@ For details about the APIs, see [Vibrator](../reference/apis/js-apis-vibrator.md ```js import vibrator from '@ohos.vibrator'; try { - vibrator.startVibration({ + vibrator.startVibration({ // To use startVibration, you must configure the ohos.permission.VIBRATE permission. type: 'time', duration: 1000, }, { @@ -50,7 +54,7 @@ For details about the APIs, see [Vibrator](../reference/apis/js-apis-vibrator.md ```js import vibrator from '@ohos.vibrator'; try { - // Stop vibration in VIBRATOR_STOP_MODE_TIME mode. + // Stop vibration in VIBRATOR_STOP_MODE_TIME mode. To use stopVibration, you must configure the ohos.permission.VIBRATE permission. vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_TIME, function (error) { if (error) { console.log('error.code' + error.code + 'error.message' + error.message); @@ -62,3 +66,72 @@ For details about the APIs, see [Vibrator](../reference/apis/js-apis-vibrator.md console.info('errCode: ' + err.code + ' ,msg: ' + err.message); } ``` + +4. Stop vibration in all modes. + + ```js + import vibrator from '@ohos.vibrator'; + // To use startVibration and stopVibration, you must configure the ohos.permission.VIBRATE permission. + try { + vibrator.startVibration({ + type: 'time', + duration: 1000, + }, { + id: 0, + usage: 'alarm' + }, (error) => { + if (error) { + console.error('vibrate fail, error.code: ' + error.code + 'error.message: ', + error.message); + return; + } + console.log('Callback returned to indicate a successful vibration.'); + }); + // Stop vibration in all modes. + vibrator.stopVibration(function (error) { + if (error) { + console.log('error.code' + error.code + 'error.message' + error.message); + return; + } + console.log('Callback returned to indicate successful.'); + }) + } catch (error) { + console.info('errCode: ' + error.code + ' ,msg: ' + error.message); + } + ``` + +5. Check whether the passed effect ID is supported. + + ```js + import vibrator from '@ohos.vibrator'; + try { + // Check whether 'haptic.clock.timer' is supported. + vibrator.isSupportEffect('haptic.clock.timer', function (err, state) { + if (err) { + console.error('isSupportEffect failed, error:' + JSON.stringify(err)); + return; + } + console.log('The effectId is ' + (state ? 'supported' : 'unsupported')); + if (state) { + try { + vibrator.startVibration({ // To use startVibration, you must configure the ohos.permission.VIBRATE permission. + type: 'preset', + effectId: 'haptic.clock.timer', + count: 1, + }, { + usage: 'unknown' + }, (error) => { + if(error) { + console.error('haptic.clock.timer vibrator error:' + JSON.stringify(error)); + } else { + console.log('haptic.clock.timer vibrator success'); + } + }); + } catch (error) { + console.error('Exception in, error:' + JSON.stringify(error)); + } + } + }) + } catch (error) { + console.error('Exception in, error:' + JSON.stringify(error)); + } + ``` diff --git a/en/application-dev/reference/apis/js-apis-vibrator.md b/en/application-dev/reference/apis/js-apis-vibrator.md index f99f74149b..383bc980e6 100644 --- a/en/application-dev/reference/apis/js-apis-vibrator.md +++ b/en/application-dev/reference/apis/js-apis-vibrator.md @@ -42,6 +42,7 @@ For details about the error codes, see [Vibrator Error Codes](../errorcodes/erro **Example** ```js +import vibrator from '@ohos.vibrator'; try { vibrator.startVibration({ type: 'time', @@ -95,6 +96,7 @@ For details about the error codes, see [Vibrator Error Codes](../errorcodes/erro **Example** ```js +import vibrator from '@ohos.vibrator'; try { vibrator.startVibration({ type: 'time', @@ -132,6 +134,7 @@ Stops vibration in the specified mode. This API uses an asynchronous callback to **Example** ```js +import vibrator from '@ohos.vibrator'; try { // Start vibration at a fixed duration. vibrator.startVibration({ @@ -190,6 +193,7 @@ Stops vibration in the specified mode. This API uses a promise to return the res **Example** ```js +import vibrator from '@ohos.vibrator'; try { // Start vibration at a fixed duration. vibrator.startVibration({ @@ -219,6 +223,213 @@ try { } ``` +## vibrator.stopVibration10+ + +stopVibration(callback: AsyncCallback<void>): void + +Stops vibration in all modes. 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 | +| -------- | ------------------------- | ---- | ------------------------------------------------------------ | +| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the vibration stops, **err** is **undefined**; otherwise, **err** is an error object.| + +**Example** + + ```js +import vibrator from '@ohos.vibrator'; +try { + // Start vibration at a fixed duration. + vibrator.startVibration({ + type: 'time', + duration: 1000, + }, { + id: 0, + usage: 'alarm' + }, (error) => { + if (error) { + console.error('vibrate fail, error.code: ' + error.code + 'error.message: ', + error.message); + return; + } + console.log('Callback returned to indicate a successful vibration.'); + }); +} catch (error) { + console.error('errCode: ' + error.code + ' ,msg: ' + error.message); +} + +try { + // Stop vibration in all modes. + vibrator.stopVibration(function (error) { + if (error) { + console.log('error.code' + error.code + 'error.message' + error.message); + return; + } + console.log('Callback returned to indicate successful.'); + }) +} catch (error) { + console.info('errCode: ' + error.code + ' ,msg: ' + error.message); +} + ``` + +## vibrator.stopVibration10+ + +stopVibration(): Promise<void> + +Stops vibration in all modes. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.VIBRATE + +**System capability**: SystemCapability.Sensors.MiscDevice + +**Return value** + +| Type | Description | +| ------------------- | ------------- | +| Promise<void> | Promise that returns no value.| + +**Example** + + ```js +import vibrator from '@ohos.vibrator'; +try { + // Start vibration at a fixed duration. + vibrator.startVibration({ + type: 'time', + duration: 1000 + }, { + id: 0, + usage: 'alarm' + }).then(() => { + console.log('Promise returned to indicate a successful vibration'); + }, (error) => { + console.error('error.code' + error.code + 'error.message' + error.message); + }); +} catch (error) { + console.error('errCode: ' + error.code + ' ,msg: ' + error.message); +} + +try { + // Stop vibration in all modes. + vibrator.stopVibration().then(() => { + console.log('Promise returned to indicate a successful vibration.'); + }, (error) => { + console.log('error.code' + error.code + 'error.message' + error.message); + }); +} catch (error) { + console.info('errCode: ' + error.code + ' ,msg: ' + error.message); +} + ``` + +## vibrator.isSupportEffect10+ + +isSupportEffect(effectId: string, callback: AsyncCallback<boolean>): void + +Checks whether the passed effect ID is supported. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Sensors.MiscDevice + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------------- | ---- | ------------------------------------------------------ | +| effectId | string | Yes | Vibration effect ID. | +| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the passed effect ID is supported, and **false** means the opposite. | + +**Example** + + ```js +import vibrator from '@ohos.vibrator'; +try { + // Check whether 'haptic.clock.timer' is supported. + vibrator.isSupportEffect('haptic.clock.timer', function (err, state) { + if (err) { + console.error('isSupportEffect failed, error:' + JSON.stringify(err)); + return; + } + console.log('The effectId is ' + (state ? 'supported' : 'unsupported')); + if (state) { + try { + vibrator.startVibration({ // To use startVibration, you must configure the ohos.permission.VIBRATE permission. + type: 'preset', + effectId: 'haptic.clock.timer', + count: 1, + }, { + usage: 'unknown' + }, (error) => { + if(error) { + console.error('haptic.clock.timer vibrator error:' + JSON.stringify(error)); + } else { + console.log('haptic.clock.timer vibrator success'); + } + }); + } catch (error) { + console.error('Exception in, error:' + JSON.stringify(error)); + } + } + }) +} catch (error) { + console.error('Exception in, error:' + JSON.stringify(error)); +} + ``` + +## vibrator.isSupportEffect10+ + +isSupportEffect(effectId: string): Promise<boolean> + +Checks whether the passed effect ID is supported. This API uses a promise to return the result. + +**System capability**: SystemCapability.Sensors.MiscDevice + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------ | ---- | ------------ | +| effectId | string | Yes | Vibration effect ID.| + +**Return value** + +| Type | Description | +| ---------------------- | --------------------------------------------------------- | +| Promise<boolean> | Promise that returns the result. The value **true** means that the passed effect ID is supported, and **false** means the opposite. | + +**Example** + + ```js +import vibrator from '@ohos.vibrator'; +try { + // Check whether 'haptic.clock.timer' is supported. + vibrator.isSupportEffect('haptic.clock.timer').then((state) => { + console.log('The effectId is ' + (state ? 'supported' : 'unsupported')); + if (state) { + try { + vibrator.startVibration({ + type: 'preset', + effectId: 'haptic.clock.timer', + count: 1, + }, { + usage: 'unknown' + }).then(()=>{ + console.log('Promise returned to indicate a successful vibration'); + }).catch((error)=>{ + console.error('Promise returned to indicate a failed vibration:' + JSON.stringify(error)); + }); + } catch (error) { + console.error('exception in, error:' + JSON.stringify(error)); + } + } + }, (error) => { + console.error('isSupportEffect failed, error:' + JSON.stringify(error)); + }) +} catch (error) { + console.error('Exception in, error:' + JSON.stringify(error)); +} + ``` + ## EffectId Describes the preset vibration effect ID. diff --git a/en/release-notes/changelogs/OpenHarmony_4.0.5.2/changelogs-miscdevice.md b/en/release-notes/changelogs/OpenHarmony_4.0.5.2/changelogs-miscdevice.md new file mode 100644 index 0000000000..100975f0ae --- /dev/null +++ b/en/release-notes/changelogs/OpenHarmony_4.0.5.2/changelogs-miscdevice.md @@ -0,0 +1,94 @@ +# Pan-sensor Subsystem Changelog + +## cl.vibrator Added isSupportEffect + +The **isSupportEffect** API is added. + +**Change Impact** + +Applications developed based on OpenHarmony4.0.5.2 or a later SDK version can use **isSupportEffect** to check whether the passed effect ID is supported. + +**Key API/Component Changes** + +The **isSupportEffect** API is added in **@ohos.vibrator.d.ts**. + +| Module| Class| Method/Attribute/Enum/Constant| Change Type| +| -- | -- | -- | -- | +| @ohos.vibrator.d.ts | vibrator | isSupportEffect(effectId: string, callback: AsyncCallback<boolean>): void | Added| +| @ohos.vibrator.d.ts | vibrator | isSupportEffect(effectId: string): Promise<boolean> | Added| + +**Adaptation Guide** + +Call **isSupportEffect** to check whether the passed effect ID is supported. + +```ts +import vibrator from '@ohos.vibrator'; +try { + // Check whether 'haptic.clock.timer' is supported. + vibrator.isSupportEffect('haptic.clock.timer', function (err, state) { + if (err) { + console.error('isSupportEffect failed, error:' + JSON.stringify(err)); + return; + } + console.log('The effectId is ' + (state ? 'supported' : 'unsupported')); + if (state) { + try { + vibrator.startVibration({ // To use startVibration, you must configure the ohos.permission.VIBRATE permission. + type: 'preset', + effectId: 'haptic.clock.timer', + count: 1, + }, { + usage: 'unknown' + }, (error) => { + if(error) { + console.error('haptic.clock.timer vibrator error:' + JSON.stringify(error)); + } else { + console.log('haptic.clock.timer vibrator success'); + } + }); + } catch (error) { + console.error('Exception in, error:' + JSON.stringify(error)); + } + } + }) +} catch (error) { + console.error('Exception in, error:' + JSON.stringify(error)); +} +``` + +## cl.vibrator Added stopVibration + +The **stopVibration** API is added. + +**Change Impact** + +Applications developed based on OpenHarmony4.0.5.2 or a later SDK version can use **stopVibration** to stop vibration in all modes. + +**Key API/Component Changes** + +The **stopVibration** API is added in **@ohos.vibrator.d.ts**. + +| Module | Class | Method/Attribute/Enum/Constant | Change Type| +| ------------------- | -------- | -------------------------------------------------------- | -------- | +| @ohos.vibrator.d.ts | vibrator | stopVibration(callback: AsyncCallback<void>): void | Added | +| @ohos.vibrator.d.ts | vibrator | stopVibration(): Promise<void> | Added | + +**Adaptation Guide** + +Call **stopVibration** to stop vibration in all modes. + +```ts +import vibrator from '@ohos.vibrator'; +try { + // Stop vibration in all modes. + vibrator.stopVibration(function (error) { + if (error) { + console.log('error.code' + error.code + 'error.message' + error.message); + return; + } + console.log('Callback returned to indicate successful.'); + }) +} catch (error) { + console.info('errCode: ' + error.code + ' ,msg: ' + error.message); +} +``` -- GitLab