Update docs against 19432+19792

Signed-off-by: wusongqing<wusongqing@huawei.com>

en/application-dev/device/vibrator-guidelines.md

@@ -18,8 +18,85 @@ For details about the APIs, see [Vibrator](../reference/apis/js-apis-vibrator.md
 | 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. |
+| 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.|
+
+
+## Custom Vibration Format
+
+Custom vibration enables you to design desired vibration effects by customizing a vibration configuration file and orchestrating vibration forms based on the corresponding rules.
+
+The custom vibration configuration file is in JSON format. An example file is as follows:
+
+```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
+                        }
+                    }
+                }
+            ]
+        }
+    ]
+}
+```
+
+This JSON file contains two attributes: **MetaData** and **Channels**.
+- **MetaData** contains information about the file header. You can add the following attributes under **MetaData**:
+  - **Version**: version number of the file format, which is forward compatible. Currently, only version 1.0 is supported. This parameter is mandatory.
+  - **ChannelNumber**: number of channels for vibration. Currently, only one channel is supported, and the value is fixed at **1**. This parameter is mandatory.
+  - **Create**: time when the file was created. This parameter is optional.
+  - **Description**: additional information such as the vibration effect and creation information. This parameter is optional.
+- **Channels** provides information about the vibration channel. It is a JSON array that holds information about each channel. It contains two attributes: **Parameters** and **Pattern**.
+- **Parameters** provides parameters related to the channel. Under it, **Index** indicates the channel ID. The value is fixed at **1** for a single channel. This parameter is mandatory.
+  - **Pattern** indicates the vibration sequence. It is a JSON array. Under it, **Event** indicates a vibration event, which can be either of the following types:
+  - **transient**: short vibration
+  - **continuous**: long vibration
+
+The table below describes the parameters under **Event**.
+
+| Parameter| Description| Value or Value Range|
+| --- | ------------------------ | ---|
+| Type | Type of the vibration event. This parameter is mandatory.| **transient** or **continuous**|
+| StartTime | Start time of the vibration. This parameter is mandatory.| [0, 1800 000], in ms, without overlapping|
+| Duration | Duration of the vibration. This parameter is valid only when **Type** is **continuous**.| (10, 1600), in ms|
+| Intensity | Intensity of the vibration. This parameter is mandatory.| [0, 100], a relative value that does not represent the actual vibration strength.|
+| Frequency | Frequency of the vibration. This parameter is mandatory.| [0, 100], a relative value that does not represent the actual vibration frequency|
+
+The following requirements must be met:
+
+| Item| Description                |
+| -------- | ------------------------ |
+| Number of vibration events| No more than 128|
+| Length of the vibration configuration file| Not greater than 64 KB|
 
 
 ## How to Develop
@@ -135,3 +212,63 @@ For details about the APIs, see [Vibrator](../reference/apis/js-apis-vibrator.md
        console.error('Exception in, error:' + JSON.stringify(error));
    }
    ```
+
+6. Start and stop custom vibration.
+
+   ```js
+   import vibrator from '@ohos.vibrator';
+   import resourceManager from '@ohos.resourceManager';
+   
+   const FILE_NAME = "xxx.json";
+   
+   async function openResource(fileName) {
+       let fileDescriptor = undefined;
+       let mgr = await resourceManager.getResourceManager();
+       await mgr.getRawFd(fileName).then(value => {
+           fileDescriptor = {fd: value.fd, offset: value.offset, length: value.length};
+           console.log('openResource success fileName: ' + fileName);
+       }).catch(error => {
+           console.log('openResource err: ' + error);
+       });
+       return fileDescriptor;
+   }
+   
+   async function closeResource(fileName) {
+       let mgr = await resourceManager.getResourceManager();
+       await mgr.closeRawFd(fileName).then(()=> {
+           console.log('closeResource success fileName: ' + fileName);
+       }).catch(error => {
+           console.log('closeResource err: ' + error);
+       });
+   }
+   
+   // Obtain the file descriptor of the vibration configuration file.
+   let rawFd = openResource(FILE_NAME);
+   // To use startVibration and stopVibration, you must configure the ohos.permission.VIBRATE permission.
+   try {
+       // Start custom vibration.
+       vibrator.startVibration({
+           type: "file",
+           hapticFd: { fd: rawFd.fd, offset: rawFd.offset, length: rawFd.length }
+       }, {
+           usage: "alarm"
+       }).then(() => {
+           console.info('startVibration success');
+       }, (error) => {
+           console.info('startVibration error');
+       });
+       // 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);
+   }
+   // Close the vibration configuration file.
+   closeResource(FILE_NAME);
+   ```
+

en/application-dev/reference/apis/js-apis-vibrator.md

@@ -460,8 +460,9 @@ Describes the vibration effect.
 
 | Type                            | Description                          |
 | -------------------------------- | ------------------------------ |
-| [VibrateTime](#vibratetime9)     | Triggers vibration with the specified duration. This API uses a promise to return the result.|
+| [VibrateTime](#vibratetime9)     | Vibration with the specified duration.|
 | [VibratePreset](#vibratepreset9) | Vibration with a preset effect.|
+| [VibrateFromFile<sup>10+</sup>](#vibratefromfile10) | Vibration according to a custom vibration configuration file.|
 
 ## VibrateTime<sup>9+</sup>
 
@@ -469,10 +470,10 @@ Describes the vibration with the specified duration.
 
 **System capability**: SystemCapability.Sensors.MiscDevice
 
-| Name    | Value| Description                          |
-| -------- | ------ | ------------------------------ |
-| type     | "time" | Vibration with the specified duration.|
-| duration | -      | Vibration duration, in ms.        |
+| Name    | Type   | Mandatory| Description                          |
+| -------- | ------ | ----- | ------------------------------ |
+| type     | string |  Yes  | The value **time** means vibration with the specified duration.|
+| duration | number |  Yes  | Vibration duration, in ms.        |
 
 ## VibratePreset<sup>9+</sup>
 
@@ -480,11 +481,34 @@ Describes the vibration with a preset effect.
 
 **System capability**: SystemCapability.Sensors.MiscDevice
 
-| Name    | Value      | Description                          |
-| -------- | -------- | ------------------------------ |
-| type     | "preset" | Vibration with the specified effect.|
-| effectId | -        | Preset vibration effect ID.            |
-| count    | -        | Number of vibrations to repeat.              |
+| Name    | Type     | Mandatory| Description                          |
+| -------- | -------- | ---- |------------------------------ |
+| type     | string   |  Yes | The value **preset** means vibration with the specified effect.|
+| effectId | string   |  Yes | Preset vibration effect ID.            |
+| count    | number   |  Yes | Number of vibrations to repeat.              |
+
+## VibrateFromFile<sup>10+</sup>
+
+Describes the custom vibration type, which is supported only by certain devices.
+
+**System capability**: SystemCapability.Sensors.MiscDevice
+
+| Name    | Type      | Mandatory| Description                          |
+| -------- | --------  | ---- | ------------------------------ |
+| type     | string    |  Yes | The value **file** means vibration according to a vibration configuration file.|
+| hapticFd | [HapticFileDescriptor](#hapticfiledescriptor10) | Yes| File descriptor (FD) of the vibration configuration file.|
+
+## HapticFileDescriptor<sup>10+</sup>
+
+Describes the FD of a custom vibration configuration file. Ensure that the file is available, and the parameters in it can be obtained from the sandbox path through the [file management API](js-apis-file-fs.md#fsopen) or from the HAP resource through the [resource management API](js-apis-resource-manager.md#getrawfd9). The use case is as follows: The system triggers vibration according to the sequence set in a configuration file, based on the specified offset and length. For details about the storage format of the vibration sequence, see [Custom Vibration Format](../../device/vibrator-guidelines.md#custom-vibration-format).
+
+**System capability**: SystemCapability.Sensors.MiscDevice
+
+| Name    | Type     |  Mandatory | Description                          |
+| -------- | -------- |--------| ------------------------------|
+| fd       | number   |  Yes   | FD of the custom vibration configuration file.               |
+| offset   | number   |  No   | Offset from the start position of the file, in bytes. The default value is the start position of the file, and the value cannot exceed the valid range of the file.|
+| length   | number   |  No   | Resource length, in bytes. The default value is the length from the offset position to the end of the file, and the value cannot exceed the valid range of the file.|
 
 ## VibrateAttribute<sup>9+</sup>
 
@@ -492,10 +516,10 @@ Describes the vibration attribute.
 
 **System capability**: SystemCapability.Sensors.MiscDevice
 
-| Name | Value| Description          |
-| ----- | ------ | -------------- |
-| id    | 0      | Vibrator ID.    |
-| usage | -      | Vibration scenario.|
+| Name | Type| Mandatory| Description          |
+| ----- | ------ | ---- | -------------- |
+| id    | number      |  No| Vibrator ID. The default value is 0.    |
+| usage | [Usage](#usage9)      | Yes| Vibration scenario.|
 
 ## Usage<sup>9+</sup>
 

en/release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-miscdevice.md

+# Pan-sensor Subsystem Changelog
+
+
+## cl.vibrator.1 Added Attributes Related to Custom Vibration
+
+The attributes **VibrateFromFile** (custom vibration effect) and **HapticFileDescriptor** (file descriptor of the custom vibration configuration file) are added. The vibration effect supported by **startVibration** is extended from **VibrateEffect = VibrateTime | VibratePreset** to **VibrateEffect = VibrateTime | VibratePreset | VibrateFromFile**.
+
+**Change Impact**
+
+When developing applications based on OpenHarmony4.0.8.2 and later SDK versions, you can use the **VibrateFromFile** attribute to enable devices that support custom vibration to trigger vibration according to the vibration sequence configured in the custom vibration configuration file.
+
+**Key API/Component Changes**
+
+Added the **VibrateFromFile** and **HapticFileDescriptor** attributes to **@ohos.vibrator.d.ts**.
+
+| Module| Class| Method/Attribute/Enum/Constant| Change Type|
+|  -- | -- | -- | -- |
+| @ohos.vibrator.d.ts | vibrator | HapticFileDescriptor | Added|
+| @ohos.vibrator.d.ts | vibrator | VibrateFromFile | Added|
+
+**Adaptation Guide**
+
+Obtain the resources in the vibration configuration file through the resource management API, and start or stop custom vibration as required.
+
+```ts
+import vibrator from '@ohos.vibrator';
+import resourceManager from '@ohos.resourceManager';
+
+const FILE_NAME = "xxx.json";
+
+async function openResource(fileName) {
+    let fileDescriptor = undefined;
+    let mgr = await resourceManager.getResourceManager();
+    await mgr.getRawFd(fileName).then(value => {
+        fileDescriptor = {fd: value.fd, offset: value.offset, length: value.length};
+        console.log('openResource success fileName: ' + fileName);
+    }).catch(error => {
+        console.log('openResource err: ' + error);
+    });
+    return fileDescriptor;
+}
+
+async function closeResource(fileName) {
+    let mgr = await resourceManager.getResourceManager();
+    await mgr.closeRawFd(fileName).then(()=> {
+        console.log('closeResource success fileName: ' + fileName);
+    }).catch(error => {
+        console.log('closeResource err: ' + error);
+    });
+}
+
+// Obtain the file descriptor of the vibration configuration file.
+let rawFd = openResource(FILE_NAME);
+// To use startVibration and stopVibration, you must configure the ohos.permission.VIBRATE permission.
+try {
+    // Start custom vibration.
+    vibrator.startVibration({
+        type: "file",
+        hapticFd: { fd: rawFd.fd, offset: rawFd.offset, length: rawFd.length }
+    }, {
+        usage: "alarm"
+    }).then(() => {
+        console.info('startVibration success');
+    }, (error) => {
+        console.info('startVibration error');
+    });
+    // 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);
+}
+// Close the vibration configuration file.
+closeResource(FILE_NAME);
+```