!12818 翻译已完成11301+11354

Merge pull request !12818 from shawn_he/11301-a

en/application-dev/device/Readme-EN.md

@@ -13,6 +13,9 @@
 - Vibrator
   - [Vibrator Overview](vibrator-overview.md)
   - [Vibrator Development](vibrator-guidelines.md)
+- Multimodal Input
+  - [Input Device Development](inputdevice-guidelines.md)
+  - [Mouse Pointer Development](pointerstyle-guidelines.md)
 - Update Service
   - [Sample Server Overview](sample-server-overview.md)
   - [Sample Server Development](sample-server-guidelines.md)

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

+# Input Device Development
+
+## When to Use
+
+Input device management provides functions such as listening for device hot swap events and querying the keyboard type of a specified device. For example, as a user enters text, the input method determines whether to launch the virtual keyboard based on whether a physical keyboard is currently inserted. Your application can determine whether a physical keyboard is inserted by listening to device hot swap events.
+
+## Modules to Import
+
+```js
+import inputDevice from '@ohos.multimodalInput.inputDevice';
+```
+
+## Available APIs
+
+The following table lists the common APIs for input device management. For details about the APIs, see [ohos.multimodalInput.inputDevice](../reference/apis/js-apis-inputdevice.md).
+
+| Instance| API | Description|
+| ----------- | ------------------------------------------------------------ | -------------------------- |
+| inputDevice | function getDeviceList(callback: AsyncCallback\<Array\<number>>): void; | Obtains the list of input devices.|
+| inputDevice | function getKeyboardType(deviceId: number, callback: AsyncCallback\<KeyboardType>): void; | Obtains the keyboard type of the input device.|
+| inputDevice | function on(type: "change", listener: Callback\<DeviceListener>): void; | Enables listening for device hot swap events.|
+| inputDevice | function off(type: "change", listener?: Callback\<DeviceListener>): void; | Disables listening for device hot swap events.|
+
+## Virtual Keyboard Detection
+
+When a user enters text, the input method determines whether to launch the virtual keyboard based on whether a physical keyboard is currently inserted. Your application can determine whether a physical keyboard is inserted by listening to device hot swap events.
+
+## How to Develop
+
+1. Call the **getDeviceList** API to obtain the list of connected input devices. Call the **getKeyboardType** API to traverse all connected devices to check whether a physical keyboard exists. If a physical keyboard exists, mark the physical keyboard as connected. This step ensures that your application detects all inserted input devices before listening for device hot swap events.
+2. Call the **on** API to listen for device hot swap events. If a physical keyboard is inserted, mark the physical keyboard as connected. If a physical keyboard is removed, mark the physical keyboard as disconnected.
+3. When a user enters text, check whether a physical keyboard is connected. If a physical keyboard is not connected, launch the virtual keyboard.
+
+
+```js
+import inputDevice from '@ohos.multimodalInput.inputDevice';
+
+let isPhysicalKeyboardExist = true;
+try {
+  // 1. Obtain the list of input devices and check whether a physical keyboard is connected.
+  inputDevice.getDeviceList().then(data => {
+    for (let i = 0; i < data.length; ++i) {
+      inputDevice.getKeyboardType(data[i]).then(res => {
+        if (type == inputDevice.KeyboardType.ALPHABETIC_KEYBOARD) {
+          // The physical keyboard is connected.
+          isPhysicalKeyboardExist = true;
+        }
+      });
+    }
+  });
+  // 2. Listen for device hot swap events.
+  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') {
+        // The physical keyboard is inserted.
+        isPhysicalKeyboardExist = true;
+      } else if (type == inputDevice.KeyboardType.ALPHABETIC_KEYBOARD && data.type == 'remove') {
+        // The physical keyboard is removed.
+        isPhysicalKeyboardExist = false;
+      }
+    });
+  });
+} catch (error) {
+  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
+}
+  // 3. Determine whether to launch the virtual keyboard based on the value of isPhysicalKeyboardExist.
+  // TODO
+```

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

