Hhutingting_02040205翻译回稿：mdm audio input等等kit

@ohos.multimodalInput.inputConsumer (Global Shortcut Keys)

The inputConsumer module implements listening for combination key events as well as listening and interception for volume key events.

NOTE

The initial APIs of this module are supported since API version 14. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Global shortcut keys are combination keys defined by the system or application. System shortcut keys are defined by the system, and application shortcut keys are defined by applications.

Modules to Import

import { inputConsumer, KeyEvent } from '@kit.InputKit';

HotkeyOptions

Defines shortcut key options.

System capability: SystemCapability.MultimodalInput.Input.InputConsumer

Name	Type	Read-Only	Optional	Description
preKeys	Array<number>	No	No	Modifier key set (including Ctrl, Shift, and Alt). One to four modifier keys are supported. There is no requirement on the sequence of modifier keys. For example, in Ctrl+Shift+Esc, Ctrl and Shift are modifier keys.
finalKey	number	No	No	Modified key, which can be any key except the modifier keys and Meta key. For details about the keys, see @ohos.multimodalInput.keyCode (Keycode). For example, in Ctrl+Shift+Esc, Esc is the modifier key.
isRepeat	boolean	No	Yes	Whether to report repeated key events. The value true means to report repeated key events, and the value false means the opposite. The default value is true.

KeyPressedConfig¹⁶⁺

Sets the key event consumption configuration.

System capability: SystemCapability.MultimodalInput.Input.InputConsumer

Device behavior differences: In versions earlier than API version 23, this API can be properly called on phones and tablets. If it is called on other device types, error code 801 is returned. Starting from API version 23, this API can be properly called on phones, PCs/2-in-1 devices, tablets, TVs, and cars. If it is called on other device types, error code 801 is returned.

Name	Type	Read-Only	Optional	Description
key	number	No	No	Key value. Note: From API version 21, the KEYCODE_VOLUME_UP, KEYCODE_VOLUME_DOWN, KEYCODE_MEDIA_PLAY_PAUSE, KEYCODE_MEDIA_NEXT, and KEYCODE_MEDIA_PREVIOUS keys. In API version 20 or earlier versions, only the KEYCODE_VOLUME_UP and KEYCODE_VOLUME_DOWN keys are supported.
action	number	No	No	Subscription type. Note: Since API version 21, the value of this parameter can be 1 or 2. The value 1 indicates subscription to only key press events, and the value 2 indicates subscription to both key press and release events. In API version 20 or earlier versions, the value of this parameter can only be set to 1, indicating subscription to only key press events.
isRepeat	boolean	No	No	Whether to report repeated key events. The value true means to report repeated key events, and the value false means the opposite. The default value is true.

inputConsumer.getAllSystemHotkeys

getAllSystemHotkeys(): Promise<Array<HotkeyOptions>>

Obtains all system shortcut keys. This API uses a promise to return the result.

System capability: SystemCapability.MultimodalInput.Input.InputConsumer

Device behavior differences: This API can be properly called on devices other than wearables. If it is called on wearables, error code 801 is returned.

Return value

Type	Description
Promise<Array<HotkeyOptions>>	Promise used to return the list of all system shortcut keys.

Error codes:

For details about the error codes, see Universal Error Codes.

Error Code	Error Message
801	Capability not supported.

Example

import { inputConsumer } from '@kit.InputKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          inputConsumer.getAllSystemHotkeys().then((data: Array<inputConsumer.HotkeyOptions>) => {
            console.info(`List of system hotkeys : ${JSON.stringify(data)}`);
          }).catch((error: BusinessError) => {
            console.error(`Get all system hotkeys failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
          })
        })
    }
  }
}

inputConsumer.on('hotkeyChange')

on(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback: Callback<HotkeyOptions>): void

Subscribes to application shortcut key change events based on the specified options. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MultimodalInput.Input.InputConsumer

Device behavior differences: This API can be properly called on devices other than wearables. If it is called on wearables, error code 801 is returned.

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. This parameter has a fixed value of hotkeyChange.
hotkeyOptions	HotkeyOptions	Yes	Shortcut key options.
callback	Callback<HotkeyOptions>	Yes	Callback used to return the application shortcut key change event.

Error codes:

For details about the error codes, see Global Shortcut Key Error Codes and Universal Error Codes.

Error Code	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported.
4200002	The hotkey has been used by the system.
4200003	The hotkey has been subscribed to by another.

Example

import { inputConsumer } from '@kit.InputKit';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          let leftCtrlKey = 2072;
          let zKey = 2042;
          let hotkeyOptions: inputConsumer.HotkeyOptions = {
            preKeys: [leftCtrlKey],
            finalKey: zKey,
            isRepeat: true
          };
          let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
            console.info(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`);
          }
          try {
            inputConsumer.on("hotkeyChange", hotkeyOptions, hotkeyCallback);
          } catch (error) {
            console.error(`Subscribe failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
          }
        })
    }
  }
}

inputConsumer.off('hotkeyChange')

off(type: 'hotkeyChange', hotkeyOptions: HotkeyOptions, callback?: Callback<HotkeyOptions>): void

Unsubscribes from application shortcut key change events. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MultimodalInput.Input.InputConsumer

Device behavior differences: This API can be properly called on devices other than wearables. If it is called on wearables, error code 801 is returned.

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. This parameter has a fixed value of hotkeyChange.
hotkeyOptions	HotkeyOptions	Yes	Shortcut key options.
callback	Callback<HotkeyOptions>	No	Callback to unregister. If this parameter is left unspecified, listening will be disabled for all callbacks registered for the specified shortcut key options.

Error codes:

For details about the error codes, see Universal Error Codes.

Error Code	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported.

Example

import { inputConsumer } from '@kit.InputKit';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          let leftCtrlKey = 2072;
          let zKey = 2042;
          // Disable listening for a single callback.
          let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
            console.info(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`);
          }
          let hotkeyOption: inputConsumer.HotkeyOptions = { preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true };
          try {
            inputConsumer.on("hotkeyChange", hotkeyOption, hotkeyCallback);
            inputConsumer.off("hotkeyChange", hotkeyOption, hotkeyCallback);
            console.info(`Unsubscribe success`);
          } catch (error) {
            console.error(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
          }
        })
    }
  }
}

