!19432 Add attribute of VibrateFromFile & HapticFileDescriptor.

Merge pull request !19432 from lixiangpeng5/master-lxp

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

@@ -22,124 +22,265 @@
 | ohos.vibrator | isSupportEffect(effectId: string, callback: AsyncCallback<boolean>): void | 查询是否支持传入的参数effectId。返回true则表示支持，否则不支持 |
 
 
+## 自定义振动格式
+
+自定义振动提供给用户设计自己所需振动效果的能力，用户可通过自定义振动配置文件，并遵循相应规则编排所需振动形式，使能更加开放的振感交互体验。
+
+自定义振动配置文件为Json格式，在形式上如下所示：
+
+```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
+                        }
+                    }
+                }
+            ]
+        }
+    ]
+}
+```
+
+Json文件共包含2个属性。
+- "MetaData"属性中为文件头信息，可在如下属性中添加描述。<br>
+"Version"：必填项，文件格式的版本号，向前兼容，目前起步仅支持版本1.0；<br>
+"ChannelNumber"：必填项，表示马达振动的通道数，目前仅支持单通道，规定为1；<br>
+"Create"：可选项，可记录文件创作时间；<br>
+"Description"：可选项，可指明振动效果、创建信息等附加说明。<br>
+- "Channels"属性中为马达振动通道的相关信息。<br>
+
+"Channels"是Json数组，表示各个通道的信息，包含2个属性。
+- "Parameters"属性中为通道参数。<br>
+"Index"：必填项，表示通道编号，单通道下规定为1。<br>
+- "Pattern"属性中为马达振动序列。<br>
+
+"Pattern"是Json数组，每个"Event"属性代表1个振动事件，支持添加2种振动类型。
+- 类型1："transient"类型，瞬态短振动，干脆有力；<br>
+- 类型2："continuous"类型，稳态长振动，具备长时间输出强劲有力振动的能力。<br>
+
+振动事件参数信息具体如下表：
+
+| 参数 | 说明 | 范围|
+| --- | ------------------------ | ---|
+| Type | 振动事件类型，必填 | "transient" 或"continuous"|
+| StartTime | 振动的起始时间，必填 | 单位ms，有效范围为[0, 1800 000]，振动事件不能重叠|
+| Duration | 振动持续时间，仅当类型为"continuous"时有效 | 单位ms，有效范围为(10, 1600)|
+| Intensity | 振动强度，必填 | 有效范围为[0, 100]，这里的强度值为相对值，并不代表真实强度|
+| Frequency | 振动频率，必填 | 有效范围为[0, 100]，这里的频率值为相对值，并不代表真实频率|
+
+其他要求：
+
+| 参数 | 要求                 |
+| -------- | ------------------------ |
+| 振动事件(event)的数量 | 不得超过128个 |
+| 振动配置文件长度 | 不得超过64KB |
+
+
 ## 开发步骤
 
 1. 控制设备上的振动器，需要申请权限ohos.permission.VIBRATE。具体配置方式请参考[权限申请声明](../security/accesstoken-guidelines.md)。
 
 2. 根据指定振动效果和振动属性触发马达振动。
 
-   ```js
-   import vibrator from '@ohos.vibrator';
-   try {
-       vibrator.startVibration({ // 使用startVibration需要添加ohos.permission.VIBRATE权限
-           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 (err) {
-       console.error('errCode: ' + err.code + ' ,msg: ' + err.message);
-   }
-   ```
+```js
+import vibrator from '@ohos.vibrator';
+try {
+    vibrator.startVibration({ // 使用startVibration需要添加ohos.permission.VIBRATE权限
+        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 (err) {
+    console.error('errCode: ' + err.code + ' ,msg: ' + err.message);
+}
+```
 
 3. 按照指定模式停止马达的振动。 
 
-   ```js
-   import vibrator from '@ohos.vibrator';
-   try {
-     // 按照VIBRATOR_STOP_MODE_TIME模式停止振动， 使用stopVibration需要添加ohos.permission.VIBRATE权限
-     vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_TIME, function (error) {
-         if (error) {
-             console.log('error.code' + error.code + 'error.message' + error.message);
-             return;
-         }
-         console.log('Callback returned to indicate successful.');
-     })
-   } catch (err) {
-     console.info('errCode: ' + err.code + ' ,msg: ' + err.message);
-   }
-   ```
-   
+```js
+import vibrator from '@ohos.vibrator';
+try {
+    // 按照VIBRATOR_STOP_MODE_TIME模式停止振动， 使用stopVibration需要添加ohos.permission.VIBRATE权限
+    vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_TIME, function (error) {
+        if (error) {
+            console.log('error.code' + error.code + 'error.message' + error.message);
+            return;
+        }
+        console.log('Callback returned to indicate successful.');
+    })
+} catch (err) {
+    console.info('errCode: ' + err.code + ' ,msg: ' + err.message);
+}
+```
+
 4. 停止所有模式的马达振动。
 