+# Mouse Pointer Development
+
+## When to Use
+
+Mouse pointer management provides the functions such as displaying or hiding the mouse pointer as well as querying and setting the pointer style. For example, you can determine whether to display or hide the mouse pointer when a user watches a video in full screen, and can switch the mouse pointer to a color picker when a user attempts color pickup.
+
+## Modules to Import
+
+```js
+import inputDevice from '@ohos.multimodalInput.pointer';
+```
+
+## Available APIs
+
+The following table lists the common APIs for mouse pointer management. For details about the APIs, see [ohos.multimodalInput.pointer](../reference/apis/js-apis-pointer.md).
+
+| Instance | API                                                      | Description                                                        |
+| ------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
+| pointer | function isPointerVisible(callback: AsyncCallback\<boolean>): void; | Checks the visible status of the mouse pointer.                                |
+| pointer | function setPointerVisible(visible: boolean, callback: AsyncCallback\<void>): void; | Sets the visible status of the mouse pointer. This setting takes effect for the mouse pointer globally.|
+| pointer | function setPointerStyle(windowId: number, pointerStyle: PointerStyle, callback: AsyncCallback\<void>): void; | Sets the mouse pointer style. This setting takes effect for the mouse pointer style of a specified window.        |
+| pointer | function getPointerStyle(windowId: number, callback: AsyncCallback\<PointerStyle>): void; | Obtains the mouse pointer style.                                          |
+
+## Hiding the Mouse Pointer
+
+When watching a video in full-screen mode, a user can hide the mouse pointer for an improved user experience.
+
+## How to Develop
+
+1. Switch to the full-screen playback mode.
+2. Hide the mouse pointer.
+3. Exit the full-screen playback mode.
+4. Display the mouse pointer.
+
+```js
+import pointer from '@ohos.multimodalInput.pointer';
+
+// 1. Switch to the full-screen playback mode.
+// 2. Hide the mouse pointer.
+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. Exit the full-screen playback mode.
+// 4. Display the mouse pointer.
+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`])}`);
+}
+```
+
+## Setting the Mouse Pointer Style
+
+When designing a color picker, you can have the mouse pointer switched to the color picker style during color pickup and then switched to the default style on completion of color pickup. This setting takes effect for the pointer style of a specified window in the current application. A total of 39 pointer styles can be set. For details, see [Pointer Style](../reference/apis/js-apis-pointer.md#pointerstyle9).
+
+### How to Develop
+
+1. Enable the color pickup function.
+2. Obtain the window ID.
+3. Set the mouse pointer to the color picker style.
+4. End color pickup.
+5. Set the mouse pointer to the default style.
+
+```js
+import window from '@ohos.window';
+
+// 1. Enable the color pickup function.
+// 2. Obtain the window ID.
+window.getTopWindow((error, windowClass) => {
+  windowClass.getProperties((error, data) => {
+    var windowId = data.id;
+    if (windowId < 0) {
+      console.log(`Invalid windowId`);
+      return;
+    }
+    try {
+      // 3. Set the mouse pointer to the color picker style.
+      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. End color pickup.
+window.getTopWindow((error, windowClass) => {
+  windowClass.getProperties((error, data) => {
+    var windowId = data.id;
+    if (windowId < 0) {
+      console.log(`Invalid windowId`);
+      return;
+    }
+    try {
+      // 5. Set the mouse pointer to the default style.
+      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)}`);
+    }
+  });
+});
+```

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

@@ -197,12 +197,12 @@ Disables listening for hot swap events of an input device.
 **Example**
 
 ```js
-callback: function(data) {
+function callback(data) {
   console.log("type: " + data.type + ", deviceId: " + data.deviceId);
 }
 
 try {
-  inputDevice.on("change", this.callback);
+  inputDevice.on("change", callback);
 } catch (error) {
   console.info("oninputdevcie " + error.code + " " + error.message)
 }
@@ -212,7 +212,7 @@ inputDevice.on("change", listener);
 
 // Disable this listener.
 try {
-  inputDevice.off("change", this.callback);
+  inputDevice.off("change", callback);
 } catch (error) {
   console.info("offinputdevcie " + error.code + " " + error.message)
 }