@ohos.inputMethodEngine (Input Method Service)

The inputMethodEngine module is oriented to input method applications (including system and third-party input method applications). With the APIs of this module, input method applications are able to create soft keyboard windows, insert or delete characters, select text, and listen for physical keyboard events.

NOTE

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

Modules to Import

import { inputMethodEngine } from '@kit.IMEKit';

Constants

Provides the constant values of function keys, edit boxes, and the cursor.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Type	Value	Description
ENTER_KEY_TYPE_UNSPECIFIED	number	0	No function is specified for the key.
ENTER_KEY_TYPE_GO	number	2	Key that executes a command or navigates to a specific location.
ENTER_KEY_TYPE_SEARCH	number	3	Key that initiates a search operation.
ENTER_KEY_TYPE_SEND	number	4	Key that sends the text to its target.
ENTER_KEY_TYPE_NEXT	number	5	Key that moves the focus to the next item in a sequence.
ENTER_KEY_TYPE_DONE	number	6	Key that indicates that a task or input is complete.
ENTER_KEY_TYPE_PREVIOUS	number	7	Key that moves the focus to the previous item in a sequence.
ENTER_KEY_TYPE_NEWLINE12+	number	8	Key that inserts a new line.
PATTERN_NULL	number	-1	Any type of edit box.
PATTERN_TEXT	number	0	Text edit box.
PATTERN_NUMBER	number	2	Number edit box.
PATTERN_PHONE	number	3	Phone number edit box.
PATTERN_DATETIME	number	4	Date edit box.
PATTERN_EMAIL	number	5	Email edit box.
PATTERN_URI	number	6	URI edit box.
PATTERN_PASSWORD	number	7	Password edit box.
PATTERN_PASSWORD_NUMBER11+	number	8	Numeric password edit box.
PATTERN_PASSWORD_SCREEN_LOCK11+	number	9	Screen lock password edit box.
PATTERN_USER_NAME20+	number	10	User name edit box.
PATTERN_NEW_PASSWORD20+	number	11	New password edit box.
PATTERN_NUMBER_DECIMAL20+	number	12	Edit box for numbers with decimal points.
PATTERN_ONE_TIME_CODE20+	number	13	Verification code edit box.
OPTION_ASCII	number	20	ASCII values are allowed.
OPTION_NONE	number	0	No input attribute is specified.
OPTION_AUTO_CAP_CHARACTERS	number	2	Characters are allowed.
OPTION_AUTO_CAP_SENTENCES	number	8	Sentences are allowed.
OPTION_AUTO_WORDS	number	4	Words are allowed.
OPTION_MULTI_LINE	number	1	Multiple lines are allowed.
OPTION_NO_FULLSCREEN	number	10	Half-screen style.
FLAG_SELECTING	number	2	The edit box is being selected.
FLAG_SINGLE_LINE	number	1	The edit box allows only single-line input.
DISPLAY_MODE_PART	number	0	The edit box is displayed in half-screen mode.
DISPLAY_MODE_FULL	number	1	The edit box is displayed in full screen.
CURSOR_UP9+	number	1	The caret moves upward.
CURSOR_DOWN9+	number	2	The caret moves downward.
CURSOR_LEFT9+	number	3	The caret moves leftward.
CURSOR_RIGHT9+	number	4	The caret moves rightward.
WINDOW_TYPE_INPUT_METHOD_FLOAT9+	number	2105	The input method is displayed in a floating window.

inputMethodEngine.getInputMethodAbility⁹⁺

getInputMethodAbility(): InputMethodAbility

Obtains an InputMethodAbility instance for the input method. This API can be called only by an input method.
The input method can use the obtained instance to subscribe to a soft keyboard display/hide request event, create/destroy an input method panel, and the like.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
InputMethodAbility	InputMethodAbility instance.

Example

let InputMethodAbility: inputMethodEngine.InputMethodAbility = inputMethodEngine.getInputMethodAbility();

inputMethodEngine.getKeyboardDelegate⁹⁺

getKeyboardDelegate(): KeyboardDelegate

Obtains a KeyboardDelegate instance for the input method.
The input method can use the obtained instance to subscribe to a physical keyboard event, text selection change event, and more.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
KeyboardDelegate	KeyboardDelegate instance.

Example

let KeyboardDelegate: inputMethodEngine.KeyboardDelegate = inputMethodEngine.getKeyboardDelegate();

inputMethodEngine.getInputMethodEngine^(deprecated)

getInputMethodEngine(): InputMethodEngine

Obtains an InputMethodEngine instance for the input method.
The input method can use the obtained instance to subscribe to a soft keyboard display/hide request event.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use getInputMethodAbility instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
InputMethodEngine	InputMethodAbility instance.

Example

let InputMethodEngine: inputMethodEngine.InputMethodEngine = inputMethodEngine.getInputMethodEngine();

inputMethodEngine.createKeyboardDelegate^(deprecated)

createKeyboardDelegate(): KeyboardDelegate

Obtains a KeyboardDelegate instance for the input method. The input method can use the obtained instance to subscribe to a physical keyboard event, text selection change event, and more.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use getKeyboardDelegate instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
KeyboardDelegate	KeyboardDelegate instance.

Example

let keyboardDelegate: inputMethodEngine.KeyboardDelegate = inputMethodEngine.createKeyboardDelegate();

CommandDataType¹²⁺

type CommandDataType = number | string | boolean;

Defines the private data type, which varies depending on its function.

System capability: SystemCapability.MiscServices.InputMethodFramework

Type	Description
number	Number.
string	String.
boolean	Boolean.

SizeChangeCallback¹⁵⁺

type SizeChangeCallback = (size: window.Size, keyboardArea?: KeyboardArea) => void

Callback triggered when the size of the input method panel changes.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
size	window.Size	Yes	Panel size.
keyboardArea	KeyboardArea	No	Size of the keyboard area.

InputMethodEngine^(deprecated)

NOTE

This API is supported since API version 8 and deprecated since API version 23. You are advised to use InputMethodAbility instead.

In the following API examples, you must first use getInputMethodEngine to obtain an InputMethodEngine instance, and then call the APIs using the obtained instance.

on('inputStart')^(deprecated)

on(type: 'inputStart', callback: (kbController: KeyboardController, textInputClient: TextInputClient) => void): void

Enables listening for the input method binding event. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 23. You are advised to use InputMethodAbility#on instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'inputStart'.
callback	(kbController: KeyboardController, textInputClient: TextInputClient) => void	Yes	Callback used to return the KeyboardController and TextInputClient instances.

Example

inputMethodEngine.getInputMethodEngine()
  .on('inputStart',
    (kbController: inputMethodEngine.KeyboardController, textClient: inputMethodEngine.TextInputClient) => {
      let keyboardController: inputMethodEngine.KeyboardController = kbController;
      let textInputClient: inputMethodEngine.TextInputClient = textClient;
    });

off('inputStart')^(deprecated)

off(type: 'inputStart', callback?: (kbController: KeyboardController, textInputClient: TextInputClient) => void): void

Disables listening for the input method binding event.

NOTE

This API is supported since API version 8 and deprecated since API version 23. You are advised to use InputMethodAbility#off instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'inputStart'.
callback	(kbController: KeyboardController, textInputClient: TextInputClient) => void	No	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getInputMethodEngine()
  .off('inputStart',
    (kbController: inputMethodEngine.KeyboardController, textClient: inputMethodEngine.TextInputClient) => {
      console.info('delete inputStart notification.');
    });

on('keyboardShow'|'keyboardHide')^(deprecated)

on(type: 'keyboardShow'|'keyboardHide', callback: () => void): void

Enables listening for a keyboard visibility event. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 23. You are advised to use InputMethodAbility#on instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. - The value 'keyboardShow' indicates the keyboard display event. - The value 'keyboardHide' indicates the keyboard hiding event.
callback	() => void	Yes	Callback used to return the result.

Example

inputMethodEngine.getInputMethodEngine().on('keyboardShow', () => {
  console.info('inputMethodEngine keyboardShow.');
});
inputMethodEngine.getInputMethodEngine().on('keyboardHide', () => {
  console.info('inputMethodEngine keyboardHide.');
});

off('keyboardShow'|'keyboardHide')^(deprecated)

off(type: 'keyboardShow'|'keyboardHide', callback?: () => void): void

Disables listening for a keyboard visibility event. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 23. You are advised to use InputMethodAbility#off instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. - The value 'keyboardShow' indicates the keyboard display event. - The value 'keyboardHide' indicates the keyboard hiding event.
callback	() => void	No	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getInputMethodEngine().off('keyboardShow');
inputMethodEngine.getInputMethodEngine().off('keyboardHide');

InputMethodAbility

In the following API examples, you must first use getInputMethodAbility to obtain an InputMethodAbility instance, and then call the APIs using the obtained instance.

on('inputStart')⁹⁺

on(type: 'inputStart', callback: (kbController: KeyboardController, inputClient: InputClient) => void): void

Enables listening for the input method binding event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'inputStart'.
callback	(kbController: KeyboardController, inputClient: InputClient) => void	Yes	Callback used to return instances related to input method operations.

Example

inputMethodEngine.getInputMethodAbility()
  .on('inputStart',
    (kbController: inputMethodEngine.KeyboardController, client: inputMethodEngine.InputClient) => {
      let keyboardController: inputMethodEngine.KeyboardController = kbController;
      let inputClient: inputMethodEngine.InputClient = client;
    });

off('inputStart')⁹⁺

off(type: 'inputStart', callback?: (kbController: KeyboardController, inputClient: InputClient) => void): void

Disables listening for the input method binding event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'inputStart'.
callback	(kbController: KeyboardController, inputClient: InputClient) => void	No	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getInputMethodAbility().off('inputStart');

on('inputStop')⁹⁺

on(type: 'inputStop', callback: () => void): void

Enables listening for the input method unbinding event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'inputStop'.
callback	() => void	Yes	Callback used to return the result.

Example

inputMethodEngine.getInputMethodAbility().on('inputStop', () => {
  console.info('inputMethodAbility inputStop');
});

off('inputStop')⁹⁺

off(type: 'inputStop', callback: () => void): void

Disables listening for the input method stop event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'inputStop'.
callback	() => void	Yes	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getInputMethodAbility().off('inputStop', () => {
  console.info('inputMethodAbility delete inputStop notification.');
});

on('setCallingWindow')⁹⁺

on(type: 'setCallingWindow', callback: (wid: number) => void): void

Enables listening for the window invocation setting event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'setCallingWindow'.
callback	(wid: number) => void	Yes	Callback used to return the window ID of the caller.

Example

inputMethodEngine.getInputMethodAbility().on('setCallingWindow', (wid: number) => {
  console.info('inputMethodAbility setCallingWindow');
});

off('setCallingWindow')⁹⁺

off(type: 'setCallingWindow', callback: (wid:number) => void): void

Disables listening for the window invocation setting event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'setCallingWindow'.
callback	(wid:number) => void	Yes	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getInputMethodAbility().off('setCallingWindow', (wid: number) => {
  console.info('inputMethodAbility delete setCallingWindow notification.');
});

on('keyboardShow'|'keyboardHide')⁹⁺

on(type: 'keyboardShow'|'keyboardHide', callback: () => void): void

Enables listening for a keyboard visibility event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. - The value 'keyboardShow' indicates the keyboard display event. - The value 'keyboardHide' indicates the keyboard hiding event.
callback	() => void	Yes	Callback used to return the result.

Example

inputMethodEngine.getInputMethodAbility().on('keyboardShow', () => {
  console.info('InputMethodAbility keyboardShow.');
});
inputMethodEngine.getInputMethodAbility().on('keyboardHide', () => {
  console.info('InputMethodAbility keyboardHide.');
});

off('keyboardShow'|'keyboardHide')⁹⁺

off(type: 'keyboardShow'|'keyboardHide', callback?: () => void): void

Disables listening for a keyboard visibility event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. - The value 'keyboardShow' indicates the keyboard display event. - The value 'keyboardHide' indicates the keyboard hiding event.
callback	() => void	No	Callback used to return the result.

Example

inputMethodEngine.getInputMethodAbility().off('keyboardShow', () => {
  console.info('InputMethodAbility delete keyboardShow notification.');
});
inputMethodEngine.getInputMethodAbility().off('keyboardHide', () => {
  console.info('InputMethodAbility delete keyboardHide notification.');
});

on('setSubtype')⁹⁺

on(type: 'setSubtype', callback: (inputMethodSubtype: InputMethodSubtype) => void): void

Enables listening for the input method subtype setting event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'setSubtype'.
callback	(inputMethodSubtype: InputMethodSubtype) => void	Yes	Callback used to return the input method subtype.

