!11301 多模开发指南

Merge pull request !11301 from mayunteng/master

zh-cn/application-dev/device/Readme-CN.md

@@ -13,6 +13,9 @@
 - 振动
   - [振动开发概述](vibrator-overview.md)
   - [振动开发指导](vibrator-guidelines.md)
+- 设备管理
+  - [输入设备开发指导](inputdevice-guidelines.md)
+  - [鼠标光标开发指导](pointerstyle-guidelines.md)
 - 升级服务
   - [示例服务器开发概述](sample-server-overview.md)
   - [示例服务器开发指导](sample-server-guidelines.md)

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

+# 输入设备开发指导
+
+## 场景介绍
+
+输入设备管理提供设备热插拔监听、查询指定设备的键盘类型等能力。使用场景例如：当用户需要输入文本时，输入法会根据当前是否插入了物理键盘来决定是否弹出虚拟键盘，开发者可以通过监听设备热插拔判断是否有物理键盘插入。
+
+## 导入模块
+
+```js
+import inputDevice from '@ohos.multimodalInput.inputDevice';
+```
+
+## 接口说明
+
+输入设备管理常用接口如下表所示，接口详细介绍请参考[ohos.multimodalInput.inputDevice文档](../reference/apis/js-apis-inputdevice.md)。
+
+| 实例名 | 接口名  | 说明 |
+| ----------- | ------------------------------------------------------------ | -------------------------- |
+| inputDevice | **function** getDeviceList(callback: AsyncCallback<Array<**number**>>): **void**; | 获取输入设备列表。 |
+| inputDevice | **function** getKeyboardType(deviceId: **number**, callback: AsyncCallback<KeyboardType>): **void**; | 获取输入设备的键盘类型。 |
+| inputDevice | **function** on(**type**: "change", listener: Callback<DeviceListener>): **void**; | 监听输入设备的热插拔事件。 |
+| inputDevice | **function** off(**type**: "change", listener?: Callback<DeviceListener>): **void**; | 取消监听输入设备的热插拔事件。 |
+
+## 虚拟键盘弹出检测
+
+当用户需要输入文本时，输入法会根据当前是否插入了物理键盘来决定是否弹出虚拟键盘，开发者可以通过监听设备热插拔，判断是否有物理键盘插入。
+
+## 开发步骤
+
+1. 调用getDeviceList方法查询所有连接的输入设备，调用getKeyboardType方法遍历所有连接的设备，判断是否有物理键盘，若有则标记已有物理键盘连接，该步骤确保监听设备热插拔之前，检测所有插入的输入设备。
+2. 调用on接口监听输入设备热插拔事件，若监听到有物理键盘插入，则标记已有物理键盘连接；若监听到有物理键盘拔掉，则标记没有物理键盘连接。
+3. 文本框进行输入时，判断是否有物理键盘连接，如果有物理键盘则不弹出虚拟键盘，如果没有物理键盘则弹出虚拟键盘。
+
+
+```js
+import inputDevice from '@ohos.multimodalInput.inputDevice';
+
+let isPhysicalKeyboardExist = true;
+try {
+  // 1.获取设备列表，判断是否有物理键盘连接
+  inputDevice.getDeviceList().then(data => {
+    for (let i = 0; i < data.length; ++i) {
+      inputDevice.getKeyboardType(data[i]).then(res => {
+        if (type == inputDevice.KeyboardType.ALPHABETIC_KEYBOARD) {
+          // 物理键盘已连接
+          isPhysicalKeyboardExist = true;
+        }
+      });
+    }
+  });
+  // 2.监听设备热插拔
+  inputDevice.on("change", (data) => {
+    console.log(`Device event info: ${JSON.stringify(data)}`);
+    inputDevice.getKeyboardType(data.deviceId, (error, type) => {
+      console.log("The keyboard type is: " + type);
+      if (type == inputDevice.KeyboardType.ALPHABETIC_KEYBOARD && data.type == 'add') {
+        // 物理键盘已插入
+        isPhysicalKeyboardExist = true;
+      } else if (type == inputDevice.KeyboardType.ALPHABETIC_KEYBOARD && data.type == 'remove') {
+        // 物理键盘已拔掉
+        isPhysicalKeyboardExist = false;
+      }
+    });
+  });
+} catch (error) {
+  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
+}
+  // 3.根据isPhysicalKeyboardExist的值决定虚拟键盘是否弹出
+  // TODO
+```

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

