harmony 鸿蒙Combination Key Development

2025-06-06
浏览 (2)

Combination Key Development

When to Use

The inputConsumer module provides capabilities such as subscribing to combination key events and setting the key shielding status. For example, if an application needs to implement a shortcut function using combination keys, you can listen for combination key events to serve that purpose.

Modules to Import

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

Available APIs

The following table lists the common APIs provided by the inputConsumer module. For details, see ohos.multimodalInput.inputConsumer-sys and ohos.multimodalInput.inputConsumer.

API	Description
on(type: ‘key’, keyOptions: KeyOptions, callback: Callback<KeyOptions>): void	Enables listening for combination key events.
off(type: ‘key’, keyOptions: KeyOptions, callback?: Callback<KeyOptions>): void	Disables listening for combination key events.
setShieldStatus(shieldMode: ShieldMode, isShield: boolean): void	Sets the key shielding status.
getShieldStatus(shieldMode: ShieldMode): boolean	Checks whether key shielding is enabled.
getAllSystemHotkeys(): Promise<Array<HotkeyOptions>>	Obtains all system combination keys.
on(type: ‘hotkeyChange’, hotkeyOptions: HotkeyOptions, callback: Callback<HotkeyOptions>): void	Enables listening for global combination key events.
off(type: ‘hotkeyChange’, hotkeyOptions: HotkeyOptions, callback?: Callback<HotkeyOptions>): void	Disables listening for global combination key events.

How to Develop

When an application that uses specific combination keys is started, on is called to subscribe to combination key events.

When the application is stopped, off is called to unsubscribe from combination key events.

let leftAltKey = 2045;
let tabKey = 2049;
let callback = (keyOptions: inputConsumer.KeyOptions) => {
  console.log(`keyOptions: ${JSON.stringify(keyOptions)}`);
}
// Start the application.
let keyOption: inputConsumer.KeyOptions = {preKeys: [leftAltKey], finalKey: tabKey, isFinalKeyDown: true, finalKeyDownDuration: 0};
try {
  inputConsumer.on("key", keyOption, callback);// Listen for combination key events.
} catch (error) {
  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
}
// Stop the application.
try {
  inputConsumer.off("key", keyOption, callback);// Disable listening for combination key events.
  console.log(`Unsubscribe success`);
} catch (error) {
  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
}

let leftCtrlKey = 2072;
let zKey = 2042;
let hotkeyCallback = (hotkeyOptions: inputConsumer.HotkeyOptions) => {
  console.log(`keyOptions: ${JSON.stringify(hotkeyOptions)}`);
}
let hotkeyOption: inputConsumer.HotkeyOptions = {preKeys: [leftCtrlKey], finalKey: zKey, isRepeat: false};
// Before subscribing to global combination keys, obtain all system combination keys and check whether the combination keys to subscribe are on the system combination key list.
inputConsumer.getAllSystemHotkeys().then((data: Array<inputConsumer.HotkeyOptions>) => {//: Obtain all system combination keys.
  console.log(`List of system hotkeys : ${JSON.stringify(data)}`);
});
// Start the application.
try {
  inputConsumer.on("hotkeyChange", hotkeyOption, hotkeyCallback);// Subscribe to global combination keys.
} catch (error) {
  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
}
// Stop the application.
try {
  inputConsumer.off("hotkeyChange", hotkeyOption, hotkeyCallback);// Unsubscribe from global combination keys.
  console.log(`Unsubscribe success`);
} catch (error) {
  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
}