fix docs: add interface VibrateFromFile, HapticFileDescriptor

Signed-off-by: Nlixiangpeng5 <lixiangpeng5@huawei.com>
Change-Id: I93396239c43be942b1e123a4ce8ceb6ba81590da

zh-cn/application-dev/device/vibrator-guidelines.md

@@ -21,6 +21,121 @@
 | ohos.vibrator | isSupportEffect(effectId: string): Promise<boolean>    | 查询是否支持传入的参数effectId。返回true则表示支持，否则不支持 |
 | ohos.vibrator | isSupportEffect(effectId: string, callback: AsyncCallback<boolean>): void | 查询是否支持传入的参数effectId。返回true则表示支持，否则不支持 |
 
+## 自定义振动支持的格式
+自定义振动配置文件为Json格式，在形式上如下所示：
+
+   ```js
+   {
+    "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
+                        }
+                    }
+                }
+            ]
+        }
+    ]
+   }
+   ```
+
+Json共包含2个属性。"MetaData"：文件头信息，可在相应属性中添加描述，必填项："Version"表示文件格式的版本号，向前兼容，目前起步仅支持版本1.0；"ChannelNumber"表示马达振动的通道数，目前仅支持单通道，规定为1。其他为选填项："Create"可记录文件创作时间；"Description"可指明振动效果、创建信息等附加说明。"Channels"：马达振动通道的相关信息。
+
+   ```js
+   {
+    "MetaData": {
+        "Create": "2023-01-09",
+        "Description": "a haptic case",
+        "Version": 1.0,
+        "ChannelNumber": 1
+    },
+    "Channels": [ ... ]
+   }
+   ```
+
+"Channels"是Json数组，表示各个通道的信息，包含两个属性。"Parameters"：对改通道参数设置。"Index"为通道编号，单通道下规定为1，其他参数待后续扩展。"Pattern"：为马达振动序列，为Json数组。
+
+   ```js
+   "Channels": [
+        {
+            "Parameters": {
+                "Index": 1
+            },
+            "Pattern": [ ... ]
+        }
+   ]
+   ```
+
+"Pattern"中每个"Event"属性代表1个振动事件，支持添加2种振动类型。类型1："transient"类型，瞬态短振动，干脆有力；类型2："continuous"类型，稳态长振动，具备长时间输出强劲有力振动的能力。
+
+   ```js
+   "Pattern": [
+        {
+            "Event": {
+                "Type": "transient",
+                "StartTime": 0,
+                "Parameters": {
+                    "Intensity": 100,
+                    "Frequency": 31
+                }
+            }
+        },
+        {
+            "Event": {
+                "Type": "continuous",
+                "StartTime": 100,
+                "Duration": 54,
+                "Parameters": {
+                    "Intensity": 38,
+                    "Frequency": 30
+                }
+            }
+        }
+    ]
+   ```
+
+振动事件参数信息具体如下表：
+
+| 参数 | 说明 | 范围|
+| --- | ------------------------ | ---|
+| Type | 振动事件类型 | "transient" 或"continuous"|
+| StartTime | 振动的起始时间 | 单位ms，有效范围为[0, 1800 000]，且振动事件不能重叠|
+| Duration | 振动持续时间，仅当类型为"continuous"时可用 | 单位ms，有效范围为(10, 1600)|
+| Intensity | 振动强度 | 有效范围为[0, 100]，这里的强度值为相对值，并不代表真实强度|
+| Frequency | 振动频率 | 有效范围为[0, 100]，这里的频率值为相对值，并不代表真实频率|
+
+其他要求：
+
+| 参数 | 要求                 |
+| -------- | ------------------------ |
+| 振动事件(event)的数量 | 不得超过128个 |
+| 振动配置文件长度 | 不得超过64KB |
 
 ## 开发步骤
 