-   ```js
-   import vibrator from '@ohos.vibrator';
-   // 使用startVibration、stopVibration需要添加ohos.permission.VIBRATE权限
-   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.');
-       });
-       // 停止所有类型的马达振动
-       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);
-   }
-   ```
+```js
+import vibrator from '@ohos.vibrator';
+// 使用startVibration、stopVibration需要添加ohos.permission.VIBRATE权限
+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.');
+    });
+    // 停止所有类型的马达振动
+    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. 查询是否支持传入的参数effectId。
 
-   ```js
-   import vibrator from '@ohos.vibrator';
-   try {
-       // 查询是否支持'haptic.clock.timer'
-       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({ // 使用startVibration需要添加ohos.permission.VIBRATE权限
-                       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));
-   }
-   ```
-
-   
+```js
+import vibrator from '@ohos.vibrator';
+try {
+    // 查询是否支持'haptic.clock.timer'
+    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({ // 使用startVibration需要添加ohos.permission.VIBRATE权限
+                    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));
+}
+```
+
+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);
+```
+
 
 ## 相关实例
 
 针对振动开发，有以下相关实例可供参考：
 
-- [`Vibrator`：振动（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/DeviceManagement/Vibrator)
\ No newline at end of file
+- [`Vibrator`：振动（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/DeviceManagement/Vibrator/BasicVibration)
+- [`CustomHaptic`：自定义振动（ArkTS）（API10）](https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/DeviceManagement/Vibrator/CustomHaptic)

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

@@ -434,7 +434,7 @@ try {
 
 预置的振动效果。
 
-**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.MiscDevice
+**系统能力**：SystemCapability.Sensors.MiscDevice
 
 | 名称               | 值                   | 说明                             |
 | ------------------ | -------------------- | -------------------------------- |
@@ -445,7 +445,7 @@ try {
 
 停止的振动模式。
 
-**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.MiscDevice
+**系统能力**：SystemCapability.Sensors.MiscDevice
 
 | 名称                      | 值       | 说明                           |
 | ------------------------- | -------- | ------------------------------ |
@@ -456,52 +456,76 @@ try {
 
 马达振动效果。
 
-**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.MiscDevice
+**系统能力**：SystemCapability.Sensors.MiscDevice
 
 | 类型                             | 说明                           |
 | -------------------------------- | ------------------------------ |
 | [VibrateTime](#vibratetime9)     | 按照指定持续时间触发马达振动。 |
 | [VibratePreset](#vibratepreset9) | 按照预置振动类型触发马达振动。 |
+| [VibrateFromFile<sup>10+</sup>](#vibratefromfile10) | 按照自定义振动配置文件触发马达振动。 |
 
 ## VibrateTime<sup>9+</sup>
 
 马达振动时长。
 
-**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.MiscDevice
+**系统能力**：SystemCapability.Sensors.MiscDevice
 
-| 名称     | 值 | 说明                           |
+| 名称     | 类型 | 说明                           |
 | -------- | ------ | ------------------------------ |
-| type     | "time" | 按照指定持续时间触发马达振动。 |
-| duration | -      | 马达持续振动时长, 单位ms。         |
+| type     | string | 值为"time"，按照指定持续时间触发马达振动。 |
+| duration | number | 马达持续振动时长, 单位ms。         |
 
 ## VibratePreset<sup>9+</sup>
 
 马达预置振动类型。
 
-**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.MiscDevice
+**系统能力**：SystemCapability.Sensors.MiscDevice
 
-| 名称     | 值       | 说明                           |
+| 名称     | 类型       | 说明                           |
 | -------- | -------- | ------------------------------ |
-| type     | "preset" | 按照预置振动效果触发马达振动。 |
-| effectId | -        | 预置的振动效果ID。             |
-| count    | -        | 重复振动的次数。               |
+| type     | string | 值为"preset"，按照预置振动效果触发马达振动。 |
+| effectId | string | 预置的振动效果ID。             |
+| count    | number | 重复振动的次数。               |
+
+## VibrateFromFile<sup>10+</sup>
+
+自定义振动类型，仅部分设备支持。
+
+**系统能力**：SystemCapability.Sensors.MiscDevice
+
+| 名称     | 类型       | 说明                           |
+| -------- | --------  | ------------------------------ |
+| type     | string    | 值为"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>
 
 马达振动属性。
 
-**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.MiscDevice
+**系统能力**：SystemCapability.Sensors.MiscDevice
 
-| 名称  | 值 | 说明           |
+| 名称  | 类型 | 说明           |
 | ----- | ------ | -------------- |
-| id    | 0      | 振动器id。     |
-| usage | -      | 马达振动的使用场景。 |
+| id    | number      | 默认值为0，振动器id。     |
+| usage | [Usage](#usage9)      | 马达振动的使用场景。 |
 
 ## Usage<sup>9+</sup>
 
 振动使用场景。
 
-**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.MiscDevice
+**系统能力**：SystemCapability.Sensors.MiscDevice
 
 | 名称             | 类型   | 说明                           |
 | ---------------- | ------ | ------------------------------ |

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

+# 泛Sensor子系统Changelog
+
+
+## cl.vibrator.1 新增自定义振动相关属性
+
+新增自定义振动效果属性VibrateFromFile，自定义振动配置文件描述符属性HapticFileDescriptor；振动下发接口startVibration支持的振动效果由VibrateEffect = VibrateTime | VibratePreset扩展为VibrateEffect = VibrateTime | VibratePreset | VibrateFromFile。
+
+**变更影响**
+
+基于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);
+```