From ecb33e8645a599a549592737187c816eb78a82f5 Mon Sep 17 00:00:00 2001 From: lixiangpeng5 Date: Thu, 8 Jun 2023 09:41:55 +0000 Subject: [PATCH] fix docs: add interface VibrateFromFile, HapticFileDescriptor Signed-off-by: lixiangpeng5 Change-Id: I93396239c43be942b1e123a4ce8ceb6ba81590da --- .../device/vibrator-guidelines.md | 174 +++++++++++++++++- .../reference/apis/js-apis-vibrator.md | 24 +++ .../changelogs-miscdevice.md | 79 ++++++++ 3 files changed, 276 insertions(+), 1 deletion(-) create mode 100755 zh-cn/release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-miscdevice.md diff --git a/zh-cn/application-dev/device/vibrator-guidelines.md b/zh-cn/application-dev/device/vibrator-guidelines.md index b30c4bac26..54368c79bf 100644 --- a/zh-cn/application-dev/device/vibrator-guidelines.md +++ b/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); + ``` ## 相关实例 diff --git a/zh-cn/application-dev/reference/apis/js-apis-vibrator.md b/zh-cn/application-dev/reference/apis/js-apis-vibrator.md index eb5fe8765d..079dd9d142 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-vibrator.md +++ b/zh-cn/application-dev/reference/apis/js-apis-vibrator.md @@ -462,6 +462,7 @@ try { | -------------------------------- | ------------------------------ | | [VibrateTime](#vibratetime9) | 按照指定持续时间触发马达振动。 | | [VibratePreset](#vibratepreset9) | 按照预置振动类型触发马达振动。 | +| [VibrateFromFile](#vibratefromfile10) | 按照振动配置文件触发马达振动。 | ## VibrateTime9+ @@ -486,6 +487,29 @@ try { | effectId | - | 预置的振动效果ID。 | | count | - | 重复振动的次数。 | +## VibrateFromFile10+ + +自定义振动类型，仅部分设备支持。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.MiscDevice + +| 名称 | 值 | 说明 | +| -------- | -------- | ------------------------------ | +| type | "file" | 按照振动配置文件触发马达振动。 | +| hapticFd | - | 振动配置文件的描述符，类型为[HapticFileDescriptor](#hapticfiledescriptor10)。 | + +## HapticFileDescriptor10+ + +自定义振动配置文件描述符，必须确认资源文件可用，可通过[文件管理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 | 否 | 文件长度，默认值为从偏移位置至文件结尾的大小。 | + ## VibrateAttribute9+ 马达振动属性。 diff --git a/zh-cn/release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-miscdevice.md b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-miscdevice.md new file mode 100755 index 0000000000..af4dc7de3e --- /dev/null +++ b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-miscdevice.md @@ -0,0 +1,79 @@ +# 泛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 | 新增 | + +**适配指导**
+ +通过资源管理接口获取振动配置文件资源，启动自定义振动并停止。 + +```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); +``` -- GitLab