@@ -136,7 +251,64 @@
    }
    ```
 
-   
+6. 启动和停止自定义振动
+
+   ```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);
+        });
+    }
+
+    // 获取振动文件资源描述符
+    let rawFd = openResource(FILE_NAME);
+    // 使用startVibration、stopVibration需要添加ohos.permission.VIBRATE权限
+    try {
+        // 启动自定义振动
+        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');
+        });
+        // 停止所有类型的马达振动
+        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);
+    }
+    // 关闭振动文件资源
+    closeResource(FILE_NAME);
+   ```
 
 ## 相关实例
 

zh-cn/application-dev/reference/apis/js-apis-vibrator.md

@@ -462,6 +462,7 @@ try {
 | -------------------------------- | ------------------------------ |
 | [VibrateTime](#vibratetime9)     | 按照指定持续时间触发马达振动。 |
 | [VibratePreset](#vibratepreset9) | 按照预置振动类型触发马达振动。 |
+| [VibrateFromFile](#vibratefromfile10) | 按照振动配置文件触发马达振动。 |
 
 ## VibrateTime<sup>9+</sup>
 
@@ -486,6 +487,29 @@ try {
 | effectId | -        | 预置的振动效果ID。             |
 | count    | -        | 重复振动的次数。               |
 
+## VibrateFromFile<sup>10+</sup>
+
+自定义振动类型，仅部分设备支持。
+
+**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.MiscDevice
+
+| 名称     | 值       | 说明                           |
+| -------- | -------- | ------------------------------ |
+| type     | "file" | 按照振动配置文件触发马达振动。 |
+| hapticFd | -        | 振动配置文件的描述符，类型为[HapticFileDescriptor](#hapticfiledescriptor10)。             |
+
+## HapticFileDescriptor<sup>10+</sup>
+
+自定义振动配置文件描述符，必须确认资源文件可用，可通过[文件管理API](js-apis-file-fs.md#fsopen)从沙箱路径获取或者通过[资源管理API](js-apis-resource-manager.md#getrawfd9)从HAP资源获取。使用场景：振动序列被存储在一个文件中，需要根据偏移量和长度进行振动，振动序列存储格式，请参考[自定义振动格式](../../device/vibrator-guidelines.md#自定义振动支持的格式)。
+
+**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.MiscDevice
+
+| 名称     | 类型      |  必填  | 说明                           |
+| -------- | -------- |--------| ------------------------------ |
+| fd       | number   |  是    | 文件描述符。                  |
+| offset   | number   |  否    | 文件指针起始偏移量，默认值为文件起始位置。             |
+| length   | number   |  否    | 文件长度，默认值为从偏移位置至文件结尾的大小。                             |
+
 ## VibrateAttribute<sup>9+</sup>
 
 马达振动属性。

zh-cn/release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-miscdevice.md

+# 泛Sensor子系统Changelog
+
+## cl.vibrator.1 新增自定义振动相关属性
+
+新增自定义振动相关属性VibrateFromFile，HapticFileDescriptor。
+
+**变更影响**
+
+基于OpenHarmony4.0.8.2及之后的SDK版本开发的应用，可使用VibrateFromFile属性播放自定义振动文件中配置的振动序列。
+
+**关键接口/组件变更**
+
+@ohos.vibrator.d.ts中新增属性VibrateFromFile，HapticFileDescriptor。
+
+| 模块名 | 类名 | 方法/属性/枚举/常量 | 变更类型 |
+|  -- | -- | -- | -- |
+| @ohos.vibrator.d.ts | vibrator | HapticFileDescriptor | 新增 |
+| @ohos.vibrator.d.ts | vibrator | VibrateFromFile | 新增 |
+
+**适配指导**<br>
+
+通过资源管理接口获取振动配置文件资源，启动自定义振动并停止。
+
+```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);
+    });
+}
+
+// 获取振动文件资源描述符
+let rawFd = openResource(FILE_NAME);
+// 使用startVibration、stopVibration需要添加ohos.permission.VIBRATE权限
+try {
+    // 启动自定义振动
+    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');
+    });
+    // 停止所有类型的马达振动
+    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);
+}
+// 关闭振动文件资源
+closeResource(FILE_NAME);
+```