import { inputConsumer } from '@kit.InputKit';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          let leftCtrlKey = 2072;
          let zKey = 2042;
          // Disable listening for all callbacks.
          let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
            console.info(`hotkeyOptions: ${JSON.stringify(hotkeyOptions)}`);
          }
          let hotkeyOption: inputConsumer.HotkeyOptions = { preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: true };
          try {
            inputConsumer.on("hotkeyChange", hotkeyOption, hotkeyCallback);
            inputConsumer.off("hotkeyChange", hotkeyOption);
            console.info(`Unsubscribe success`);
          } catch (error) {
            console.error(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
          }
        })
    }
  }
}

inputConsumer.on('keyPressed')¹⁶⁺

on(type: 'keyPressed', options: KeyPressedConfig, callback: Callback<KeyEvent>): void

Subscribes to key press events. This API uses an asynchronous callback to return the result. If the current application is in the foreground focus window, a callback is triggered when the specified key is pressed.

If the API call is successful, the system's default response to the key event will be intercepted; that is, system-level actions, such as volume adjustment, will no longer be triggered. To restore the system response, call off to disable listening for the key event.

System capability: SystemCapability.MultimodalInput.Input.InputConsumer

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. This parameter has a fixed value of keyPressed.
options	KeyPressedConfig	Yes	Sets the key event consumption configuration.
callback	Callback<KeyEvent>	Yes	Callback used to return key press events. Ensure that different callbacks are used for different key events. Otherwise, the subscription does not take effect.

Error codes:

For details about the error codes, see Universal Error Codes.

Error Code	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported.

Example

import { inputConsumer, KeyEvent } from '@kit.InputKit';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          try {
            let options: inputConsumer.KeyPressedConfig = {
              key: 16,
              action: 1,
              isRepeat: false,
            }
            inputConsumer.on('keyPressed', options, (event: KeyEvent) => {
              console.info(`Subscribe success ${JSON.stringify(event)}`);
            });
          } catch (error) {
            console.error(`Subscribe execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
          }
        })
    }
  }
}

inputConsumer.off('keyPressed')¹⁶⁺

off(type: 'keyPressed', callback?: Callback<KeyEvent>): void

Unsubscribes from key press events. This API uses an asynchronous callback to return the result. If the API call is successful, the system's default response to the key event will be resumed; that is, system-level actions, such as volume adjustment, will be triggered normally.

System capability: SystemCapability.MultimodalInput.Input.InputConsumer

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. This parameter has a fixed value of keyPressed.
callback	Callback<KeyEvent>	No	Callback to unregister. If this parameter is not specified, listening will be disabled for all registered callbacks.

Error codes:

For details about the error codes, see Universal Error Codes.

Error Code	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported.

Example

import { inputConsumer, KeyEvent } from '@kit.InputKit';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          try {
            // Disable listening for a single callback.
            let options: inputConsumer.KeyPressedConfig = {
              key: 16,
              action: 1,
              isRepeat: false,
            }
            let callback = (event: KeyEvent) => {
              console.info(`Unsubscribe success ${JSON.stringify(event)}`);
            }
            inputConsumer.on('keyPressed', options, callback);
            inputConsumer.off('keyPressed', callback);
            // Disable listening for all callbacks.
            inputConsumer.off("keyPressed");
          } catch (error) {
            console.error(`Unsubscribe execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
          }
        })
    }
  }
}

@ohos.multimodalInput.inputConsumer (Global Shortcut Keys)

Modules to Import

HotkeyOptions

KeyPressedConfig16+

inputConsumer.getAllSystemHotkeys

inputConsumer.on('hotkeyChange')

inputConsumer.off('hotkeyChange')

inputConsumer.on('keyPressed')16+

inputConsumer.off('keyPressed')16+

KeyPressedConfig¹⁶⁺

inputConsumer.on('keyPressed')¹⁶⁺

inputConsumer.off('keyPressed')¹⁶⁺