Example

import { InputMethodSubtype } from '@kit.IMEKit';

inputMethodEngine.getInputMethodAbility().on('setSubtype', (inputMethodSubtype: InputMethodSubtype) => {
  console.info('InputMethodAbility setSubtype.');
});

off('setSubtype')⁹⁺

off(type: 'setSubtype', callback?: (inputMethodSubtype: InputMethodSubtype) => void): void

Disables listening for the input method subtype setting event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'setSubtype'.
callback	(inputMethodSubtype: InputMethodSubtype) => void	No	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getInputMethodAbility().off('setSubtype', () => {
  console.info('InputMethodAbility delete setSubtype notification.');
});

on('securityModeChange')¹¹⁺

on(type: 'securityModeChange', callback: Callback< SecurityMode>): void

Enables listening for the security mode changes of the input method. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'securityModeChange'.
callback	Callback<SecurityMode>	Yes	Callback used to return the current security mode.

Example

inputMethodEngine.getInputMethodAbility()
  .on('securityModeChange', (securityMode: inputMethodEngine.SecurityMode) => {
    console.info(`InputMethodAbility securityModeChange, security is ${securityMode}`);
  });

off('securityModeChange')¹¹⁺

off(type: 'securityModeChange', callback?: Callback< SecurityMode>): void

Disables listening for the security mode changes of the input method. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'securityModeChange'.
callback	Callback<SecurityMode>	No	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

let securityChangeCallback: (securityMode: inputMethodEngine.SecurityMode) => void =
  (securityMode: inputMethodEngine.SecurityMode) => {
    console.info(`InputMethodAbility securityModeChange, security is ${securityMode}`);
  };
let inputMethodAbility: inputMethodEngine.InputMethodAbility = inputMethodEngine.getInputMethodAbility();
inputMethodAbility.on('securityModeChange', securityChangeCallback);
inputMethodAbility.off('securityModeChange', securityChangeCallback);

on('privateCommand')¹²⁺

on(type: 'privateCommand', callback: Callback<Record<string, CommandDataType>>): void;

Enables listening for the private data event of the input method. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'privateCommand'.
callback	Callback<Record<string, CommandDataType>>	Yes	Callback used to return the private data sent to the input method application.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
12800010	not the preconfigured default input method.

Example

let privateCommandCallback: (record: Record<string, inputMethodEngine.CommandDataType>) => void =
  (record: Record<string, inputMethodEngine.CommandDataType>) => {
    for (let i :number = 0; i < record.length; i++) {
      console.info(`private command key: ${i}, value: ${record[i]}`);
    }
  }
inputMethodEngine.getInputMethodAbility().on('privateCommand', privateCommandCallback);

off('privateCommand')¹²⁺

off(type: 'privateCommand', callback?: Callback<Record<string, CommandDataType>>): void

Disables listening for the private data event of the input method. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'privateCommand'.
callback	Callback<Record<string, CommandDataType>>	No	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
12800010	not the preconfigured default input method.

Example

let privateCommandCallback: (record: Record<string, inputMethodEngine.CommandDataType>) => void =
  (record: Record<string, inputMethodEngine.CommandDataType>) => {
    for (let i: number = 0; i < record.length; i++) {
      console.info(`private command key: ${i}, value: ${record[i]}`);
    }
  }

inputMethodEngine.getInputMethodAbility().off('privateCommand', privateCommandCallback);

on('callingDisplayDidChange')¹⁸⁺

on(type: 'callingDisplayDidChange', callback: Callback<number>): void

Enables listening for changes of the screen ID of the window associated with the edit box. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'callingDisplayDidChange'.
callback	Callback<number>	Yes	Callback used to return the screen ID of the window corresponding to the edit box.

Error codes

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

ID	Error Message
801	capability not supported.

Example

let callingDisplayDidChangeCallback: (num: number) => void = (num: number) => {
  console.info(`display id: ${num}`);
}
inputMethodEngine.getInputMethodAbility().on('callingDisplayDidChange', callingDisplayDidChangeCallback);

off('callingDisplayDidChange')¹⁸⁺

off(type: 'callingDisplayDidChange', callback?: Callback<number>): void

Disables listening for changes of the screen ID of the window associated with the edit box. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'callingDisplayDidChange'.
callback	Callback<number>	No	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getInputMethodAbility().off('callingDisplayDidChange', (num: number) => {
  console.info('InputMethodAbility delete calling display  notification.');
});

on('discardTypingText')²⁰⁺

on(type: 'discardTypingText', callback: Callback<void>): void

Subscribes to the event of discarding candidate words and sends the event to the input method. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'discardTypingText'. - 'discardTypingText': indicates subscribing to the event of discarding candidate words and sending the event to the input method.
callback	Callback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Example

inputMethodEngine.getInputMethodAbility().on('discardTypingText', () => {
  console.info('InputMethodAbility discard the typing text.');
});

off('discardTypingText')²⁰⁺

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

Unsubscribes from the event of discarding candidate words and sends the event to the input method. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'discardTypingText'. - 'discardTypingText': indicates unsubscribing from the event of discarding candidate words and sending the event to the input method.
callback	Callback<void>	No	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getInputMethodAbility().off('discardTypingText', () => {
  console.info('InputMethodAbility discard the typing text.');
});

getSecurityMode¹¹⁺

getSecurityMode(): SecurityMode

Obtains the current security mode of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
SecurityMode	Security mode.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
12800004	not an input method application.

Example

let security: inputMethodEngine.SecurityMode = inputMethodEngine.getInputMethodAbility().getSecurityMode();
console.error(`getSecurityMode, securityMode is : ${security}`);

createPanel¹⁰⁺

createPanel(ctx: BaseContext, info: PanelInfo, callback: AsyncCallback<Panel>): void

Creates an input method panel. This API can be called only by the input method application in the InputMethodExtensionAbility class. This API uses an asynchronous callback to return the result.

NOTE

Only one SOFT_KEYBOARD panel and one STATUS_BAR panel can be created for a single input method.
The input method panel does not support subwindows. For example, subwindows cannot be created using APIs such as window.createWindow, bindContextMenu, and CustomDialog. You are advised to adopt alternative solutions to sub-windows, such as using a dialog box or bindMenu, or set showInSubwindow to false.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
ctx	BaseContext	Yes	Current context of the input method.
info	PanelInfo	Yes	Information about the input method panel.
callback	AsyncCallback<Panel>	Yes	Callback used to return the result. If the operation is successful, the created input method panel is returned.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
12800004	not an input method application.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { inputMethodEngine, InputMethodExtensionAbility } from '@kit.IMEKit';
import { Want } from '@kit.AbilityKit';

let panelInfo: inputMethodEngine.PanelInfo = {
  type: inputMethodEngine.PanelType.SOFT_KEYBOARD,
  flag: inputMethodEngine.PanelFlag.FLG_FIXED
}

class InputMethodExt extends InputMethodExtensionAbility {
    onCreate(want: Want): void {
        console.info(`onCreate, want: ${want.abilityName}`);
        if (!this.context) {
            inputMethodEngine.getInputMethodAbility()
            .createPanel(this.context, panelInfo, (err: BusinessError, panel: inputMethodEngine.Panel) => {
                if (err) {
                console.error(`Failed to createPanel. Code is ${err.code}, message is ${err.message}`);
                return;
              }
                console.info('Succeed in creating panel.');
            })
        }
    }
}

createPanel¹⁰⁺

createPanel(ctx: BaseContext, info: PanelInfo): Promise<Panel>

Creates an input method panel. This API can be called only by the input method application in the InputMethodExtensionAbility class. This API uses a promise to return the result.

NOTE

Only one SOFT_KEYBOARD panel and one STATUS_BAR panel can be created for a single input method.
The input method panel does not support subwindows. For example, subwindows cannot be created using APIs such as window.createWindow, bindContextMenu, and CustomDialog. You are advised to adopt alternative solutions to sub-windows, such as using a dialog box or bindMenu, or set showInSubwindow to false.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
ctx	BaseContext	Yes	Current context of the input method.
info	PanelInfo	Yes	Information about the input method panel.

Return value

Type	Description
Promise<Panel>	Promise used to return the result. If the operation is successful, the created input method panel is returned.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
12800004	not an input method application.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { inputMethodEngine, InputMethodExtensionAbility } from '@kit.IMEKit';
import { Want } from '@kit.AbilityKit';

let panelInfo: inputMethodEngine.PanelInfo = {
  type: inputMethodEngine.PanelType.SOFT_KEYBOARD,
  flag: inputMethodEngine.PanelFlag.FLG_FIXED
}

class InputMethodExt extends InputMethodExtensionAbility {
    onCreate(want: Want): void {
        console.info(`onCreate, want: ${want.abilityName}`);
        if (this.context) {
            inputMethodEngine.getInputMethodAbility().createPanel(this.context, panelInfo)
                .then((panel: inputMethodEngine.Panel) => {
                console.info('Succeed in creating panel.');
            }).catch((err: BusinessError) => {
                console.error(`Failed to create panel. Code is ${err.code}, message is ${err.message}`);
            })
        }
    }
}

destroyPanel¹⁰⁺

destroyPanel(panel: Panel, callback: AsyncCallback<void>): void

Destroys the specified input method panel. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
panel	Panel	Yes	Input method panel to destroy.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

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

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

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

let panelInfo: inputMethodEngine.PanelInfo = {
  type: inputMethodEngine.PanelType.SOFT_KEYBOARD,
  flag: inputMethodEngine.PanelFlag.FLG_FIXED
}

let inputPanel: inputMethodEngine.Panel | undefined = undefined;
if (this.context) {
  inputMethodEngine.getInputMethodAbility()
    .createPanel(this.context, panelInfo, (err: BusinessError, panel: inputMethodEngine.Panel) => {
      if (err) {
        console.error(`Failed to create panel. Code is ${err.code}, message is ${err.message}`);
        return;
      }
      inputPanel = panel;
      console.info('Succeed in creating panel.');
    })
}

if (inputPanel) {
  inputMethodEngine.getInputMethodAbility().destroyPanel(inputPanel, (err: BusinessError) => {
    if (err !== undefined) {
      console.error(`Failed to destroy panel. Code is ${err.code}, message is ${err.message}`);
      return;
    }
    console.info('Succeed in destroying panel.');
  })
}

destroyPanel¹⁰⁺

destroyPanel(panel: Panel): Promise<void>

Destroys the specified input method panel. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
panel	Panel	Yes	Input method panel to destroy.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

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

let panelInfo: inputMethodEngine.PanelInfo = {
  type: inputMethodEngine.PanelType.SOFT_KEYBOARD,
  flag: inputMethodEngine.PanelFlag.FLG_FIXED
}

let inputPanel: inputMethodEngine.Panel | undefined = undefined;
if (this.context) {
  inputMethodEngine.getInputMethodAbility()
    .createPanel(this.context, panelInfo, (err: BusinessError, panel: inputMethodEngine.Panel) => {
      if (err) {
        console.error(`Failed to create panel. Code is ${err.code}, message is ${err.message}`);
        return;
      }
      inputPanel = panel;
      console.info('Succeed in creating panel.');
    })
}