+# 鼠标光标开发指导
+
+## 场景介绍
+
+鼠标光标控制提供对鼠标光标显示隐藏、光标样式查询设置的能力。使用场景例如：用户在全屏观看视频时，开发者可以控制鼠标光标的显示隐藏；当用户执行取色时，开发者可以将鼠标光标样式切换为取色器样式。
+
+## 导入模块
+
+```js
+import inputDevice from '@ohos.multimodalInput.pointer';
+```
+
+## 接口说明
+
+鼠标光标控制常用接口如下表所示，接口详细介绍请参见[ohos.multimodalInput.pointer文档](../reference/apis/js-apis-pointer.md)
+
+| 实例名  | 接口名                                                       | 说明                                                         |
+| ------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
+| pointer | **function** isPointerVisible(callback: AsyncCallback<boolean>): **void**; | 获取鼠标指针显示或隐藏状态。                                 |
+| pointer | **function** setPointerVisible(visible: boolean, callback: AsyncCallback<**void**>): **void**; | 设置鼠标指针显示或隐藏状态，改接口会影响全局鼠标光标的显示状态。 |
+| pointer | **function** setPointerStyle(windowId: **number**, pointerStyle: PointerStyle, callback: AsyncCallback<**void**>): **void**; | 设置鼠标光标样式，改接口会影响指定窗口鼠标光标样式。         |
+| pointer | **function** getPointerStyle(windowId: **number**, callback: AsyncCallback<PointerStyle>): **void**; | 查询鼠标光标样式。                                           |
+
+## 设置鼠标光标隐藏
+
+用户在全屏观看视频时，可以调用鼠标光标的隐藏接口设置鼠标光标不可见，提升用户体验。
+
+## 开发步骤
+
+1. 应用切换到全屏播放。
+2. 在应用中调用鼠标光标隐藏接口隐藏光标。
+3. 应用退出全屏播放。
+4. 在应用中调用鼠标光标显示接口显示光标。
+
+```js
+import pointer from '@ohos.multimodalInput.pointer';
+
+// 1.应用切换到全屏播放
+// 2.调用鼠标光标隐藏接口隐藏光标
+try {
+  pointer.setPointerVisible(false, (error) => {
+    if (error) {
+      console.log(`Set pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
+      return;
+    }
+    console.log(`Set pointer visible success.`);
+  });
+} catch (error) {
+  console.log(`The mouse pointer hide attributes is failed. ${JSON.stringify(error, [`code`, `message`])}`);
+}
+
+// 3.应用退出全屏播放
+// 4.调用鼠标光标显示接口显示光标
+try {
+  pointer.setPointerVisible(true, (error) => {
+    if (error) {
+      console.log(`Set pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
+      return;
+    }
+    console.log(`Set pointer visible success.`);
+  });
+} catch (error) {
+  console.log(`Set pointer visible failed, ${JSON.stringify(error, [`code`, `message`])}`);
+}
+```
+
+## 设置鼠标光标样式
+
+当开发者设计取色器特性时，可以将鼠标光标样式切换为取色器样式，完成取色后，设置鼠标光标样式为默认样式，该接口设置和查询当前应用内指定窗口的光标样式，总共可设置39种光标样式，具体参考[光标样式](../reference/apis/js-apis-pointer.md#pointerstyle9)。
+
+### 开发步骤
+
+1. 开发者使能取色功能。
+2. 调用窗口实例获取对应的窗口id。
+3. 设置鼠标光标样式为取色器样式。
+4. 取色结束。
+5. 设置鼠标光标样式为默认样式。
+
+```js
+import window from '@ohos.window';
+
+// 1.开发者使能取色功能
+// 2.调用窗口实例获取对应的窗口id
+window.getTopWindow((error, windowClass) => {
+  windowClass.getProperties((error, data) => {
+    var windowId = data.id;
+    if (windowId < 0) {
+      console.log(`Invalid windowId`);
+      return;
+    }
+    try {
+      // 3.设置鼠标光标样式为取色器样式
+      pointer.setPointerStyle(windowId, pointer.PointerStyle.COLOR_SUCKER).then(() => {
+        console.log(`Successfully set mouse pointer style`);
+      });
+    } catch (error) {
+      console.log(`Failed to set the pointer style, error=${JSON.stringify(error)}, msg=${JSON.stringify(message)}`);
+    }
+  });
+});
+// 4.取色结束
+window.getTopWindow((error, windowClass) => {
+  windowClass.getProperties((error, data) => {
+    var windowId = data.id;
+    if (windowId < 0) {
+      console.log(`Invalid windowId`);
+      return;
+    }
+    try {
+      // 5.设置鼠标光标样式为默认样式
+      pointer.setPointerStyle(windowId, pointer.PointerStyle.DEFAULT).then(() => {
+        console.log(`Successfully set mouse pointer style`);
+      });
+    } catch (error) {
+      console.log(`Failed to set the pointer style, error=${JSON.stringify(error)}, msg=${JSON.stringify(message)}`);
+    }
+  });
+});
+```