if (inputPanel) {
  inputMethodEngine.getInputMethodAbility().destroyPanel(inputPanel).then(() => {
    console.info('Succeed in destroying panel.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to destroy panel. Code is ${err.code}, message is ${err.message}`);
  });
}

KeyboardDelegate

In the following API examples, you must first use getKeyboardDelegate to obtain a KeyboardDelegate instance, and then call the APIs using the obtained instance.

on('keyDown'|'keyUp')

on(type: 'keyDown'|'keyUp', callback: (event: KeyEvent) => boolean): void

Enables listening for a physical keyboard event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. - The value 'keyDown' indicates the keydown event. - The value 'keyUp' indicates the keyup event.
callback	(event: KeyEvent) => boolean	Yes	Callback used to return the key information. If the event is consumed by the event subscriber, true is returned. Otherwise, false is returned.

Example

inputMethodEngine.getKeyboardDelegate().on('keyUp', (keyEvent: inputMethodEngine.KeyEvent) => {
  console.info(`inputMethodEngine keyCode.(keyUp): ${keyEvent.keyCode}`);
  console.info(`inputMethodEngine keyAction.(keyUp): ${keyEvent.keyAction}`);
  return true;
});
inputMethodEngine.getKeyboardDelegate().on('keyDown', (keyEvent: inputMethodEngine.KeyEvent) => {
  console.info(`inputMethodEngine keyCode.(keyDown): ${keyEvent.keyCode}`);
  console.info(`inputMethodEngine keyAction.(keyDown): ${keyEvent.keyAction}`);
  return true;
});

off('keyDown'|'keyUp')

off(type: 'keyDown'|'keyUp', callback?: (event: KeyEvent) => boolean): void

Disables listening for a physical keyboard event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. - The value 'keyDown' indicates the keydown event. - The value 'keyUp' indicates the keyup event.
callback	(event: KeyEvent) => boolean	No	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getKeyboardDelegate().off('keyUp', (keyEvent: inputMethodEngine.KeyEvent) => {
  console.info('delete keyUp notification.');
  return true;
});
inputMethodEngine.getKeyboardDelegate().off('keyDown', (keyEvent: inputMethodEngine.KeyEvent) => {
  console.info('delete keyDown notification.');
  return true;
});

on('keyEvent')¹⁰⁺

on(type: 'keyEvent', callback: (event: InputKeyEvent) => boolean): void

Enables listening for a keyboard event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'keyEvent'.
callback	(event: InputKeyEvent) => boolean	Yes	Callback used to return the result. The input parameter is the key event information and the return value is of the Boolean type. - Input parameter: InputKeyEvent. - If the event is consumed by the event subscriber, true is returned. Otherwise, false is returned.

Example

import type { KeyEvent } from '@kit.InputKit';

inputMethodEngine.getKeyboardDelegate().on('keyEvent', (keyEvent: KeyEvent) => {
  console.info(`inputMethodEngine keyEvent.action:${ keyEvent.action}`);
  console.info(`inputMethodEngine keyEvent.key.code: ${keyEvent.key.code}`);
  console.info(`inputMethodEngine keyEvent.ctrlKey: ${keyEvent.ctrlKey}`);
  console.info(`inputMethodEngine keyEvent.unicodeChar: ${keyEvent.unicodeChar}`);
  return true;
});

off('keyEvent')¹⁰⁺

off(type: 'keyEvent', callback?: (event: InputKeyEvent) => boolean): void

Disables listening for a keyboard event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'keyEvent'.
callback	(event: InputKeyEvent) => boolean	No	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

import type { KeyEvent } from '@kit.InputKit';

inputMethodEngine.getKeyboardDelegate().off('keyEvent', (keyEvent: KeyEvent) => {
  console.info('This is a callback function which will be deregistered.');
  return true;
});
inputMethodEngine.getKeyboardDelegate().off('keyEvent');

on('cursorContextChange')

on(type: 'cursorContextChange', callback: (x: number, y:number, height:number) => void): void

Enables listening for the cursor change event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'cursorContextChange'.
callback	(x: number, y: number, height: number) => void	Yes	Callback used to return the cursor information. - x: x coordinate of the top of the cursor. - y: y coordinate of the bottom of the cursor. - height: height of the cursor.

Example

inputMethodEngine.getKeyboardDelegate().on('cursorContextChange', (x: number, y: number, height: number) => {
  console.info('inputMethodEngine cursorContextChange x:' + x);
  console.info('inputMethodEngine cursorContextChange y:' + y);
  console.info('inputMethodEngine cursorContextChange height:' + height);
});

off('cursorContextChange')

off(type: 'cursorContextChange', callback?: (x: number, y: number, height: number) => void): void

Disables listening for cursor context changes. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'cursorContextChange'.
callback	(x: number, y:number, height:number) => void	No	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getKeyboardDelegate().off('cursorContextChange', (x: number, y: number, height: number) => {
  console.info('delete cursorContextChange notification.');
});

on('selectionChange')

on(type: 'selectionChange', callback: (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void): void

Enables listening for the text selection change event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'selectionChange'.
callback	(oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void	Yes	Callback used to return the text selection information. - oldBegin: start of the selected text before the change. - oldEnd: end of the selected text before the change. - newBegin: start of the selected text after the change. - newEnd: end of the selected text after the change.

Example

inputMethodEngine.getKeyboardDelegate()
  .on('selectionChange', (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => {
    console.info('selectionChange oldBegin:' + oldBegin);
    console.info('selectionChange oldEnd:' + oldEnd);
    console.info('selectionChange newBegin:' + newBegin);
    console.info('selectionChange newEnd:' + newEnd);
  });

off('selectionChange')

off(type: 'selectionChange', callback?: (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void): void

Disables listening for the text selection change event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'selectionChange'.
callback	(oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => void	No	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getKeyboardDelegate()
  .off('selectionChange', (oldBegin: number, oldEnd: number, newBegin: number, newEnd: number) => {
    console.info('delete selectionChange notification.');
  });

on('textChange')

on(type: 'textChange', callback: (text: string) => void): void

Enables listening for the text change event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'textChange'.
callback	(text: string) => void	Yes	Callback used to return the text content.

Example

inputMethodEngine.getKeyboardDelegate().on('textChange', (text: string) => {
  console.info('inputMethodEngine textChange. text:' + text);
});

off('textChange')

off(type: 'textChange', callback?: (text: string) => void): void

Disables listening for the text change event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'textChange'.
callback	(text: string) => void	No	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Example

inputMethodEngine.getKeyboardDelegate().off('textChange', (text: string) => {
  console.info('delete textChange notification. text:' + text);
});

on('editorAttributeChanged')¹⁰⁺

on(type: 'editorAttributeChanged', callback: (attr: EditorAttribute) => void): void

Enables listening for the edit box attribute change event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'editorAttributeChanged'.
callback	(attr: EditorAttribute) => void	Yes	Callback used to return the changed edit box attribute.

Example

inputMethodEngine.getKeyboardDelegate()
  .on('editorAttributeChanged', (attr: inputMethodEngine.EditorAttribute) => {
    console.info(`Succeeded in receiving attribute of editor, inputPattern = ${attr.inputPattern}, enterKeyType = ${attr.enterKeyType}`);
  });

off('editorAttributeChanged')¹⁰⁺

off(type: 'editorAttributeChanged', callback?: (attr: EditorAttribute) => void): void

Disables listening for the edit box attribute change event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'editorAttributeChanged'.
callback	(attr: EditorAttribute) => void	No	Callback used for unsubscription. If this parameter is not specified, this API unregisters all callbacks for the specified type by default.

Example

inputMethodEngine.getKeyboardDelegate().off('editorAttributeChanged');

Panel¹⁰⁺

In the following API examples, you must first use createPanel to obtain a Panel instance, and then call the APIs using the obtained instance.

setUiContent¹⁰⁺

setUiContent(path: string, callback: AsyncCallback<void>): void

Loads content from a page to this input method panel. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
path	string	Yes	Path of the page from which the content will be loaded.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

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

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

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

panel.setUiContent('pages/page2/page2', (err: BusinessError) => {
  if (err) {
    console.error(`Failed to setUiContent. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in setting the content.');
});

setUiContent¹⁰⁺

setUiContent(path: string): Promise<void>

Loads content from a page to this input method panel. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
path	string	Yes	Path of the page from which the content will be loaded.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

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

panel.setUiContent('pages/page2/page2').then(() => {
  console.info('Succeeded in setting the content.');
}).catch((err: BusinessError) => {
  console.error(`Failed to setUiContent. Code is ${err.code}, message is ${err.message}`);
});

setUiContent¹⁰⁺

setUiContent(path: string, storage: LocalStorage, callback: AsyncCallback<void>): void

Loads content from a page linked to LocalStorage to this input method panel. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
path	string	Yes	Path of the page linked to LocalStorage.
storage	LocalStorage	Yes	Storage unit that provides storage for mutable and immutable state variables in the application.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

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

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

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

let storage: LocalStorage = new LocalStorage();
storage.setOrCreate('storageSimpleProp', 121);
panel.setUiContent('pages/page2/page2', storage, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to setUiContent. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in setting the content.');
});

setUiContent¹⁰⁺

setUiContent(path: string, storage: LocalStorage): Promise<void>

Loads content from a page linked to LocalStorage to this panel. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
path	string	Yes	Path of the page from which the content will be loaded.
storage	LocalStorage	Yes	Storage unit that provides storage for mutable and immutable state variables in the application.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

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

let storage: LocalStorage = new LocalStorage();
storage.setOrCreate('storageSimpleProp', 121);
panel.setUiContent('pages/page2/page2', storage).then(() => {
  console.info('Succeeded in setting the content.');
}).catch((err: BusinessError) => {
  console.error(`Failed to setUiContent. Code is ${err.code}, message is ${err.message}`);
});

resize¹⁰⁺

resize(width: number, height: number, callback: AsyncCallback<void>): void

Resizes this input method panel. This API uses an asynchronous callback to return the result.

NOTE

The panel width cannot exceed the screen width, and the panel height cannot be 0.7 times higher than the screen height.

When the PanelFlag of a smartphone is FLG_FLOATING and the panel width is between 0 and 288 vp, the function buttons at the bottom of the panel will dynamically adjust their size according to the panel width. To ensure the optimal user experience, it is recommended that the panel width be no less than 90 vp.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
width	number	Yes	Target width of the panel, in px. The value is an integer greater than or equal to 0, and cannot be greater than the screen width.
height	number	Yes	Target height of the panel, in px. The value is an integer greater than or equal to 0, and cannot be greater than 0.7 times the screen height.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

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

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

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

panel.resize(500, 1000, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to resize panel. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in changing the panel size.');
});

resize¹⁰⁺

resize(width: number, height: number): Promise<void>

Resizes this input method panel. This API uses a promise to return the result.

NOTE

The panel width cannot exceed the screen width, and the panel height cannot be 0.7 times higher than the screen height.

When the PanelFlag of a smartphone is FLG_FLOATING and the panel width is between 0 and 288 vp, the function buttons at the bottom of the panel will dynamically adjust their size according to the panel width. To ensure the optimal user experience, it is recommended that the panel width be no less than 90 vp.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
width	number	Yes	Target width of the panel, in px. The value is an integer greater than or equal to 0, and cannot be greater than the screen width.
height	number	Yes	Target height of the panel, in px. The value is an integer greater than or equal to 0, and cannot be greater than 0.7 times the screen height.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

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

panel.resize(500, 1000).then(() => {
  console.info('Succeeded in changing the panel size.');
}).catch((err: BusinessError) => {
  console.error(`Failed to resize panel. Code is ${err.code}, message is ${err.message}`);
});

moveTo¹⁰⁺

moveTo(x: number, y: number, callback: AsyncCallback<void>): void

Moves this input method panel to the specified position. This API uses an asynchronous callback to return the result. This API does not work on panels in the FLG_FIXED state.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
x	number	Yes	Distance to move along the horizontal axis, in px. A positive value indicates moving rightwards. The value must be an integer.
y	number	Yes	Distance to move along the vertical axis, in px. A positive value indicates moving downwards. The value must be an integer.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

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

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

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

panel.moveTo(300, 300, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to move panel. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in moving the panel.');
});

moveTo¹⁰⁺

moveTo(x: number, y: number): Promise<void>

Moves this input method panel to the specified position. This API uses a promise to return the result. This API does not work on panels in the FLG_FIXED state.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
x	number	Yes	Distance to move along the horizontal axis, in px. A positive value indicates moving rightwards. The value must be an integer.
y	number	Yes	Distance to move along the vertical axis, in px. A positive value indicates moving downwards. The value must be an integer.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

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

panel.moveTo(300, 300).then(() => {
  console.info('Succeeded in moving the panel.');
}).catch((err: BusinessError) => {
  console.error(`Failed to move panel. Code is ${err.code}, message is ${err.message}`);
});

startMoving¹⁵⁺

startMoving(): void

Sends a command to start moving the window. The window can be moved only when the mouse is clicked.

System capability: SystemCapability.MiscServices.InputMethodFramework

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
801	capability not supported.
12800002	input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800013	window manager service error.
12800017	invalid panel type or panel flag.

Example

panel.startMoving();

getDisplayId¹⁵⁺

getDisplayId(): Promise<number>

Obtains the window ID. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
Promise<number>	Promise used to return the result. It returns displayId of the window.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
12800002	input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800013	window manager service error.

Example

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

panel.getDisplayId().then((result: number) => {
  console.info('get displayId:' + result);
}).catch((err: BusinessError) => {
  console.error(`Failed to get displayId. Code is ${err.code}, message is ${err.message}`);
});

show¹⁰⁺

show(callback: AsyncCallback<void>): void

Shows this input method panel. This API uses an asynchronous callback to return the result. It can be called when the input method is bound to the edit box.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Example

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

panel.show((err: BusinessError) => {
  if (err) {
    console.error(`Failed to show panel. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in showing the panel.');
});

show¹⁰⁺

show(): Promise<void>

Shows this input method panel. This API uses a promise to return the result. It can be called when the input method is bound to the edit box.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

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

panel.show().then(() => {
  console.info('Succeeded in showing the panel.');
}).catch((err: BusinessError) => {
  console.error(`Failed to show panel. Code is ${err.code}, message is ${err.message}`);
});

hide¹⁰⁺

hide(callback: AsyncCallback<void>): void

Hides this panel. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Example

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

panel.hide((err: BusinessError) => {
  if (err) {
    console.error(`Failed to hide panel. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in hiding the panel.');
});

hide¹⁰⁺

hide(): Promise<void>

Hides this panel. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

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

panel.hide().then(() => {
  console.info('Succeeded in hiding the panel.');
}).catch((err: BusinessError) => {
  console.error(`Failed to hide panel. Code is ${err.code}, message is ${err.message}`);
});

adjustPanelRect¹²⁺

adjustPanelRect(flag: PanelFlag, rect: PanelRect): void

Adjusts the panel rectangle. After the API is called, the adjust request is submitted to the input method framework, but the execution is not complete.

NOTE

This API applies only to the panels of the SOFT_KEYBOARD type in the FLG_FIXED or FLG_FLOATING state.

This API returns the result synchronously. The return only indicates that the system receives the setting request, not that the setting is complete.

When the PanelFlag of a smartphone is FLG_FLOATING and the panel width is between 0 and 288 vp, the function buttons at the bottom of the panel will dynamically adjust their size according to the panel width. To ensure the optimal user experience, it is recommended that the panel width be no less than 90 vp.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
flag	PanelFlag	Yes	Type of the state of the target panel. It can be FLG_FIXED or FLG_FLOATING.
rect	PanelRect	Yes	Landscape rectangle and portrait rectangle of the target panel. For the panel of the fixed state, the height cannot exceed 70% of the screen height, and the width cannot exceed the screen width. For the panel of the floating state, the height cannot exceed the screen height, and the width cannot exceed the screen width.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800013	window manager service error.

Example

import { window } from '@kit.ArkUI';

let landscapeRect: window.Rect = {
  left: 100,
  top: 100,
  width: 400,
  height: 400
};

let portraitRect: window.Rect = {
  left: 200,
  top: 200,
  width: 300,
  height: 300
};

// Target panel status type.
let panelFlag: inputMethodEngine.PanelFlag = inputMethodEngine.PanelFlag.FLG_FIXED;
// X-coordinate, Y-coordinate, width, and height of the target panel in both landscape and portrait orientations.
let panelRect: inputMethodEngine.PanelRect = {
  landscapeRect: landscapeRect,
  portraitRect: portraitRect
};
panel.adjustPanelRect(panelFlag, panelRect);

adjustPanelRect¹⁵⁺

adjustPanelRect(flag: PanelFlag, rect: EnhancedPanelRect): void

Adjusts the panel rectangle, and customizes the avoid area and touch area.

NOTE

This API applies only to the panels of the SOFT_KEYBOARD type in the FLG_FIXED or FLG_FLOATING state. This API is compatible with adjustPanelRect. If the input parameter rect contains only the landscapeRect and portraitRect attributes, adjustPanelRect is called by default.

This API returns the result synchronously. The return only indicates that the system receives the setting request, not that the setting is complete.

When the PanelFlag of a smartphone is FLG_FLOATING and the panel width is between 0 and 288 vp, the function buttons at the bottom of the panel will dynamically adjust their size according to the panel width. To ensure the optimal user experience, it is recommended that the panel width be no less than 90 vp.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
flag	PanelFlag	Yes	Type of the state of the target panel. It can be FLG_FIXED or FLG_FLOATING.
rect	EnhancedPanelRect	Yes	The target panel rectangle, avoid area, and touch area.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800013	window manager service error.
12800017	invalid panel type or panel flag.

Example

import { window } from '@kit.ArkUI';

let landscapeRect1: window.Rect = {
  left: 300,
  top: 650,
  width: 2000,
  height: 500
};
let landscapeInputRegion: Array<window.Rect> = [landscapeRect1];

let portraitRect1: window.Rect = {
  left: 0,
  top: 1800,
  width: 1200,
  height: 800
}
let portraitInputRegion: Array<window.Rect> = [portraitRect1];
// Target panel status type.
let panelFlag: inputMethodEngine.PanelFlag = inputMethodEngine.PanelFlag.FLG_FIXED;
// Location, size, avoid area, and hot zone of the target panel in both landscape and portrait orientations.
let panelRect: inputMethodEngine.EnhancedPanelRect = {
  landscapeAvoidY: 650,
  landscapeInputRegion: landscapeInputRegion,
  portraitAvoidY: 1800,
  portraitInputRegion: portraitInputRegion,
  fullScreenMode: true
};
panel.adjustPanelRect(panelFlag, panelRect);

updateRegion¹⁵⁺

updateRegion(inputRegion: Array<window.Rect>): void

Updates the hot zone on the input method panel in the current state.

NOTE

This API applies only to the panels of the SOFT_KEYBOARD type in the FLG_FIXED or FLG_FLOATING state.

This API returns the result synchronously. The return only indicates that the system has received the request for updating the hot zone, not that the hot zone has been updated.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
inputRegion	Array<window.Rect>	Yes	Region for receiving input events. - The array size is limited to [1, 4]. - The input hot zone is relative to the left vertex of the input method panel window.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800013	window manager service error.
12800017	invalid panel type or panel flag.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

let inputRegion: Array<window.Rect> = [{
  left: 300,
  top: 650,
  width: 2000,
  height: 500
}];
panel.updateRegion(inputRegion);

on('show')¹⁰⁺

on(type: 'show', callback: () => void): void

Enables listening for the show event of this panel. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'show'.
callback	() => void	Yes	Callback used to return the result.

Example

panel.on('show', () => {
  console.info('Panel is showing.');
});

on('hide')¹⁰⁺

on(type: 'hide', callback: () => void): void

Enables listening for the hide event of this panel. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'hide'.
callback	() => void	Yes	Callback used to return the result.

Example

panel.on('hide', () => {
  console.info('Panel is hiding.');
});

on('sizeChange')¹²⁺

on(type: 'sizeChange', callback: SizeChangeCallback): void

Enables listening for the panel size change. This API uses an asynchronous callback to return the result.

NOTE

This API applies only to the panels of the SOFT_KEYBOARD type in the FLG_FIXED or FLG_FLOATING state. When you call adjustPanelRect to adjust the panel size, the system calculates the final value based on certain rules (for example, whether the panel size exceeds the screen). This callback can be used to obtain the actual panel size to refresh the panel layout.

• This API is supported from API version 12 to 14. The callback function of this API contains only mandatory parameters of the window.Size type.
• Since API version 15, after the adjustPanelRect API is called, an optional parameter of the KeyboardArea type is added to the callback function of this API.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'sizeChange'.
callback	SizeChangeCallback	Yes	Callback used to return the size of the soft keyboard panel, including the width and height.

Example

import { window } from '@kit.ArkUI';

panel.on('sizeChange', (windowSize: window.Size) => {
  console.info(`panel size changed, width: ${windowSize.width}, height: ${windowSize.height}`);
});

panel.on('sizeChange', (windowSize: window.Size, keyboardArea: inputMethodEngine.KeyboardArea) => {
  console.info(`panel size changed, windowSize: ${windowSize.width}, ${windowSize.height}, ` +
    `keyboardArea: ${keyboardArea.top}, ${keyboardArea.bottom}, ${keyboardArea.left}, ${keyboardArea.right}`);
});

off('show')¹⁰⁺

off(type: 'show', callback?: () => void): void

Disables listening for the show event of this panel. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'show'.
callback	() => void	No	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Error codes

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

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

panel.off('show');

off('hide')¹⁰⁺

off(type: 'hide', callback?: () => void): void

Disables listening for the hide event of this panel. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'hide'.
callback	() => void	No	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type.

Error codes

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

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

panel.off('hide');

off('sizeChange')¹²⁺

off(type: 'sizeChange', callback?: SizeChangeCallback): void

Disables listening for the panel size change. This API uses an asynchronous callback to return the result.

NOTE

This API applies only to the panels of the SOFT_KEYBOARD type in the FLG_FIXED or FLG_FLOATING state. When you call adjustPanelRect to adjust the panel size, the system calculates the final value based on certain rules (for example, whether the panel size exceeds the screen). This callback can be used to obtain the actual panel size to refresh the panel layout.

• This API is supported from API version 12 to 14. The callback function of this API contains only mandatory parameters of the window.Size type.
• Since API version 15, after the adjustPanelRect API is called, an optional parameter of the KeyboardArea type is added to the callback function of this API.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'sizeChange'.
callback	SizeChangeCallback	No	Callback used to return the size of the soft keyboard panel, including the width and height.

Example

import { window } from '@kit.ArkUI';

panel.off('sizeChange', (windowSize: window.Size) => {
  console.info(`panel size changed, width: ${windowSize.width}, height: ${windowSize.height}`);
});

changeFlag¹⁰⁺

changeFlag(flag: PanelFlag): void

Changes the state type (PanelFlag) of this input method panel. This API only works for SOFT_KEYBOARD panels.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
flag	PanelFlag	Yes	Type of the state of the target panel.

Error codes

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

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

let panelFlag: inputMethodEngine.PanelFlag = inputMethodEngine.PanelFlag.FLG_FIXED;
panel.changeFlag(panelFlag);

setPrivacyMode¹¹⁺

setPrivacyMode(isPrivacyMode: boolean): void

Sets the input method panel to privacy mode. In privacy mode, screenshot and screen recording are blocked.

Required permissions: ohos.permission.PRIVACY_WINDOW

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
isPrivacyMode	boolean	Yes	Whether to set the input method panel to privacy mode. - true: privacy mode. - false: non-privacy mode.

Error codes

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

ID	Error Message
201	permissions check fails.
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

let isPrivacyMode: boolean = true;
panel.setPrivacyMode(isPrivacyMode);

setImmersiveMode¹⁵⁺

setImmersiveMode(mode: ImmersiveMode): void

Sets the immersive mode of the input method application. You can only set the immersion mode to NONE_IMMERSIVE, LIGHT_IMMERSIVE, or DARK_IMMERSIVE. IMMERSIVE cannot be set.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
mode	ImmersiveMode	Yes	Immersive mode.

Error codes

For details about the error codes, see Universal Error Codes and Input Method Framework Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1.Incorrect parameter types; 2.Parameter verification failed.
12800002	input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800013	window manager service error.

Example

panel.setImmersiveMode(inputMethodEngine.ImmersiveMode.LIGHT_IMMERSIVE);

getImmersiveMode¹⁵⁺

getImmersiveMode(): ImmersiveMode

Obtains the immersive mode of the input method application.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
ImmersiveMode	Immersive mode.

Example

let mode: inputMethodEngine.ImmersiveMode = panel.getImmersiveMode();

setImmersiveEffect²⁰⁺

setImmersiveEffect(effect: ImmersiveEffect): void

Sets the immersive effect of the input method application.

• Gradient mode and fluid light mode can be used only when the immersive mode is enabled.
• The fluid light mode can be used only when the gradient mode is enabled.
• If the gradient mode is disabled, the gradient height must be 0 px.
• Only system applications can set the fluid light mode.
• The current API can be called only after any of the following APIs is called:
  • adjustPanelRect (available since API version 12)
  • adjustPanelRect (available since API version 15)
  • resize (available since API version 10)

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
effect	ImmersiveEffect	Yes	Immersive effect.

Error codes

For details about the error codes, see Universal Error Codes and Input Method Framework Error Codes.

ID	Error Message
801	capability not supported.
12800002	input method engine error. Possible causes:1.input method panel not created. 2.the input method application does not subscribe to related events.
12800013	window manager service error.
12800020	invalid immersive effect. 1.The gradient mode and the fluid light mode can only be used when the immersive mode is enabled. 2.The fluid light mode can only be used when the gradient mode is enabled. 3.When the gradient mode is not enabled, the gradient height can only be 0.
12800021	this operation is allowed only after adjustPanelRect or resize is called.

Example

let effect: inputMethodEngine.ImmersiveEffect = {
  gradientHeight: 100,
  gradientMode: inputMethodEngine.GradientMode.LINEAR_GRADIENT
}
panel.setImmersiveEffect(effect);

setKeepScreenOn²⁰⁺

setKeepScreenOn(isKeepScreenOn: boolean): Promise<void>

Sets to keep the screen always on. This API uses a promise to return the result.

NOTE

• When the keyboard is displayed, the screen stays on. When the keyboard is hidden, the screen turns off.
• You need to use this API properly. Set the attribute to true in necessary scenarios (for example, voice input) and reset this attribute to false after exiting necessary scenarios. In other scenarios, do not use this API.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
isKeepScreenOn	boolean	Yes	Whether to keep the screen always on. The value true means that the screen is always on; the value false means the opposite.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
12800013	window manager service error.

Example

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

panel.setKeepScreenOn(true).then(() => {
  console.info(`setKeepScreenOn success.`);
}).catch((error: BusinessError) => {
  console.error(`setKeepScreenOn failed, code: ${error.code}, message: ${error.message}`);
})

getSystemPanelCurrentInsets²¹⁺

getSystemPanelCurrentInsets(displayId: number): Promise<SystemPanelInsets>

Obtains the offset area of the soft keyboard relative to the system panel under the current state of the specified screen (for example, folded or unfolded) and the current state of the input method keyboard (for example, floating or fixed). This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
displayId	number	Yes	Display ID of the screen where the input method keyboard is located. It can be obtained by calling getDisplayId.

Return value

Type	Description
Promise<SystemPanelInsets>	Promise used to return the offset area between the input method keyboard and the system panel.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
12800013	window manager service error.
12800017	invalid panel type or panel flag. Possible causes: 1. Current panel's type is not SOFT_KEYBOARD. 2. Panel's flag is not FLG_FIXED or FLG_FLOATING.
12800022	invalid displayId.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { inputMethodEngine } from '@kit.IMEKit';

let inputMethodAbility: inputMethodEngine.InputMethodAbility = inputMethodEngine.getInputMethodAbility();
let panelConfig: inputMethodEngine.PanelInfo = {
  type: inputMethodEngine.PanelType.SOFT_KEYBOARD,
  flag: inputMethodEngine.PanelFlag.FLG_FIXED
}
// The following logic needs to be executed in InputMethodExtensionAbility. this.context is the context of InputMethodExtensionAbility.
inputMethodAbility.createPanel(this.context, panelConfig).then( (panel: inputMethodEngine.Panel) =>{
  panel.getDisplayId().then((displayId: number) => {
    panel.getSystemPanelCurrentInsets(displayId).then((insets: inputMethodEngine.SystemPanelInsets) => {
      console.info(`getSystemPanelCurrentInsets success, insets is { left: ${insets.left}, right: ${insets.right}, bottom: ${insets.bottom} }`);
    }).catch((error: BusinessError) => {
      console.error(`getSystemPanelCurrentInsets failed, code: ${error.code}, message: ${error.message}`);
    })
  });
})

setSystemPanelButtonColor²²⁺

setSystemPanelButtonColor(fillColor: string | undefined, backgroundColor: string | undefined): Promise<void>

Sets the color of the function buttons and their background color on the current panel. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
fillColor	string|undefined	Yes	Color of the function buttons. The value can be [#01000000, #FFFFFFFF] or [#000000, #FFFFFF]. The value of the fully transparent alpha channel (#00xxxxxx) is not supported.
backgroundColor	string|undefined	Yes	Background color of the function buttons. The value can be [#01000000, #FFFFFFFF] or [#000000, #FFFFFF]. The value of the fully transparent alpha channel (#00xxxxxx) is not supported.

Return value

Type	Description
Promise<void>	Promise that returns no result.

Example

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

try {
  let fillColor = "#FFFF00";
  let backgroundColor = "#0000FF";
  this.panel.setSystemPanelButtonColor(fillColor, backgroundColor).then(() => {
    console.info(`setSystemPanelButtonColor success.`);
  }).catch((error: BusinessError) => {
    console.error(`setSystemPanelButtonColor failed, code: ${error.code}, message: ${error.message}`);
  })
} catch (err) {
  let error = err as BusinessError;
  console.error(`setSystemPanelButtonColor failed, code: ${error.code}, message: ${error.message}`);
}

KeyboardController

You must first use on('inputStart') to obtain a KeyboardController instance, and then use this instance to call the following APIs.

hide⁹⁺

hide(callback: AsyncCallback<void>): void

Hides the keyboard. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

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

keyboardController.hide((err: BusinessError) => {
  if (err) {
    console.error(`Failed to hide. Code:${err.code}, message:${err.message}`);
    return;
  }
  console.info('Succeeded in hiding keyboard.');
});

hide⁹⁺

hide(): Promise<void>

Hides the keyboard. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

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

keyboardController.hide().then(() => {
  console.info('Succeeded in hiding keyboard.');
}).catch((err: BusinessError) => {
  console.error(`Failed to hide. Code:${err.code}, message:${err.message}`);
});

hideKeyboard^(deprecated)

hideKeyboard(callback: AsyncCallback<void>): void

Hides the keyboard. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use hide instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Example

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

keyboardController.hideKeyboard((err: BusinessError) => {
  if (err) {
    console.error(`Failed to hideKeyboard. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in hiding keyboard.');
});

hideKeyboard^(deprecated)

hideKeyboard(): Promise<void>

Hides the keyboard. This API uses a promise to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use hide instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

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

keyboardController.hideKeyboard().then(() => {
  console.info('Succeeded in hiding keyboard.');
}).catch((err: BusinessError) => {
  console.info(`Failed to hideKeyboard. Code is ${err.code}, message is ${err.message}`);
});

exitCurrentInputType¹¹⁺

exitCurrentInputType(callback: AsyncCallback<void>): void

Exits this input type. This API can be called only by the preconfigured default input method. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
12800008	input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.
12800010	not the preconfigured default input method.

Example

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

keyboardController.exitCurrentInputType((err: BusinessError) => {
  if (err) {
    console.error(`Failed to exit current input type. Code:${err.code}, message:${err.message}`);
    return;
  }
  console.info('Succeeded in exiting current input type.');
});

exitCurrentInputType¹¹⁺

exitCurrentInputType(): Promise<void>

Exits this input type. This API can be called only by the preconfigured default input method. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
12800008	input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.
12800010	not the preconfigured default input method.

Example

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

keyboardController.exitCurrentInputType().then(() => {
  console.info('Succeeded in exiting current input type.');
}).catch((err: BusinessError) => {
  console.error(`Failed to exit current input type. Code:${err.code}, message:${err.message}`);
});

SecurityMode¹¹⁺

Describes the security mode.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Value	Description
BASIC	0	Basic access mode, where network access is restricted.
FULL	1	Full access mode, where network access is not restricted.

ExtendAction¹⁰⁺

Describes the type of the extended edit action on the text box.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Value	Description
SELECT_ALL	0	Select all.
CUT	3	Cut.
COPY	4	Copy.
PASTE	5	Paste.

Direction¹⁰⁺

Enumerates the directions of cursor movement of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Value	Description
CURSOR_UP	1	Upward.
CURSOR_DOWN	2	Downward.
CURSOR_LEFT	3	Leftward.
CURSOR_RIGHT	4	Rightward.

Range¹⁰⁺

Describes the range of the selected text.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Type	Read-Only	Optional	Description
start	number	No	No	Index of the first selected character in the text box.
end	number	No	No	Index of the last selected character in the text box.

Movement¹⁰⁺

Describes the direction in which the cursor moves when the text is selected.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Type	Read-Only	Optional	Description
direction	Direction	No	No	Direction in which the cursor moves when the text is selected.

MessageHandler¹⁵⁺

Represents a custom communication object.

NOTE

You can register this object to receive custom communication data sent by the edit box application attached to the input method application. When the custom communication data is received, the onMessage callback in this object is triggered.

This object is globally unique. After multiple registrations, only the last registered object is valid and retained, and the onTerminated callback of the penultimate registered object is triggered.

If this object is unregistered, its onTerminated callback will be triggered.

onMessage¹⁵⁺

onMessage(msgId: string, msgParam?: ArrayBuffer): void

Receives the custom data callback sent by the edit box application attached to the input method application.

NOTE

This callback is triggered when the registered MessageHandler receives custom communication data sent by the edit box application attached to the input method application.

The msgId parameter is mandatory, and the msgParam parameter is optional. If only the custom msgId data is received, confirm it with the data sender.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
msgId	string	Yes	Identifier of the received custom communication data.
msgParam	ArrayBuffer	No	Message body of the received custom communication data.

Example

inputMethodEngine.getInputMethodAbility()
  .on('inputStart',
    (kbController: inputMethodEngine.KeyboardController, client: inputMethodEngine.InputClient) => {
      let keyboardController: inputMethodEngine.KeyboardController = kbController;
      let inputClient: inputMethodEngine.InputClient = client;
      let messageHandler: inputMethodEngine.MessageHandler = {
        onTerminated(): void {
          console.info('OnTerminated.');
        },
        onMessage(msgId: string, msgParam?: ArrayBuffer): void {
          console.info(`recv message, msgId is ${msgId}, msgParam is ${JSON.stringify(msgParam)}`);
        }
      }
      inputClient.recvMessage(messageHandler);
    });

onTerminated¹⁵⁺

onTerminated(): void

Listens for MessageHandler termination.

NOTE

When an application registers a new MessageHandler object, the onTerminated callback of the penultimate registered MessageHandler object is triggered.

When an application unregisters a new MessageHandler object, the onTerminated callback of the registered MessageHandler object is triggered.

System capability: SystemCapability.MiscServices.InputMethodFramework

Example

inputMethodEngine.getInputMethodAbility()
  .on('inputStart',
    (kbController: inputMethodEngine.KeyboardController, client: inputMethodEngine.InputClient) => {
      let keyboardController: inputMethodEngine.KeyboardController = kbController;
      let inputClient: inputMethodEngine.InputClient = client;
      let messageHandler: inputMethodEngine.MessageHandler = {
        onTerminated(): void {
          console.info('OnTerminated.');
        },
        onMessage(msgId: string, msgParam?: ArrayBuffer): void {
          console.info(`recv message, msgId is ${msgId}, msgParam is ${JSON.stringify(msgParam)}`);
        }
      }
      inputClient.recvMessage(messageHandler);
    });

InputClient⁹⁺

You must first use on('inputStart') to obtain a InputClient instance, and then use this instance to call the following APIs.

sendKeyFunction⁹⁺

sendKeyFunction(action:number, callback: AsyncCallback<boolean>): void

Sends the function key. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
action	number	Yes	Action of the function key. - 0: invalid key. - 1: confirm key (Enter key).
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is true. Otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

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

let action: number = 1;

inputClient.sendKeyFunction(action, (err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to sendKeyFunction. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in sending key function.');
  } else {
    console.error('Failed to sendKeyFunction.');
  }
});

sendKeyFunction⁹⁺

sendKeyFunction(action: number): Promise<boolean>

Sends the function key. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
action	number	Yes	Action of the function key. 0: invalid key. 1: confirm key (Enter key).

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true means that the operation is successful, and false means the opposite.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

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

let action: number = 1;
inputClient.sendKeyFunction(action).then((result: boolean) => {
  if (result) {
    console.info('Succeeded in sending key function.');
  } else {
    console.error('Failed to sendKeyFunction.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to sendKeyFunction. Code is ${err.code}, message is ${err.message}`);
});

getForward⁹⁺

getForward(length:number, callback: AsyncCallback<string>): void

Obtains the specific-length text before the cursor. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.
callback	AsyncCallback<string>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is the obtained text. Otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006	input method controller error. Possible cause: create InputMethodController object failed.

Example

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

let length: number = 1;
inputClient.getForward(length, (err: BusinessError, text: string) => {
  if (err) {
    console.error(`Failed to getForward. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in getting forward, text: ' + text);
});

getForward⁹⁺

getForward(length:number): Promise<string>

Obtains the specific-length text before the cursor. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.

Return value

Type	Description
Promise<string>	Promise used to return the specific-length text before the cursor.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006	input method controller error. Possible cause: create InputMethodController object failed.

Example

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

let length: number = 1;
inputClient.getForward(length).then((text: string) => {
  console.info('Succeeded in getting forward, text: ' + text);
}).catch((err: BusinessError) => {
  console.error(`Failed to getForward. Code is ${err.code}, message is ${err.message}`);
});

getForwardSync¹⁰⁺

getForwardSync(length:number): string

Obtains the specific-length text before the cursor.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.

Return value

Type	Description
string	Specific-length text before the cursor.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006	input method controller error. Possible cause: create InputMethodController object failed.

Example

let length: number = 1;
let text: string = inputClient.getForwardSync(length);
console.info(`Succeeded in getting forward, text: ${text}`);

getBackward⁹⁺

getBackward(length:number, callback: AsyncCallback<string>): void

Obtains the specific-length text after the cursor. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.
callback	AsyncCallback<string>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is the obtained text. Otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006	input method controller error. Possible cause: create InputMethodController object failed.

Example

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

let length: number = 1;
inputClient.getBackward(length, (err: BusinessError, text: string) => {
  if (err) {
    console.error(`Failed to getBackward. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in getting backward, text: ' + text);
});

getBackward⁹⁺

getBackward(length:number): Promise<string>

Obtains the specific-length text after the cursor. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.

Return value

Type	Description
Promise<string>	Promise used to return the specific-length text after the cursor.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006	input method controller error. Possible cause: create InputMethodController object failed.

Example

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

let length: number = 1;
inputClient.getBackward(length).then((text: string) => {
  console.info('Succeeded in getting backward, text: ' + text);
}).catch((err: BusinessError) => {
  console.error(`Failed to getBackward. Code is ${err.code}, message is ${err.message}`);
});

getBackwardSync¹⁰⁺

getBackwardSync(length:number): string

Obtains the specific-length text after the cursor.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.

Return value

Type	Description
string	Specific-length text after the cursor.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006	input method controller error. Possible cause: create InputMethodController object failed.

Example

let length: number = 1;
let text: string = inputClient.getBackwardSync(length);
console.info(`Succeeded in getting backward, text: ${text}`);

deleteForward⁹⁺

deleteForward(length:number, callback: AsyncCallback<boolean>): void

Deletes the fixed-length text before the cursor. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is true. Otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800002	input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

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

let length: number = 1;
inputClient.deleteForward(length, (err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to deleteForward. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in deleting forward.');
  } else {
    console.error(`Failed to deleteForward.`);
  }
});

deleteForward⁹⁺

deleteForward(length:number): Promise<boolean>

Deletes the fixed-length text before the cursor. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true means that the deletion is successful, and false means the opposite.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800002	input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

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

let length: number = 1;
inputClient.deleteForward(length).then((result: boolean) => {
  if (result) {
    console.info('Succeeded in deleting forward.');
  } else {
    console.error('Failed to delete Forward.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to deleteForward. Code is ${err.code}, message is ${err.message}`);
});

deleteForwardSync¹⁰⁺

deleteForwardSync(length:number): void

Deletes the fixed-length text before the cursor.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800002	input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

let length: number = 1;
inputClient.deleteForwardSync(length);

deleteBackward⁹⁺

deleteBackward(length:number, callback: AsyncCallback<boolean>): void

Deletes the fixed-length text after the cursor. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is true. Otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800002	input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

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

let length: number = 1;
inputClient.deleteBackward(length, (err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to deleteBackward. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in deleting backward.');
  } else {
    console.error(`Failed to deleteBackward.`);
  }
});

deleteBackward⁹⁺

deleteBackward(length:number): Promise<boolean>

Deletes the fixed-length text after the cursor. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true means that the deletion is successful, and false means the opposite.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800002	input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

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

let length: number = 1;
inputClient.deleteBackward(length).then((result: boolean) => {
  if (result) {
    console.info('Succeeded in deleting backward.');
  } else {
    console.error('Failed to deleteBackward.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to deleteBackward. Code is ${err.code}, message is ${err.message}`);
});

deleteBackwardSync¹⁰⁺

deleteBackwardSync(length:number): void

Deletes the fixed-length text after the cursor.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800002	input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

let length: number = 1;
inputClient.deleteBackwardSync(length);

insertText⁹⁺

insertText(text:string, callback: AsyncCallback<boolean>): void

Inserts text. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
text	string	Yes	Text to insert.
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is true. Otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800002	input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

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


inputClient.insertText('test', (err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to insertText. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in inserting text.');
  } else {
    console.error('Failed to insertText.');
  }
});

insertText⁹⁺

insertText(text:string): Promise<boolean>

Inserts text. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
text	string	Yes	Text to insert.

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true means that the insertion is successful, and false means the opposite.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800002	input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

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

inputClient.insertText('test').then((result: boolean) => {
  if (result) {
    console.info('Succeeded in inserting text.');
  } else {
    console.error('Failed to insertText.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to insertText. Code is ${err.code}, message is ${err.message}`);
});

insertTextSync¹⁰⁺

insertTextSync(text: string): void

Inserts text.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
text	string	Yes	Text to insert.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800002	input method engine error. Possible causes: 1.input method panel not created. 2.the input method application does not subscribe to related events.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

inputClient.insertTextSync('test');

getEditorAttribute⁹⁺

getEditorAttribute(callback: AsyncCallback<EditorAttribute>): void

Obtains the attribute of the edit box. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<EditorAttribute>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is the attribute of the edit box. Otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

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

inputClient.getEditorAttribute((err: BusinessError, editorAttribute: inputMethodEngine.EditorAttribute) => {
  if (err) {
    console.error(`Failed to getEditorAttribute. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info(`editorAttribute.inputPattern:  ${editorAttribute.inputPattern}`);
  console.info(`editorAttribute.enterKeyType:  ${editorAttribute.enterKeyType}`);
});

getEditorAttribute⁹⁺

getEditorAttribute(): Promise<EditorAttribute>

Obtains the attribute of the edit box. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
Promise<EditorAttribute>	Promise used to return the attribute of the edit box.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

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

inputClient.getEditorAttribute().then((editorAttribute: inputMethodEngine.EditorAttribute) => {
  console.info(`editorAttribute.inputPattern:  ${editorAttribute.inputPattern}`);
  console.info(`editorAttribute.enterKeyType:  ${editorAttribute.enterKeyType}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to getEditorAttribute. Code is ${err.code}, message is ${err.message}`);
});

getEditorAttributeSync¹⁰⁺

getEditorAttributeSync(): EditorAttribute

Obtains the attribute of the edit box.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
EditorAttribute	Attribute information.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

let editorAttribute: inputMethodEngine.EditorAttribute = inputClient.getEditorAttributeSync();
console.info(`editorAttribute.inputPattern:  ${editorAttribute.inputPattern}`);
console.info(`editorAttribute.enterKeyType:  ${editorAttribute.enterKeyType}`);

moveCursor⁹⁺

moveCursor(direction: number, callback: AsyncCallback<void>): void

Moves the cursor. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
direction	number	Yes	Direction in which the cursor moves. - 1: upward. - 2: downward. - 3: leftward. - 4: rightward. which cannot be less than 0.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

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

inputClient.moveCursor(inputMethodEngine.Direction.CURSOR_UP, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to moveCursor. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in moving cursor.');
});

moveCursor⁹⁺

moveCursor(direction: number): Promise<void>

Moves the cursor. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
direction	number	Yes	Direction in which the cursor moves. - 1: upward. - 2: downward. - 3: leftward. - 4: rightward. which cannot be less than 0.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

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

inputClient.moveCursor(inputMethodEngine.Direction.CURSOR_UP).then(() => {
  console.info('Succeeded in moving cursor.');
}).catch((err: BusinessError) => {
  console.error(`Failed to moveCursor. Code is ${err.code}, message is ${err.message}`);
});

moveCursorSync¹⁰⁺

moveCursorSync(direction: number): void

Moves the cursor.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
direction	number	Yes	Direction in which the cursor moves. - 1: upward. - 2: downward. - 3: leftward. - 4: rightward. which cannot be less than 0.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

inputClient.moveCursorSync(inputMethodEngine.Direction.CURSOR_UP);

selectByRange¹⁰⁺

selectByRange(range: Range, callback: AsyncCallback<void>): void

Selects text based on the specified range. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
range	Range	Yes	Range of the selected text.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the selection event is sent, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

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

let range: inputMethodEngine.Range = { start: 0, end: 1 };
inputClient.selectByRange(range, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to selectByRange. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in selecting by range.');
});

selectByRange¹⁰⁺

selectByRange(range: Range): Promise<void>

Selects text based on the specified range. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
range	Range	Yes	Range of the selected text.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

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

let range: inputMethodEngine.Range = { start: 0, end: 1 };
inputClient.selectByRange(range).then(() => {
  console.info('Succeeded in selecting by range.');
}).catch((err: BusinessError) => {
  console.error(`Failed to selectByRange. Code is ${err.code}, message is ${err.message}`);
});

selectByRangeSync¹⁰⁺

selectByRangeSync(range: Range): void

Selects text based on the specified range.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
range	Range	Yes	Range of the selected text.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

let range: inputMethodEngine.Range = { start: 0, end: 1 };
inputClient.selectByRangeSync(range);

selectByMovement¹⁰⁺

selectByMovement(movement: Movement, callback: AsyncCallback<void>): void

Selects text based on the cursor movement direction. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
movement	Movement	Yes	Direction in which the cursor moves when the text is selected.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the selection event is sent, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

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

let movement: inputMethodEngine.Movement = { direction: 1 };
inputClient.selectByMovement(movement, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to selectByMovement. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in selecting by movement.');
});

selectByMovement¹⁰⁺

selectByMovement(movement: Movement): Promise<void>

Selects text based on the cursor movement direction. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
movement	Movement	Yes	Direction in which the cursor moves when the text is selected.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

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

let movement: inputMethodEngine.Movement = { direction: 1 };
inputClient.selectByMovement(movement).then(() => {
  console.info('Succeeded in selecting by movement.');
}).catch((err: BusinessError) => {
  console.error(`Failed to selectByMovement. Code is ${err.code}, message is ${err.message}`);
});

selectByMovementSync¹⁰⁺

selectByMovementSync(movement: Movement): void

Selects text based on the cursor movement direction.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
movement	Movement	Yes	Direction in which the cursor moves when the text is selected.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.

Example

let movement: inputMethodEngine.Movement = { direction: 1 };
inputClient.selectByMovementSync(movement);

getTextIndexAtCursor¹⁰⁺

getTextIndexAtCursor(callback: AsyncCallback<number>): void

Obtains the index of the text where the cursor is located. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<number>	Yes	Callback used to return the result. If the text index is obtained, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006	input method controller error. Possible cause: create InputMethodController object failed.

Example

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

inputClient.getTextIndexAtCursor((err: BusinessError, index: number) => {
  if (err) {
    console.error(`Failed to getTextIndexAtCursor. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in getTextIndexAtCursor: ' + index);
});

getTextIndexAtCursor¹⁰⁺

getTextIndexAtCursor(): Promise<number>

Obtains the index of the text where the cursor is located. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
Promise<number>	Promise used to return the result.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006	input method controller error. Possible cause: create InputMethodController object failed.

Example

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

inputClient.getTextIndexAtCursor().then((index: number) => {
  console.info('Succeeded in getTextIndexAtCursor: ' + index);
}).catch((err: BusinessError) => {
  console.error(`Failed to getTextIndexAtCursor. Code is ${err.code}, message is ${err.message}`);
});

getTextIndexAtCursorSync¹⁰⁺

getTextIndexAtCursorSync(): number

Obtains the index of the text where the cursor is located.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
number	Index of the text where the cursor is located.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006	input method controller error. Possible cause: create InputMethodController object failed.

Example

let index: number = inputClient.getTextIndexAtCursorSync();
console.info(`Succeeded in getTextIndexAtCursorSync, index: ${index}`);

sendExtendAction¹⁰⁺

sendExtendAction(action: ExtendAction, callback: AsyncCallback<void>): void

Sends an extended edit action. This API uses an asynchronous callback to return the result.

NOTE

The input method applications call this API to send extended edit actions to the edit box. The edit box listens for the corresponding event using on('handleExtendAction') for further processing.

When the edit box responds to the PASTE command of ExtendAction, the edit box application needs to apply for the ohos.permission.READ_PASTEBOARD permission.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
action	ExtendAction	Yes	Extended edit action to send.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006	input method controller error. Possible cause: create InputMethodController object failed.

Example

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

inputClient.sendExtendAction(inputMethodEngine.ExtendAction.COPY, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to sendExtendAction. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in sending extend action.');
});

sendExtendAction¹⁰⁺

sendExtendAction(action: ExtendAction): Promise<void>

Sends an extended edit action. This API uses a promise to return the result.

NOTE

The input method applications call this API to send extended edit actions to the edit box. The edit box listens for the corresponding event using on('handleExtendAction') for further processing.

When the edit box responds to the PASTE command of ExtendAction, the edit box application needs to apply for the ohos.permission.READ_PASTEBOARD permission.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
action	ExtendAction	Yes	Extended edit action to send.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800006	input method controller error. Possible cause: create InputMethodController object failed.

Example

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

inputClient.sendExtendAction(inputMethodEngine.ExtendAction.COPY).then(() => {
  console.info('Succeeded in sending extend action.');
}).catch((err: BusinessError) => {
  console.error(`Failed to sendExtendAction. Code is ${err.code}, message is ${err.message}`);
});

sendPrivateCommand¹²⁺

sendPrivateCommand(commandData: Record<string, CommandDataType>): Promise<void>

Sends private data to the system component that needs to communicate with the input method application. This API uses a promise to return the result.

NOTE

• The private data channel allows communication between the system preset input method application and specific system components (such as a text box or a home screen application). It is usually used to implement custom input on a specific device.
• The total size of the private data is 32 KB, and the maximum number of private data records is 5.
• Private data is sent to the text box by default. To send it to a desktop application, add a data entry {'sys_cmd':1} to the private data.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
commandData	Record<string, CommandDataType>	Yes	Private data to send.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800010	not the preconfigured default input method.

Example

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

inputMethodEngine.getInputMethodAbility().on('inputStart', (kbController, textInputClient) => {
  let record: Record<string, inputMethodEngine.CommandDataType> = {
    "valueString1": "abcdefg",
    "valueString2": true,
    "valueString3": 500,
  }
  textInputClient.sendPrivateCommand(record).then(() => {
  }).catch((err: BusinessError) => {
    if (err !== undefined) {
      console.error(`sendPrivateCommand catch error: ${err.code} ${err.message}`);
    }
  });
})

getCallingWindowInfo¹²⁺

getCallingWindowInfo(): Promise<WindowInfo>

Obtains information about the application window, in which the input box that starts an input method is located. This API uses a promise to return the result.

NOTE

This API applies only to the input method applications that use Panel as the soft keyboard window.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
Promise<WindowInfo>	Promise used to return the information obtained.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800012	the input method panel does not exist.
12800013	window manager service error.

Example

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

inputClient.getCallingWindowInfo().then((windowInfo: inputMethodEngine.WindowInfo) => {
  console.info(`windowInfo.rect: ${windowInfo.rect.left}, ${windowInfo.rect.top}, ${windowInfo.rect.width}, ${windowInfo.rect.height}`);
  console.info(`windowInfo.status: ${windowInfo.status}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to getCallingWindowInfo. Code is ${err.code}, message is ${err.message}`);
});

setPreviewText¹²⁺

setPreviewText(text: string, range: Range): Promise<void>

Sets the preview text. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
text	string	Yes	Preview text to set.
range	Range	Yes	Range of the preview text. - If the value is { start: -1, end: -1 }, text replaces the entire text in the current preview area by default. - If start is equal to end, text is inserted into the cursor position specified by start. - If start is not equal to end, text replaces the text of the specified range. - If the values of start and end are negative values, a parameter error is returned. - If there is preview text in the text box, the value of range cannot exceed the range of the preview text. Otherwise, a parameter error is returned. - If there is no preview text in the text box, the value of range cannot exceed the text range of the text box. Otherwise, a parameter error is returned.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800011	text preview not supported.

Example

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

let range: inputMethodEngine.Range = { start: 0, end: 1 };
inputClient.setPreviewText('test', range).then(() => {
  console.info('Succeeded in setting preview text.');
}).catch((err: BusinessError) => {
  console.error(`Failed to setPreviewText. Code is ${err.code}, message is ${err.message}`);
});

setPreviewTextSync¹²⁺

setPreviewTextSync(text: string, range: Range): void

Sets the preview text.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
text	string	Yes	Preview text to set.
range	Range	Yes	Range of the preview text. - If the value is { start: -1, end: -1 }, text replaces the entire text in the current preview area by default. - If start is equal to end, text is inserted into the cursor position specified by start. - If start is not equal to end, text replaces the text of the specified range. - If the values of start and end are negative values, a parameter error is returned. - If there is preview text in the text box, the value of range cannot exceed the range of the preview text. Otherwise, a parameter error is returned. - If there is no preview text in the text box, the value of range cannot exceed the text range of the text box. Otherwise, a parameter error is returned.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800011	text preview not supported.

Example

let range: inputMethodEngine.Range = { start: 0, end: 1 };
inputClient.setPreviewTextSync('test', range);

finishTextPreview¹²⁺

finishTextPreview(): Promise<void>

Finishes the text preview. This API uses a promise to return the result.

NOTE

If there is preview text in the current text box, calling this API will display the preview text on the screen.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800011	text preview not supported.

Example

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

inputClient.finishTextPreview().then(() => {
  console.info('Succeeded in finishing text preview.');
}).catch((err: BusinessError) => {
  console.error(`Failed to finishTextPreview. Code is ${err.code}, message is ${err.message}`);
});

finishTextPreviewSync¹²⁺

finishTextPreviewSync(): void

Finishes the text preview.

NOTE

If there is preview text in the current text box, calling this API will display the preview text on the screen.

System capability: SystemCapability.MiscServices.InputMethodFramework

Error codes

For details about the error codes, see Input Method Framework Error Codes.

ID	Error Message
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800011	text preview not supported.

Example

inputClient.finishTextPreviewSync();

sendMessage¹⁵⁺

sendMessage(msgId: string, msgParam?: ArrayBuffer): Promise<void>

Sends the custom communication to the edit box application attached to the input method application. This API uses a promise to return the result.

NOTE

This API can be called only when the edit box is attached to the input method and enter the edit mode, and the input method application is in full experience mode.

The maximum length of msgId is 256 B, and the maximum length of msgParam is 128 KB.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
msgId	string	Yes	Identifier of the custom data to be sent to the edit box application attached to the input method application.
msgParam	ArrayBuffer	No	Message body of the custom data to be sent to the edit box application attached to the input method application.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Input Method Framework Error Codes and Universal Error Codes.

ID	Error Message
401	parameter error. Possible causes: 1. Incorrect parameter types. 2. Incorrect parameter length.
12800003	input method client error. Possible causes: 1.the edit box is not focused. 2.no edit box is bound to current input method application. 3.ipc failed due to the large amount of data transferred or other reasons.
12800009	input method client detached.
12800014	the input method is in basic mode.
12800015	the other side does not accept the request.
12800016	input method client is not editable.

Example

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

let msgId: string = "testMsgId";
let msgParam: ArrayBuffer = new ArrayBuffer(128);
inputClient.sendMessage(msgId, msgParam).then(() => {
  console.info('Succeeded send message.');
}).catch((err: BusinessError) => {
  console.error(`Failed to send message. Code is ${err.code}, message is ${err.message}`);
});

recvMessage¹⁵⁺

recvMessage(msgHandler?: MessageHandler): void;

Registers or unregisters MessageHandler.

NOTE

The MessageHandler object is globally unique. After multiple registrations, only the last registered object is valid and retained, and the onTerminated callback of the penultimate registered object is triggered.

If no parameter is set, unregister MessageHandler. Its onTerminated callback will be triggered.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
msgHandler	MessageHandler	No	This object receives custom communication data from the edit box application attached to the input method application through onMessage and receives a message for terminating the subscription to this object through onTerminated. If no parameter is set, unregister MessageHandler. Its onTerminated callback will be triggered.

Error codes

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

ID	Error Message
401	parameter error. Possible causes: 1. Incorrect parameter types.

Example

inputMethodEngine.getInputMethodAbility()
  .on('inputStart',
    (kbController: inputMethodEngine.KeyboardController, client: inputMethodEngine.InputClient) => {
      let keyboardController: inputMethodEngine.KeyboardController = kbController;
      let inputClient: inputMethodEngine.InputClient = client;
      let messageHandler: inputMethodEngine.MessageHandler = {
        onTerminated(): void {
          console.info('OnTerminated.');
        },
        onMessage(msgId: string, msgParam?: ArrayBuffer): void {
          console.info('recv message.');
        }
      }
      inputClient.recvMessage(messageHandler);
    });

getAttachOptions¹⁹⁺

getAttachOptions(): AttachOptions

Obtains the additional options for binding an input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
AttachOptions	Additional options for binding an input method.

NOTE

Error code 801 Capability not supported. is removed since API version 20.

Example

let attachOptions: inputMethodEngine.AttachOptions = inputClient.getAttachOptions();
console.info(`Succeeded in getting AttachOptions, AttachOptions is ${attachOptions}`);

on('attachOptionsDidChange')¹⁹⁺

on(type: 'attachOptionsDidChange', callback: Callback<AttachOptions>): void

Subscribes to the event indicating that the additional options for binding an input method are changed. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Additional option change event when the input method is bound. The value is fixed to 'attachOptionsDidChange'.
callback	Callback<AttachOptions>	Yes	Callback used to return the additional options for binding an input method.

NOTE

Error code 801 Capability not supported. is removed since API version 20.

Example

let attachOptionsDidChangeCallback: (attachOptions: inputMethodEngine.AttachOptions) => void =
  (attachOptions: inputMethodEngine.AttachOptions) => {
    console.info(`AttachOptionsDidChangeCallback1: attachOptionsDidChange event triggered`);
  };

inputClient.on('attachOptionsDidChange', attachOptionsDidChangeCallback);
console.info(`attachOptionsDidChangeCallback subscribed to attachOptionsDidChange`);
inputClient.off('attachOptionsDidChange', attachOptionsDidChangeCallback);
console.info(`attachOptionsDidChange unsubscribed from attachOptionsDidChange`);

off('attachOptionsDidChange')¹⁹⁺

off(type: 'attachOptionsDidChange', callback?: Callback<AttachOptions>): void

Unsubscribes from the event indicating that additional options for binding an input method are changed. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Additional option change event when the input method is bound. The value is fixed to 'attachOptionsDidChange'.
callback	Callback<AttachOptions>	No	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified type by default.

Example

let attachOptionsDidChangeCallback: (attachOptions: inputMethodEngine.AttachOptions) => void =
  (attachOptions: inputMethodEngine.AttachOptions) => {
    console.info(`AttachOptionsDidChangeCallback1: attachOptionsDidChange event triggered`);
  };

inputClient.on('attachOptionsDidChange', attachOptionsDidChangeCallback);
console.info(`attachOptionsDidChangeCallback subscribed to attachOptionsDidChange`);
inputClient.off('attachOptionsDidChange', attachOptionsDidChangeCallback);
console.info(`attachOptionsDidChange unsubscribed from attachOptionsDidChange`);

CapitalizeMode²⁰⁺

Enumerates the modes of capitalizing the first letter of a text.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Value	Description
NONE	0	The first letter is not capitalized.
SENTENCES	1	The first letter of each sentence is capitalized.
WORDS	2	The first letter of each word is capitalized.
CHARACTERS	3	All letters are capitalized.

EditorAttribute

Represents the attributes of the edit box.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Type	Read-Only	Optional	Description
enterKeyType	number	Yes	No	Function attributes of the edit box. For details, see function key definitions in constants.
inputPattern	number	Yes	No	Text attribute of the edit box. For details, see edit box definitions in constants.
isTextPreviewSupported12+	boolean	No	No	Whether text preview is supported. - true: Supported. - false: Unsupported.
bundleName14+	string	Yes	Yes	Name of the application package to which the edit box belongs. The value may be "". Handle this scenario when using the attribute.
immersiveMode15+	ImmersiveMode	Yes	Yes	Immersive mode of the input method.
windowId18+	number	Yes	Yes	ID of the window where the edit box is located.
displayId18+	number	Yes	Yes	Screen ID of the window corresponding to the edit box. If window ID is not set, the screen ID of the focused window is used.
placeholder20+	string	Yes	Yes	Placeholder information set for the edit box.
abilityName20+	string	Yes	Yes	Ability name set for the edit box.
capitalizeMode20+	CapitalizeMode	Yes	Yes	Whether to capitalize the first letter in the edit box. If it is not set or is set to an invalid value, the first letter is not capitalized by default.
gradientMode20+	GradientMode	Yes	Yes	Gradient mode. If this attribute is not specified or is set to an invalid value, the gradient mode is not used by default.
extraConfig22+	InputMethodExtraConfig	Yes	Yes	Extra information about the input method.

KeyEvent

Represents the attributes of a key.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Type	Read-Only	Optional	Description
keyCode	number	Yes	No	Key value. For details, see KeyCode.
keyAction	number	Yes	No	Key event type. - 2: keydown event. - 3: keyup event.

PanelFlag¹⁰⁺

Enumerates the state types of the input method panel.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Value	Description
FLG_FIXED	0	Fixed state type.
FLG_FLOATING	1	Floating state type.
FLAG_CANDIDATE15+	2	Candidate state type.

PanelType¹⁰⁺

Enumerates the types of the input method panel.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Value	Description
SOFT_KEYBOARD	0	Soft keyboard type.
STATUS_BAR	1	Status bar type.

PanelInfo¹⁰⁺

Describes the attributes of the input method panel.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Type	Read-Only	Optional	Description
type	PanelType	No	No	Type of the panel.
flag	PanelFlag	No	Yes	State type of the panel.

PanelRect¹²⁺

Represents the size of the input method panel.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Type	Read-Only	Optional	Description
landscapeRect	window.Rect	No	No	Size of the input method panel window in landscape mode.
portraitRect	window.Rect	No	No	Size of the input method panel window in portrait mode.

EnhancedPanelRect¹⁵⁺

Indicates the size of the enhanced input method panel, including the custom avoid area and touch area.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Type	Read-Only	Optional	Description
landscapeRect	window.Rect	No	Yes	Size of the input method panel window in landscape mode. - This attribute is mandatory when fullScreenMode is not set or is set to false.
portraitRect	window.Rect	No	Yes	Size of the input method panel window in portrait mode. - This attribute is mandatory when fullScreenMode is not set or is set to false.
landscapeAvoidY	number	No	Yes	Distance between the avoid line and the top of the panel in landscape mode, in px. The default value is 0. - Other system components in the application avoid the input method panel area below the avoid line. - When the panel is fixed, the distance between the avoid line and the bottom of the screen cannot exceed 70% of the screen height.
landscapeInputRegion	Array<window.Rect>	No	Yes	Region where the panel receives input events in landscape mode. - The array size is limited to [1, 4]. The default value is the panel size in landscape mode. - The input hot zone is relative to the left vertex of the input method panel window.
portraitAvoidY	number	No	Yes	Distance between the avoid line and the top of the panel in portrait mode, in px. The default value is 0. - Other system components in the application avoid the input method panel area below the avoid line. - When the panel is fixed, the distance between the avoid line and the bottom of the screen cannot exceed 70% of the screen height.
portraitInputRegion	Array<window.Rect>	No	Yes	Region where the panel receives input events in portrait mode. - The array size is limited to [1, 4]. The default value is the panel size in portrait mode. - The input hot zone is relative to the left vertex of the input method panel window.
fullScreenMode	boolean	No	Yes	Indicates whether to enable the full-screen mode. The default value is false. - If the value is true, landscapeRect and portraitRect are optional. - If the value is false, landscapeRect and portraitRect are mandatory.

KeyboardArea¹⁵⁺

Represents the keyboard area on the panel.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Type	Read-Only	Optional	Description
top	number	No	No	Distance between the upper boundary of the keyboard area and the upper boundary of the panel area, in pixels. The value is an integer.
bottom	number	No	No	Distance between the lower boundary of the keyboard area and the lower boundary of the panel area, in pixels. The value is an integer.
left	number	No	No	Distance between the left boundary of the keyboard area and the left boundary of the panel area, in pixels. The value is an integer.
right	number	No	No	Distance between the right border of the keyboard area and the right border of the panel area, in pixels. The value is an integer.

AttachOptions¹⁹⁺

Defines additional options for binding an input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Type	Read-Only	Optional	Description
requestKeyboardReason	RequestKeyboardReason	No	Yes	Reason for requesting the keyboard. This attribute is set by the edit box application. If this attribute is not set or is set to an invalid value, the keyboard will not be triggered by default.
isSimpleKeyboardEnabled20+	boolean	No	Yes	Whether to enable the simple keyboard. This attribute is set by the edit box application. The value true means that the simple keyboard is enabled, and the value false means the opposite. If this attribute is not set or is set to an invalid value, the simple keyboard is disabled by default.

WindowInfo¹²⁺

Represents window information.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Type	Read-Only	Optional	Description
rect	window.Rect	No	No	Rectangular area of the window.
status	window.WindowStatusType	No	No	Window status type.

ImmersiveMode¹⁵⁺

Enumerates the immersive modes of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Value	Description
NONE_IMMERSIVE	0	The immersive mode is not used.
IMMERSIVE	1	The immersive mode is used. Its style is determined by the input method application.
LIGHT_IMMERSIVE	2	Immersive style in light mode.
DARK_IMMERSIVE	3	Immersive style in dark mode.

RequestKeyboardReason¹⁹⁺

Enumerates the reasons for requesting keyboard input.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Value	Description
NONE	0	The keyboard request is triggered for no reason.
MOUSE	1	The keyboard request is triggered by a mouse operation.
TOUCH	2	The keyboard request is triggered by a touch operation.
OTHER	20	The keyboard request is triggered by other reasons.

GradientMode²⁰⁺

Enumerates the gradient modes of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Value	Description
NONE	0	The gradient mode is not used.
LINEAR_GRADIENT	1	Linear gradient.

ImmersiveEffect²⁰⁺

Describes the immersive effect.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Type	Read-Only	Optional	Description
gradientHeight	number	No	No	Gradient height, which cannot exceed 15% of the screen height.
gradientMode	GradientMode	No	No	Gradient mode.

SystemPanelInsets²¹⁺

Defines the offset area between the input method soft keyboard and the system panel.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name	Type	Read-Only	Optional	Description
bottom	number	Yes	No	Distance between the bottom border of the keyboard area and the bottom border of the system panel area, in px. The value is an integer.
left	number	Yes	No	Distance between the left border of the keyboard area and the left border of the system panel area, in px. The value is an integer.
right	number	Yes	No	Distance between the right border of the keyboard area and the right border of the system panel area, in px. The value is an integer.

TextInputClient^(deprecated)

In the following API examples, you must first use on('inputStart') to obtain a TextInputClient instance, and then call the APIs using the obtained instance.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use InputClient instead.

getForward^(deprecated)

getForward(length:number, callback: AsyncCallback<string>): void

Obtains the specific-length text before the cursor. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use getForward instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.
callback	AsyncCallback<string>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is the obtained text. Otherwise, err is an error object.

Example

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

let length: number = 1;
textInputClient.getForward(length, (err: BusinessError, text: string) => {
  if (err) {
    console.error(`Failed to getForward. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in getting forward, text: ' + text);
});

getForward^(deprecated)

getForward(length:number): Promise<string>

Obtains the specific-length text before the cursor. This API uses a promise to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use getForward instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.

Return value

Type	Description
Promise<string>	Promise used to return the specific-length text before the cursor.

Example

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

let length: number = 1;
textInputClient.getForward(length).then((text: string) => {
  console.info('Succeeded in getting forward, text: ' + text);
}).catch((err: BusinessError) => {
  console.error(`Failed to getForward. Code is ${err.code}, message is ${err.message}`);
});

getBackward^(deprecated)

getBackward(length:number, callback: AsyncCallback<string>): void

Obtains the specific-length text after the cursor. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use getBackward instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.
callback	AsyncCallback<string>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is the obtained text. Otherwise, err is an error object.

Example

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

let length: number = 1;
textInputClient.getBackward(length, (err: BusinessError, text: string) => {
  if (err) {
    console.error(`Failed to getBackward. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info('Succeeded in getting backward, text: ' + text);
});

getBackward^(deprecated)

getBackward(length:number): Promise<string>

Obtains the specific-length text after the cursor. This API uses a promise to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use getBackward instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.

Return value

Type	Description
Promise<string>	Promise used to return the specific-length text after the cursor.

Example

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

let length: number = 1;
textInputClient.getBackward(length).then((text: string) => {
  console.info(`'Succeeded in getting backward: ${text}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to getBackward. Code is ${err.code}, message is ${err.message}`);
});

deleteForward^(deprecated)

deleteForward(length:number, callback: AsyncCallback<boolean>): void

Deletes the fixed-length text before the cursor. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use deleteForward instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is true. Otherwise, err is an error object.

Example

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

let length: number = 1;
textInputClient.deleteForward(length, (err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to deleteForward. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in deleting forward.');
  } else {
    console.error('Failed to deleteForward.');
  }
});

deleteForward^(deprecated)

deleteForward(length:number): Promise<boolean>

Deletes the fixed-length text before the cursor. This API uses a promise to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use deleteForward instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true means that the deletion is successful, and false means the opposite.

Example

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

let length: number = 1;
textInputClient.deleteForward(length).then((result: boolean) => {
  if (result) {
    console.info('Succeeded in deleting forward.');
  } else {
    console.error('Failed to delete forward.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to deleteForward. Code is ${err.code}, message is ${err.message}`);
});

deleteBackward^(deprecated)

deleteBackward(length:number, callback: AsyncCallback<boolean>): void

Deletes the fixed-length text after the cursor. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use deleteBackward instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is true. Otherwise, err is an error object.

Example

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

let length: number = 1;
textInputClient.deleteBackward(length, (err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to deleteBackward. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in deleting backward.');
  } else {
    console.error('Failed to deleteBackward.');
  }
});

deleteBackward^(deprecated)

deleteBackward(length:number): Promise<boolean>

Deletes the fixed-length text after the cursor. This API uses a promise to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use deleteBackward instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
length	number	Yes	Text length, which cannot be less than 0.

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true means that the deletion is successful, and false means the opposite.

Example

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

let length: number = 1;
textInputClient.deleteBackward(length).then((result: boolean) => {
  if (result) {
    console.info('Succeeded in deleting backward.');
  } else {
    console.error('Failed to deleteBackward.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to deleteBackward. Code is ${err.code}, message is ${err.message}`);
});

sendKeyFunction^(deprecated)

sendKeyFunction(action: number, callback: AsyncCallback<boolean>): void

Sends the function key. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use sendKeyFunction instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
action	number	Yes	Action of the function key. - 0: invalid key. - 1: confirm key (Enter key).
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is true. Otherwise, err is an error object.

Example

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

let action: number = 1;
textInputClient.sendKeyFunction(action, (err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to sendKeyFunction. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in sending key function.');
  } else {
    console.error('Failed to sendKeyFunction.');
  }
});

sendKeyFunction^(deprecated)

sendKeyFunction(action: number): Promise<boolean>

Sends the function key. This API uses a promise to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use sendKeyFunction instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
action	number	Yes	Action of the function key. 0: invalid key. 1: confirm key (Enter key).

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true means that the setting is successful, and false means the opposite.

Example

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

let action: number = 1;
textInputClient.sendKeyFunction(action).then((result: boolean) => {
  if (result) {
    console.info('Succeeded in sending key function.');
  } else {
    console.error('Failed to sendKeyFunction.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to sendKeyFunction:. Code is ${err.code}, message is ${err.message}`);
});

insertText^(deprecated)

insertText(text:string, callback: AsyncCallback<boolean>): void

Inserts text. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use insertText instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
text	string	Yes	Text to insert.
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is true. Otherwise, err is an error object.

Example

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

textInputClient.insertText('test', (err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to insertText. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in inserting text.');
  } else {
    console.error('Failed to insertText.');
  }
});

insertText^(deprecated)

insertText(text:string): Promise<boolean>

Inserts text. This API uses a promise to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use insertText instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
text	string	Yes	Text to insert.

Return value

Type	Description
Promise<boolean>	Promise used to return the result. The value true means that the insertion is successful, and false means the opposite.

Example

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

textInputClient.insertText('test').then((result: boolean) => {
  if (result) {
    console.info('Succeeded in inserting text.');
  } else {
    console.error('Failed to insertText.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to insertText. Code is ${err.code}, message is ${err.message}`);
});

getEditorAttribute^(deprecated)

getEditorAttribute(callback: AsyncCallback<EditorAttribute>): void

Obtains the attribute of the edit box. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use getEditorAttribute instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<EditorAttribute>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is the attribute of the edit box. Otherwise, err is an error object.

Example

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


textInputClient.getEditorAttribute((err: BusinessError,
  editorAttribute: inputMethodEngine.EditorAttribute) => {
  if (err) {
    console.error(`Failed to getEditorAttribute. Code is ${err.code}, message is ${err.message}`);
    return;
  }
  console.info(`editorAttribute.inputPattern: ${editorAttribute.inputPattern}`);
  console.info(`editorAttribute.enterKeyType: ${editorAttribute.enterKeyType}`);
});

getEditorAttribute^(deprecated)

getEditorAttribute(): Promise<EditorAttribute>

Obtains the attribute of the edit box. This API uses a promise to return the result.

NOTE

This API is supported since API version 8 and deprecated since API version 9. You are advised to use getEditorAttribute instead.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
Promise<EditorAttribute>	Promise used to return the attribute of the edit box.

Example

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

textInputClient.getEditorAttribute().then((editorAttribute: inputMethodEngine.EditorAttribute) => {
  console.info(`editorAttribute.inputPattern: ${editorAttribute.inputPattern}`);
  console.info(`editorAttribute.enterKeyType: ${editorAttribute.enterKeyType}}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to getEditorAttribute. Code is ${err.code}, message is ${err.message}`);
});