目录

@ohos.inputMethod (Input Method Framework)

The @ohos.inputMethod module is the input method client module for common foreground applications (such as Notes, Messaging, and Settings). It provides input method control and management capabilities.

This module is the client interface of the input method framework. It provides edit box applications with the ability to interact with the input method service, including input method attachment/detachment, soft keyboard showing/hiding, input method switching, input method list query, edit box attribute and cursor update, text selection and operation event listening, and custom message communication.

This module provides two core capability sets: (1) Through InputMethodController, it enables attachment, interaction, and event listening between edit box applications and the input method. After an edit box application attaches to the input method, it can control the showing and hiding of the keyboard, update the cursor and edit attributes, listen to text operation events sent by the input method (insert/delete/select text, move cursor, send function keys and extended actions, etc.), and communicate bidirectionally with the input method application through a custom message channel. (2) Through InputMethodSetting, it implements input method management, including obtaining the input method list, querying the current input method and subtype, subscribing to input method switching events, switching input methods and subtypes, and querying the panel display status.

Use this module when developing applications with text edit boxes (which need to interact with the input method) or system applications (which need to manage input methods). Typical scenarios include: attaching to the input method and showing the keyboard when an edit box in the application gains focus, detaching from the input method and hiding the keyboard when the edit box loses focus, and switching and configuring input methods in the system Settings application.

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

This module is the client control module in IME Kit. It works together with other modules in IME Kit:

The typical call sequence for a client application (such as Notes or Settings) to interact with the input method is as follows:

  1. Obtain the client controller instance InputMethodController through inputMethod.getController().
  2. Attach to the input method through InputMethodController.attach() (for self-drawn component scenarios), or rely on the system native edit box to attach automatically.
  3. Bring up the soft keyboard through InputMethodController.showTextInput() to enter the text editing state.
  4. During editing, synchronize the edit box state to the input method through APIs such as updateCursor, changeSelection, and updateAttribute.
  5. Hide the soft keyboard through InputMethodController.hideTextInput() to exit the editing state.
  6. Detach from the input method through InputMethodController.detach().

Pairing constraints:

The core open capabilities of this module are implemented by the following key interfaces:

Interface Description
InputMethodController The input method controller, which is the core object for interaction between the edit box application and the input method. It provides capabilities such as attaching to or detaching from the input method (attach/detach), showing/hiding the keyboard (showTextInput/hideTextInput), updating the cursor and edit attributes (updateCursor/updateAttribute/changeSelection), listening for input method operation events (insertText/deleteLeft/deleteRight/selectByRange/selectByMovement/moveCursor/sendFunctionKey/sendKeyboardStatus/handleExtendAction/setPreviewText/finishTextPreview), custom message communication (sendMessage/recvMessage), and stopping the input session. Obtain an instance through getController().
InputMethodSetting The input method setting management object, which provides input method query and management capabilities. It includes obtaining the list of enabled/disabled/all input methods (getInputMethods/getAllInputMethods), querying the subtype list of a specified input method (listInputMethodSubtype), obtaining the current input method and subtype, subscribing to input method switching events (on('imeChange')), subscribing to panel showing/hiding events (on('imeShow')/on('imeHide')), querying the panel display state (isPanelShown), enabling/disabling an input method (enableInputMethod), and obtaining the enabled state of the input method itself (getInputMethodState). Obtain an instance through getSetting().

In addition, this module defines multiple key data types:

Type Description
InputMethodProperty Input method property information, describing the name, ID, label, icon, enabled status, and other properties of an input method.
InputMethodSubtype Input method subtype, describing the language, mode, and other subtype properties of an input method.
TextConfig Text configuration of the edit box, including the input attribute (InputAttribute), cursor information (CursorInfo), selection information, window ID, and more.
InputAttribute Input attribute, defining the text input type (TextInputType) and the Enter key type (EnterKeyType).
CursorInfo Cursor information, defining the position and size of the cursor.
MessageHandler Custom message handler, used to receive messages sent by the input method application and provide termination notifications.

The typical process of interaction between an edit box application and the input method involves the combined invocation of multiple APIs of InputMethodController: obtain the controller -> attach to the input method -> subscribe to input method operation events -> process text operations in the callback -> detach from the input method.

// The following is pseudocode illustrating the calling logic.

// 1. Obtain the input method controller and setting object.
let controller = inputMethod.getController();
let setting = inputMethod.getSetting();

// 2. Subscribe to input method operation events (subscribe before the attach API is called to ensure no events are missed).
controller.on('insertText', (text) => { /*Handle text insertion*/ });
controller.on('deleteLeft', (length) => { /*Handle backward deletion*/ });
controller.on('deleteRight', (length) => { /*Handle forward deletion*/ });
controller.on('selectByRange', (range) => { /*Handle text selection by range*/ });
controller.on('selectByMovement', (movement) => { /*Handle text selection by direction*/ });
controller.on('moveCursor', (direction) => { /*Handle cursor movement*/ });
controller.on('sendFunctionKey', (functionKey) => { /*Handle function keys*/ });
controller.on('handleExtendAction', (action) => { /*Handle extended actions*/ });

// 3. Attach the input method (called when the edit box gains focus).
let textConfig = {
  inputAttribute: { textInputType: TextInputType.TEXT, enterKeyType: EnterKeyType.NONE },
  cursorInfo: { left: 100, top: 200, width: 2, height: 20 },
  selection: { start: 0, end: 0 },
  windowId: 1
};
controller.attach(true, textConfig);

// 4. Show the keyboard.
controller.showTextInput();

// 5. Update the cursor and edit attributes (called when the edit box state changes).
controller.updateCursor(cursorInfo);
controller.updateAttribute(inputAttribute);
controller.changeSelection(text, start, end);

// 6. When the keyboard needs to be hidden.
controller.hideTextInput();

// 7. Detach the input method when the edit box loses focus.
controller.detach();

// 8. Switch the input method for system applications.
setting.getInputMethods(true);  // Obtain the list of enabled input methods.
inputMethod.switchInputMethod(targetProperty);  // Switch to the target input method.

Subscription to input method operation events (such as insertText and deleteLeft) should be completed before attach is called to avoid missing events. attach is the prerequisite for an edit box application to use input method capabilities. The input method must be attached before subsequent operations can be performed.

Modules to Import

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

Constant

Provides the constants.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Value Description
MAX_TYPE_NUM8+ number 128 Maximum number of supported input methods.

InputMethodProperty8+

Describes the input method application properties.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read-only Optional Description
name9+ string Yes No Mandatory. Name of the input method package.
id9+ string Yes No Mandatory. Unique identifier of an input method extension in an app. id and name form a globally unique identifier of the input method extension.
label9+ string Yes Yes

Optional.

- When InputMethodProperty is used as the input parameter of an API for switching or querying, you do not need to set this field. You can use name and ID to uniquely specify an input method extension.

- When InputMethodProperty is used as the return value of an API for querying (for example, getCurrentInputMethod), this field indicates the name of the input method extension displayed externally. Use the label configured for the InputMethodExtensionAbility. If no label is configured, the label of the application entry ability is automatically used. If no label is configured for the application entry ability, the label configured in AppScope is automatically used.
labelId10+ number Yes Yes

Optional.

- When InputMethodProperty is used as the input parameter of an API for switching or querying, you do not need to set this field. You can use name and ID to uniquely specify an input method extension.

- When InputMethodProperty is used as the return value of an API for querying (for example, getCurrentInputMethod), this field indicates the resource ID of the label field.
icon9+ string Yes Yes

Optional.

- When InputMethodProperty is used as the input parameter of an API for switching or querying, you do not need to set this field. You can use name and ID to uniquely specify an input method extension.

- When InputMethodProperty is used as the return value of an API for querying (for example, getCurrentInputMethod), this field indicates the input method icon data, which can be obtained through icon ID.
iconId9+ number Yes Yes

Optional.

- When InputMethodProperty is used as the input parameter of an API for switching or querying, you do not need to set this field. You can use name and ID to uniquely specify an input method extension.

- When InputMethodProperty is used as the return value of an API for querying (for example, getCurrentInputMethod), this field indicates the resource ID of the icon field.
enabledState20+ EnabledState Yes Yes

Optional.

- When InputMethodProperty is used as an input parameter for switching, querying, and other APIs, you may omit this field, and an input method extension can be uniquely specified by name and id.

- When InputMethodProperty is used as the return value of a query API (such as getCurrentInputMethod), this field indicates the enabled state of the input method.
extra9+ object No Yes

Extended information of the input method.

- Since API version 10: optional;

- API version 9: mandatory.
packageName(deprecated) string Yes No

Name of the input method package. Mandatory.

Note: This API is supported since API version 8 and deprecated since API version 9. You are advised to use name instead.
methodId(deprecated) string Yes No

Unique ID of the input method. Mandatory.

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

CapitalizeMode20+

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

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Value Description
NONE 0

No initial capitalization is performed.

Usage scenarios: Applicable to input boxes that do not require automatic capitalization, such as password input and verification code input.
SENTENCES 1

The first letter of each sentence is capitalized.

Usage scenarios: Applicable to ordinary text input boxes, such as chat and memo, where the first letter is automatically capitalized following punctuation marks such as a period.
WORDS 2

The first letter of each word is capitalized.

Usage scenarios: Applicable to scenarios where the first letter of each word needs to be capitalized, such as titles and personal names.
CHARACTERS 3

Every letter is capitalized.

Usage scenarios: Applicable to all uppercase input scenarios, such as abbreviation input (for example, the domain name part in a URL).

inputMethod.getController9+

getController(): InputMethodController

Obtains an InputMethodController instance.

Meaning/Function: Obtains the input method client controller instance of the current application, which is used for subsequent interaction with the input method (such as attaching to the input method, showing/hiding the keyboard, and synchronizing the edit box status).

Usage scenarios: When a foreground application (such as a memo or chat application) needs to control the showing/hiding of the input method, attach to or detach from the input method, or synchronize edit box information, it must first obtain the InputMethodController instance through this API.

Use effect: Returns an InputMethodController instance. Subsequently, the instance can be used to call a series of APIs such as attach, showTextInput, hideTextInput, and detach to interact with the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
InputMethodController InputMethodController instance.

Error codes

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

ID Error Message
12800006 input method controller error. Possible cause: create InputMethodController object failed.

Example

let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();

inputMethod.getDefaultInputMethod11+

getDefaultInputMethod(): InputMethodProperty

Obtains the default input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
InputMethodProperty Default input method property 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.

Example

let defaultIme: inputMethod.InputMethodProperty = inputMethod.getDefaultInputMethod();

inputMethod.getSystemInputMethodConfigAbility11+

getSystemInputMethodConfigAbility(): ElementName

Obtains the information about the system input method configuration ability.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
ElementName Element name of the input method configuration page ability.

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.

Example

import { bundleManager } from '@kit.AbilityKit';

let inputMethodConfig: bundleManager.ElementName = inputMethod.getSystemInputMethodConfigAbility();

inputMethod.getSetting9+

getSetting(): InputMethodSetting

Obtains an InputMethodSetting instance.

Meaning/Function: Obtains the input method setting instance, which is used for configuration management operations such as querying the input method list, subscribing to input method change events, and querying panel visibility.

Usage scenarios: When an application needs to query the installed/activated input method list, subscribe to input method switching events, or display the input method selection dialog, it must first obtain the InputMethodSetting instance through this API.

Use effect: Returns an InputMethodSetting instance. Subsequently, the instance can be used to call APIs such as getInputMethods, listInputMethodSubtype, and on('imeChange').

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
InputMethodSetting InputMethodSetting instance.

Error codes

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

ID Error Message
12800007 input method setter error. Possible cause: create InputMethodSetting object failed.

Example

let inputMethodSetting: inputMethod.InputMethodSetting = inputMethod.getSetting();

inputMethod.switchInputMethod9+

switchInputMethod(target: InputMethodProperty, callback: AsyncCallback<boolean>): void

Switches the input method. This API uses an asynchronous callback to return the result.

Meaning/Function: Switches the current input method to the specified target input method.

Usage scenarios: Used when the current input method application needs to switch to another input method (for example, when the user selects a new input method in the input method settings).

Use effect: On success, the system switches the current input method to the target input method, and the target input method becomes the new current input method; on failure, the current input method remains unchanged.

Required permissions:

Required permissions:

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
target InputMethodProperty Yes

Target input method.

Usage scenarios: Specifies the target input method to switch to, uniquely identified by name and id.

Note: only the name and id fields need to be filled in to uniquely specify an input method; optional fields such as label and icon are not required.
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
201 permissions check fails. [since 9 - 10].
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800005 configuration persistence error.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

let currentIme: inputMethod.InputMethodProperty = inputMethod.getCurrentInputMethod();
inputMethod.switchInputMethod(currentIme, (err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to switchInputMethod, code: ${err.code}, message: ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in switching input method.');
  } else {
    console.error('Failed to switch input method.');
  }
});

In API version 11, the error code 201 permissions check fails. has been removed.

inputMethod.switchInputMethod9+

switchInputMethod(target: InputMethodProperty): Promise<boolean>

Switches the input method. This API uses a promise to return the result.

Meaning/Function: Switches the current input method to the specified target input method.

Usage scenarios: Used when the current input method application needs to switch to another input method.

Use effect: On success, the system switches the current input method to the target input method; on failure, the current input method remains unchanged.

Required permissions:

Required permissions:

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
target InputMethodProperty Yes

Target input method.

Usage scenarios: Specifies the target input method to switch to, uniquely determined by name and id.

Note: only the name and id fields need to be filled in to uniquely specify an input method.

Return value

Type Description
Promise<boolean> Promise object. When resolved, returns true if the input method is switched successfully, and returns false if the input method fails to be switched; when rejected, returns an error object, indicating that an error occurs during input method switching.

Error codes

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

ID Error Message
201 permissions check fails. [since 9 - 10]
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800005 configuration persistence error.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

let currentIme: inputMethod.InputMethodProperty = inputMethod.getCurrentInputMethod();
inputMethod.switchInputMethod(currentIme).then((result: boolean) => {
  if (result) {
    console.info('Succeeded in switching input method.');
  } else {
    console.error('Failed to switch input method.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to switchInputMethod, code: ${err.code}, message: ${err.message}`);
});

In API 11, the error code 201 permissions check fails. is removed.

inputMethod.getCurrentInputMethod9+

getCurrentInputMethod(): InputMethodProperty

Obtains the current input method. This API returns the result synchronously.

Meaning/Function: Obtains the property information of the input method currently in use.

Usage scenarios: Used when an application needs to know which input method is currently active (for example, to determine the input method name or obtain the input method ID for subsequent switching operations).

Use effect: Returns the InputMethodProperty object of the current input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
InputMethodProperty Input method property object.

Example

let currentIme: inputMethod.InputMethodProperty = inputMethod.getCurrentInputMethod();

inputMethod.switchCurrentInputMethodSubtype9+

switchCurrentInputMethodSubtype(target: InputMethodSubtype, callback: AsyncCallback<boolean>): void

Switches to another subtype of this input method. This API uses an asynchronous callback to return the result.

Required permissions:

Required permissions:

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
target InputMethodSubtype Yes Target input method subtype.
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
201 permissions check fails. [since 9 - 10]
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800005 configuration persistence error.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

let extra: Record<string, string> = {}
// For details, see the parameter description of **InputMethodSubtype**.
inputMethod.switchCurrentInputMethodSubtype({
  id: "ServiceExtAbility",
  label: "",
  name: "com.example.keyboard",
  mode: "upper",
  locale: "",
  language: "",
  icon: "",
  iconId: 0,
  extra: extra
}, (err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to switchCurrentInputMethodSubtype, code: ${err.code}, message: ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in switching currentInputMethodSubtype.');
  } else {
    console.error('Failed to switchCurrentInputMethodSubtype');
  }
});

In API 11, the error code 201 permissions check fails. is removed.

inputMethod.switchCurrentInputMethodSubtype9+

switchCurrentInputMethodSubtype(target: InputMethodSubtype): Promise<boolean>

Switches to another subtype of this input method. This API uses a promise to return the result.

Required permissions:

Required permissions:

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
target InputMethodSubtype Yes Target input method subtype.

Return value

Type Description
Promise<boolean> Promise object. When resolved, true indicates that the current input method subtype is switched successfully, and false indicates that the current input method subtype fails to be switched; when rejected, an error object is returned, indicating that an error occurs during input method subtype switching.

Error codes

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

ID Error Message
201 permissions check fails. [since 9 - 10]
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800005 configuration persistence error.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

let extra: Record<string, string> = {}
// For details, see the parameter description of **InputMethodSubtype**.
inputMethod.switchCurrentInputMethodSubtype({
  id: "ServiceExtAbility",
  label: "",
  name: "com.example.keyboard",
  mode: "upper",
  locale: "",
  language: "",
  icon: "",
  iconId: 0,
  extra: extra
}).then((result: boolean) => {
  if (result) {
    console.info('Succeeded in switching currentInputMethodSubtype.');
  } else {
    console.error('Failed to switchCurrentInputMethodSubtype.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to switchCurrentInputMethodSubtype, code: ${err.code}, message: ${err.message}`);
});

In API 11, the error code 201 permissions check fails. is removed.

inputMethod.getCurrentInputMethodSubtype9+

getCurrentInputMethodSubtype(): InputMethodSubtype

Obtains the current input method subtype.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
InputMethodSubtype Current input method subtype.

Example

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

let currentImeSubType: InputMethodSubtype = inputMethod.getCurrentInputMethodSubtype();

inputMethod.switchCurrentInputMethodAndSubtype9+

switchCurrentInputMethodAndSubtype(inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype, callback: AsyncCallback<boolean>): void

Switches to a specified subtype of a specified input method. This API uses an asynchronous callback to return the result.

Required permissions:

Required permissions:

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
inputMethodProperty InputMethodProperty Yes Target input method.
inputMethodSubtype InputMethodSubtype Yes Target input method subtype.
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
201 permissions check fails. [since 9 - 10].
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800005 configuration persistence error.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

let currentIme: inputMethod.InputMethodProperty = inputMethod.getCurrentInputMethod();
let imSubType: InputMethodSubtype = inputMethod.getCurrentInputMethodSubtype();
inputMethod.switchCurrentInputMethodAndSubtype(currentIme, imSubType, (err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to switchCurrentInputMethodAndSubtype, code: ${err.code}, message: ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in switching currentInputMethodAndSubtype.');
  } else {
    console.error('Failed to switchCurrentInputMethodAndSubtype.');
  }
});

In API 11, the error code 201 permissions check fails. is removed.

inputMethod.switchCurrentInputMethodAndSubtype9+

switchCurrentInputMethodAndSubtype(inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype): Promise<boolean>

Switches to a specified subtype of a specified input method. This API uses a promise to return the result.

Required permissions:

Required permissions:

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
inputMethodProperty InputMethodProperty Yes Target input method.
inputMethodSubtype InputMethodSubtype Yes Target input method subtype.

Return value

Type Description
Promise<boolean> Promise object. When resolved, true is returned if switching to the specified subtype of the specified input method succeeds, and false is returned if switching to the specified subtype of the specified input method fails; when rejected, an error object is returned, indicating that an error occurred while switching to the specified subtype of the specified input method.

Error codes

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

ID Error Message
201 permissions check fails. [since 9 - 10].
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
12800005 configuration persistence error.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

let currentIme: inputMethod.InputMethodProperty = inputMethod.getCurrentInputMethod();
let imSubType: InputMethodSubtype = inputMethod.getCurrentInputMethodSubtype();
inputMethod.switchCurrentInputMethodAndSubtype(currentIme, imSubType).then((result: boolean) => {
  if (result) {
    console.info('Succeeded in switching currentInputMethodAndSubtype.');
  } else {
    console.error('Failed to switchCurrentInputMethodAndSubtype.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to switchCurrentInputMethodAndSubtype, code: ${err.code}, message: ${err.message}`);
});

In API 11, the error code 201 permissions check fails. is removed.

inputMethod.getInputMethodController(deprecated)

getInputMethodController(): InputMethodController

Obtains an InputMethodController instance.

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

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
InputMethodController Current InputMethodController instance.

Example

let inputMethodController: inputMethod.InputMethodController = inputMethod.getInputMethodController();

inputMethod.getInputMethodSetting(deprecated)

getInputMethodSetting(): InputMethodSetting

Obtains an InputMethodSetting instance.

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

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
InputMethodSetting InputMethodSetting instance.

Example

let inputMethodSetting: inputMethod.InputMethodSetting = inputMethod.getInputMethodSetting();

inputMethod.setSimpleKeyboardEnabled20+

setSimpleKeyboardEnabled(enable: boolean): void

Enables or disables the simple keyboard.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
enable boolean Yes

Whether to enable the simple keyboard. The value true indicates that the simple keyboard is enabled; the value false indicates the opposite.

The native edit box takes effect when it is focused next time, while the self-drawn component takes effect when the input method is attached by calling attach next time.

Example

  let enable: boolean = false;
  inputMethod.setSimpleKeyboardEnabled(enable);

inputMethod.onAttachmentDidFail22+

onAttachmentDidFail(callback: Callback<AttachFailureReason>): void

Subscribes to attachment failure events. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
callback Callback<AttachFailureReason> Yes Callback used to return the reason for attachment failure. This callback is only invoked when the attachment failure is triggered by the registrant's process.

Example

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

let attachmentDidFailCallback: Callback<inputMethod.AttachFailureReason> =
  (reason: inputMethod.AttachFailureReason): void => {
    console.error(`Attachment failed with reason: ${reason}.`);
  if (reason === inputMethod.AttachFailureReason.CALLER_NOT_FOCUSED) {
    console.error(`Failure reason is CALLER_NOT_FOCUSED.`);
  }
  };
inputMethod.onAttachmentDidFail(attachmentDidFailCallback);

inputMethod.offAttachmentDidFail22+

offAttachmentDidFail(callback?: Callback<AttachFailureReason>): void

Unsubscribes from attachment failure events. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
callback Callback<AttachFailureReason> No Callback used for unsubscription, which must be the same as that passed by the subscription API. If no parameter is specified, all callback functions for this event will be unsubscribed.

Example

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

let attachmentDidFailCallback: Callback<inputMethod.AttachFailureReason> =
  (reason: inputMethod.AttachFailureReason): void => {
    console.error(`Attachment failed with reason: ${reason}.`);
  if (reason === inputMethod.AttachFailureReason.CALLER_NOT_FOCUSED) {
    console.error(`Failure reason is CALLER_NOT_FOCUSED.`);
  }
  };
inputMethod.onAttachmentDidFail(attachmentDidFailCallback);
inputMethod.offAttachmentDidFail(attachmentDidFailCallback);

TextInputType10+

Enumerates the text input types.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Value Description
NONE -1

NONE.

Usage scenarios: used when the edit box does not want to specify a particular input type, and the input method uses the default keyboard layout.
TEXT 0

Text type.

Usage scenarios: applicable to ordinary text input boxes, such as chat and memo, and the input method displays a full-featured keyboard.
MULTILINE 1

Multiline type.

Usage scenarios: applicable to scenarios that require multiline text input, such as long text editing and comment boxes.
NUMBER 2

Number type.

Usage scenarios: applicable to scenarios that require only numeric input, such as quantity input and age input, and the input method displays a numeric keyboard.
PHONE 3

Phone number type.

Usage scenarios: applicable to phone number input boxes, and the input method displays a phone number keyboard (including digits and common phone symbols).
DATETIME 4

Date type.

Usage scenarios: applicable to date and time input boxes, and the input method displays a date-related keyboard layout.
EMAIL_ADDRESS 5

Email address type.

Usage scenarios: applicable to email input boxes, and the input method keyboard highlights common email symbols such as "@" and ".".
URL 6

Link type.

Usage scenarios: applicable to URL input boxes, and the input method keyboard highlights common URL symbols such as "/" and ".".
VISIBLE_PASSWORD 7

Password type.

Usage scenarios: applicable to password input boxes, and the input method displays a visible password keyboard without automatic suggestions.
NUMBER_PASSWORD11+ 8

Numeric password type.

Usage scenarios: applicable to scenarios that require only numeric password input, such as PIN code input.
SCREEN_LOCK_PASSWORD20+ 9

Screen lock password type.

Usage scenarios: applicable to the password input box on the lock screen.
USER_NAME20+ 10

Username type.

Usage scenarios: applicable to username input boxes, and the input method can provide optimized suggestions based on username characteristics.
NEW_PASSWORD20+ 11

New password type.

Usage scenarios: applicable to input boxes for setting a new password, and the input method can provide password strength hints.
NUMBER_DECIMAL20+ 12

Number type with a decimal point.

Usage scenarios: applicable to scenarios that require input of numbers with a decimal point, such as amount input.
ONE_TIME_CODE20+ 13

Verification code type.

Usage scenarios: applicable to verification code input boxes, and the input method can optimize the verification code input experience.

EnterKeyType10+

Enumerates the function types represented by the Enter key of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Value Description
UNSPECIFIED 0

Unspecified.

Usage scenarios: used when the edit box does not specify a specific function for the Enter key.
NONE 1

NONE.

Usage scenarios: the Enter key has no specific behavior and is used only as a line break or a normal key.
GO 2

Go.

Usage scenarios: applicable to URL input boxes, where the Enter key triggers the "Go" action, such as opening a link.
SEARCH 3

Search.

Usage scenarios: applicable to search boxes, where the Enter key triggers the search action.
SEND 4

Send.

Usage scenarios: applicable to message sending boxes, where the Enter key triggers the send action.
NEXT 5

Next.

Usage scenarios: applicable to multi-step forms, where the Enter key jumps to the next input box.
DONE 6

Done.

Usage scenarios: applicable to the last input box of a single-step form, where the Enter key indicates that input is complete.
PREVIOUS 7

Previous.

Usage scenarios: applicable to multi-step forms, where the Enter key jumps to the previous input box.
NEWLINE12+ 8

Line break.

Usage scenarios: applicable to multi-line text edit boxes, where the Enter key inserts a line break.

KeyboardStatus10+

Enumerates the soft keyboard states of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Value Description
NONE 0

NONE.

Usage scenarios: used when the keyboard status is not determined or cannot be determined.
HIDE 1

Hidden state.

Usage scenarios: indicates that the soft keyboard is currently hidden.
SHOW 2

Shown state.

Usage scenarios: indicates that the soft keyboard is currently shown.

Direction10+

Enumerates the directions of cursor movement of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Value Description
CURSOR_UP 1

Upward.

Usage scenarios: Used when the input method requests to move the cursor upward, such as moving the cursor up in multi-line text.
CURSOR_DOWN 2

Downward.

Usage scenarios: Used when the input method requests to move the cursor downward.
CURSOR_LEFT 3

Leftward.

Usage scenarios: Used when the input method requests to move the cursor leftward, such as moving the cursor before deleting the character to the left of the cursor.
CURSOR_RIGHT 4

Rightward.

Usage scenarios: Used when the input method requests to move the cursor rightward.

ExtendAction10+

Enumerates the types of extended edit actions on the edit box.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Value Description
SELECT_ALL 0

Select all.

Usage scenarios: used when the input method requests to select all text in the edit box.
CUT 3

Cut.

Usage scenarios: used when the input method requests to cut the selected text, copying the selected text to the clipboard and deleting the original text.
COPY 4

Copy.

Usage scenarios: used when the input method requests to copy the selected text, copying the selected text to the clipboard.
PASTE 5

Paste.

Usage scenarios: used when the input method requests to paste the clipboard content.

FunctionKey10+

Describes the type of the input method function key.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read-only Optional Description
enterKeyType EnterKeyType No No Function type represented by the Enter key of the input method.

InputAttribute10+

Describes the attributes of the edit box, including the text input type and Enter key function type.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read-only Optional Description
textInputType TextInputType No No Enumerates the text input types.
enterKeyType EnterKeyType No No Function type represented by the Enter key.
placeholder20+ string No Yes

Placeholder information set for the edit box.

- When placeholder information is set for the edit box, the length cannot exceed 255 characters (a placeholder longer than 255 characters will be automatically truncated to 255 characters). It is used to prompt or guide users to enter temporary text or symbols. (For example, the placeholder indicates whether the input item is mandatory.)

- If no placeholder is set for the edit box, the value is an empty string by default.

- This field is provided for the input method application when attach is called.
abilityName20+ string No Yes

Ability name set for the edit box.

- If the ability name is set for the edit box, the length cannot exceed 127 characters. (A name longer than 127 characters will be automatically truncated to 127 characters.)

- If the ability name is not set for the edit box, the value is an empty string by default.

- This field is provided for the input method application when attach is called.
consumeKeyEvents boolean No Yes

Whether the edit box has full capability to handle keys such as letters, characters, and function keys. The default value is false.

- The value true means that the edit box has this capability.

- The value false means that the edit box does not have this capability.

- This field is provided for the input method application when attach/updateAttribute is called.

Since: 26.0.0

Model restriction: This parameter can be used only in the stage model.

TextConfig10+

Describes the configuration of the edit box.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read-only Optional Description
inputAttribute InputAttribute No No Edit box attribute.
cursorInfo CursorInfo No Yes Cursor information.
selection Range No Yes Text selection range.
windowId number No Yes

ID of the window where the edit box is located. The value must be an integer.

You are advised to call getWindowProperties to obtain the window ID.
newEditBox20+ boolean No Yes Whether the edit box is new. The value true means the edit box is new; the value false means the opposite.
capitalizeMode20+ CapitalizeMode No Yes Capitalization mode set for the edit box. If it is not set or is set to an invalid value, no initial capitalization is performed by default.

CursorInfo10+

Represents the cursor information.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read-only Optional Description
left number No No Horizontal coordinate of the cursor, in px. The value must be an integer. The minimum value is 0 and the maximum value is the width of the current screen.
top number No No Vertical coordinate of the cursor, in px. The value must be an integer. The minimum value is 0 and the maximum value is the height of the current screen.
width number No No Width of the cursor, in px. The value must be an integer. The minimum value is 0 and the maximum value is the width of the current screen.
height number No No Height of the cursor, in px. The value must be an integer. The minimum value is 0 and the maximum value is the height of the current screen.
displayId number No Yes

ID of the display where the cursor is located.

Since: 26.0.0

Model restriction: This parameter can be used only in the stage model.

Range10+

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 edit box. The value is an integer greater than or equal to 0, and cannot exceed the actual text length.
end number No No Index of the last selected character in the edit box. The value is an integer greater than or equal to 0, and cannot exceed the actual text length. The end value must be greater than the start value.

Movement10+

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.

InputWindowInfo10+

Describes the window information of the input method keyboard.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read-only Optional Description
name string No No Name of the input method keyboard window.
left number No No Horizontal coordinate of the upper left corner of the input method keyboard window, in px. The value must be an integer. The minimum value is 0 and the maximum value is the width of the current screen.
top number No No Vertical coordinate of the upper left corner of the input method keyboard window, in px. The value must be an integer. The minimum value is 0 and the maximum value is the height of the current screen.
width number No No Width of the input method keyboard window, in px. The value must be an integer. The minimum value is 0 and the maximum value is the width of the current screen.
height number No No Height of the input method keyboard window, in px. The value must be an integer. The minimum value is 0 and the maximum value is the height of the current screen.
displayId23+ number No Yes

ID of the display where the soft keyboard window is located.

Model restriction: This parameter can be used only in the stage model.

EnabledState15+

Indicates whether the input method is enabled.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Value Description
DISABLED 0

Not enabled.

Usage scenarios: The input method is disabled and cannot be used as the current input method.
BASIC_MODE 1

Basic mode.

Usage scenarios: The input method is enabled but in basic mode, providing only basic input capabilities and not supporting advanced features (such as custom communication).
FULL_EXPERIENCE_MODE 2

Full experience mode.

Usage scenarios: The input method is enabled and in full experience mode, supporting all features (including custom communication and text preview).

RequestKeyboardReason15+

Enumerates the reasons for requesting the keyboard.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Value Description
NONE 0

Indicates that no specific reason triggers the keyboard request.

Usage scenarios: default value, used when no specific trigger reason is specified.
MOUSE 1

Indicates that the keyboard request is triggered by a mouse operation.

Usage scenarios: used when the user clicks the edit box with a mouse to trigger the keyboard to pop up.
TOUCH 2

Indicates that the keyboard request is triggered by a touch operation.

Usage scenarios: used when the user taps the edit box to trigger the keyboard to pop up.
OTHER 20

Indicates that the keyboard request is triggered by other reasons.

Usage scenarios: used when the trigger reason for the keyboard to pop up is neither mouse nor touch.

MessageHandler15+

Represents a custom communication object.

You can register this object to receive custom communication data sent by 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.

[h2]onMessage15+

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

Receives custom data sent by the input method application.

This callback is triggered when the registered MessageHandler receives custom communication data sent by 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

let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();

let messageHandler: inputMethod.MessageHandler = {
  onTerminated(): void {
    console.info('OnTerminated.');
  },
  onMessage(msgId: string, msgParam?: ArrayBuffer): void {
    console.info(`recv message, msg: ${msgId}, msgParam: ${JSON.stringify(msgParam)}`);
  }
};
inputMethodController.recvMessage(messageHandler);

[h2]onTerminated15+

onTerminated(): void

Listens for MessageHandler termination.

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

When an application unregisters a MessageHandler object, the OnTerminated callback of the current registered MessageHandler object is triggered.

System capability: SystemCapability.MiscServices.InputMethodFramework

Example

let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();

let messageHandler: inputMethod.MessageHandler = {
  onTerminated(): void {
    console.info('OnTerminated.');
  },
  onMessage(msgId: string, msgParam?: ArrayBuffer): void {
    console.info(`recv message, msg: ${msgId}, msgParam: ${JSON.stringify(msgParam)}`);
  }
};
inputMethodController.recvMessage(messageHandler);

SetPreviewTextCallback17+

type SetPreviewTextCallback = (text: string, range: Range) => void

Callback triggered when the input method framework needs to display the text preview.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
text string Yes Preview text content.
range Range Yes Describes the range of the selected text.

AttachFailureReason22+

Enumerates the reasons for attachment failure.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Value Description
CALLER_NOT_FOCUSED 0

Indicates a failure caused because the caller is not the application that owns the focused window.

Usage scenarios: When attach is called while the application window is not focused, this failure reason is returned.

Note: Ensure that the application window is focused before calling attach.
IME_ABNORMAL 1

Indicates a failure caused by an input method application exception.

Usage scenarios: When the input method application process crashes or is not running normally, attach returns this failure reason.
SERVICE_ABNORMAL 2

Indicates a failure caused by an input method framework service exception.

Usage scenarios: When the input method framework service process is abnormal, attach returns this failure reason.

AttachOptions23+

Defines additional options for binding an input method.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.MiscServices.InputMethodFramework

Name Type Read-only Optional Description
requestKeyboardReason RequestKeyboardReason No Yes Reason for requesting the keyboard.
showKeyboard boolean No Yes

Whether to start the input method keyboard after the input method attachment is complete.

- true means to start the input method keyboard.

- false means not to start the input method keyboard.

InputMethodController

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

InputMethodController is the input method client controller, which provides foreground applications with core capabilities for interacting with the input method. After obtaining an instance through inputMethod.getController(), you can perform the following operations:

Typical call sequence: getController() → attach() → showTextInput()/hideTextInput() → detach()

attach and detach must be used in pairs, and showTextInput and hideTextInput must be used in pairs. Otherwise, resource leaks or inconsistent states may occur.

[h2]attach10+

attach(showKeyboard: boolean, textConfig: TextConfig, callback: AsyncCallback<void>): void

Attaches a self-drawn component to the input method. This API uses an asynchronous callback to return the result.

Meaning/Function: Establishes attachment between a self-drawn component and the input method application. This is the prerequisite for a self-drawn component to use input method features.

Usage scenarios: When a self-drawn component (not a system native edit box) needs to interact with the input method, this API must be called first to establish attachment. When a native edit box gains focus, the system performs attachment automatically, and there is no need to call this API.

Use effect: After the attachment succeeds, the self-drawn component can call showTextInput/hideTextInput to control the keyboard visibility, and call updateCursor/changeSelection to synchronize the edit box state, subscribe to input method events, and implement more features.

Preconditions: The window where the self-drawn component resides must be in the focused state; otherwise, the attachment fails.

Usage with related APIs: attach must be used in pairs with detach. Only after attach is called can APIs such as showTextInput, hideTextInput, and updateCursor be called.

Differences between similar APIs and selection principles:

An input method can use the following features only when it has a self-drawn component attached to it: showing or hiding the keyboard, updating the cursor information, changing the selection range of the edit box, saving the configuration information, and listening for and processing information or commands sent by the input method.

If the window where the self-drawn component is located is set to be non-focusable via setWindowFocusable, the system cannot guarantee proper interaction between the self-drawing input component and the input method. If you want to draw an input box in a non-focusable window, refer to Input Box and Input Method Interaction in Non-Focusable Windows.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
showKeyboard boolean Yes

Whether to start the input method keyboard after the input method is successfully attached.

- true means to start the input method keyboard.

- false means not to start the input method keyboard.
textConfig TextConfig Yes Configuration of the edit box.
callback AsyncCallback<void> Yes Callback used to return the result. If the input method is successfully attached, 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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

let inputAttribute: inputMethod.InputAttribute = {
  textInputType: inputMethod.TextInputType.TEXT,
  enterKeyType: inputMethod.EnterKeyType.GO
}
let textConfig: inputMethod.TextConfig = { inputAttribute: inputAttribute };
inputMethod.getController().attach(true, textConfig, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to attach, code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in attaching the inputMethod.');
});

[h2]attach10+

attach(showKeyboard: boolean, textConfig: TextConfig): Promise<void>

Attaches a self-drawn component to the input method. This API uses a promise to return the result.

An input method can use the following features only when it has a self-drawn component attached to it: showing or hiding the keyboard, updating the cursor information, changing the selection range of the edit box, saving the configuration information, and listening for and processing the information or commands sent by the input method.

If the window where the self-drawn component is located is set to be non-focusable via setWindowFocusable, the system cannot guarantee proper interaction between the self-drawing input component and the input method. If you want to draw an input box in a non-focusable window, refer to Input Box and Input Method Interaction in Non-Focusable Windows.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
showKeyboard boolean Yes

Whether to start the input method keyboard after the input method is successfully attached.

- true means to start the input method keyboard.

- false means not to start the input method keyboard.
textConfig TextConfig Yes Configuration of the edit box.

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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

let inputAttribute: inputMethod.InputAttribute = {
  textInputType: inputMethod.TextInputType.TEXT,
  enterKeyType: inputMethod.EnterKeyType.GO
}
let textConfig: inputMethod.TextConfig = { inputAttribute: inputAttribute };
inputMethod.getController().attach(true, textConfig).then(() => {
  console.info('Succeeded in attaching inputMethod.');
}).catch((err: BusinessError) => {
  console.error(`Failed to attach, code: ${err.code}, message: ${err.message}`);
});

[h2]attach15+

attach(showKeyboard: boolean, textConfig: TextConfig, requestKeyboardReason: RequestKeyboardReason): Promise<void>

Attaches a self-drawn component to the input method. This API uses a promise to return the result.

An input method can use the following features only when it has a self-drawn component attached to it: showing or hiding the keyboard, updating the cursor information, changing the selection range of the edit box, saving the configuration information, and listening for and processing the information or commands sent by the input method.

If the window where the self-drawn component is located is set to be non-focusable via setWindowFocusable, the system cannot guarantee proper interaction between the self-drawing input component and the input method. If you want to draw an input box in a non-focusable window, refer to Input Box and Input Method Interaction in Non-Focusable Windows.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
showKeyboard boolean Yes

Whether to start the input method keyboard after the input method is successfully attached.

- true means to start the input method keyboard.

- false means not to start the input method keyboard.
textConfig TextConfig Yes Configuration of the edit box.
requestKeyboardReason RequestKeyboardReason Yes Reason for requesting the keyboard.

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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

let inputAttribute: inputMethod.InputAttribute = {
  textInputType: inputMethod.TextInputType.TEXT,
  enterKeyType: inputMethod.EnterKeyType.GO
}
let textConfig: inputMethod.TextConfig = { inputAttribute: inputAttribute };
let requestKeyboardReason: inputMethod.RequestKeyboardReason = inputMethod.RequestKeyboardReason.MOUSE;

inputMethod.getController().attach(true, textConfig, requestKeyboardReason).then(() => {
  console.info('Succeeded in attaching inputMethod.');
}).catch((err: BusinessError) => {
  console.error(`Failed to attach, code: ${err.code}, message: ${err.message}`);
});

[h2]attachWithUIContext23+

attachWithUIContext(uiContext: UIContext, textConfig: TextConfig, attachOptions?: AttachOptions): Promise<void>

Attaches a self-drawn component to the input method. This API uses a promise to return the result.

An input method can use the following features only when it has a self-drawn component attached to it: showing or hiding the keyboard, updating the cursor information, changing the selection range of the edit box, saving the configuration information, and listening for and processing the information or commands sent by the input method.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
uiContext UIContext Yes UIContext instance.
textConfig TextConfig Yes Configuration of the edit box.
attachOptions AttachOptions No Additional options for attachment.

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
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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

let uiContext: UIContext | undefined = UIContext.getCallingScopeUIContext();
let inputAttribute: inputMethod.InputAttribute = {
  textInputType: inputMethod.TextInputType.TEXT,
  enterKeyType: inputMethod.EnterKeyType.GO
}
let textConfig: inputMethod.TextConfig = { inputAttribute: inputAttribute };
let attachOptions: inputMethod.AttachOptions = { showKeyboard: true };
inputMethod.getController().attachWithUIContext(uiContext, textConfig, attachOptions).then(() => {
  console.info('Succeeded in attaching inputMethod.');
}).catch((err: BusinessError) => {
  console.error(`Failed to attach, code: ${err.code}, message: ${err.message}`);
});

[h2]discardTypingText20+

discardTypingText(): Promise<void>

Discards the text that is being typed. This API uses a promise to return the result.

This API can be called after the edit box is attached to an input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
Promise<void> Promise object 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.
12800009 input method client detached.
12800015 the other side does not accept the request.

Example

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

inputMethod.getController().discardTypingText().then(() => {
  console.info('Succeeded discardTypingText.');
}).catch((err: BusinessError) => {
  console.error(`Failed to discardTypingText, code: ${err.code}, message: ${err.message}`);
});

[h2]showTextInput10+

showTextInput(callback: AsyncCallback<void>): void

Enters the text editing mode. This API uses an asynchronous callback to return the result.

Meaning/Function: Pulls up the soft keyboard and puts the edit box into the text editing state.

Usage scenarios: Called when a self-drawn component needs to display the soft keyboard to start text input after being attached to the input method.

Use effect: The soft keyboard is displayed, and the edit box enters the editable text input state.

Preconditions: Call attach to complete the attachment first. Otherwise, error code 12800009 is reported.

Usage with related APIs: showTextInput and hideTextInput must be used in pairs. After hideTextInput is called to exit the editing state, showTextInput must be called again to re-enter the editing state.

Differences between similar APIs and selection principles:

After the edit box is attached to an input method, this API can be called to start the soft keyboard and enter the text editing state.

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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.
12800009 input method client detached.

Example

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

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

[h2]showTextInput10+

showTextInput(): Promise<void>

Enters the text editing mode. This API uses a promise to return the result.

After the edit box is attached to an input method, this API can be called to start the soft keyboard and enter the text editing state.

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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.
12800009 input method client detached.

Example

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

inputMethod.getController().showTextInput().then(() => {
  console.info('Succeeded in showing text input.');
}).catch((err: BusinessError) => {
  console.error(`Failed to showTextInput, code: ${err.code}, message: ${err.message}`);
});

[h2]showTextInput15+

showTextInput(requestKeyboardReason: RequestKeyboardReason): Promise<void>

Enters the text editing mode. This API uses a promise to return the result.

After the edit box is attached to an input method, this API can be called to start the soft keyboard and enter the text editing state.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
requestKeyboardReason RequestKeyboardReason Yes Reason for requesting the keyboard.

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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.
12800009 input method client detached.

Example

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

let requestKeyboardReason: inputMethod.RequestKeyboardReason = inputMethod.RequestKeyboardReason.MOUSE;

inputMethod.getController().showTextInput(requestKeyboardReason).then(() => {
  console.info('Succeeded in showing text input.');
}).catch((err: BusinessError) => {
  console.error(`Failed to showTextInput, code: ${err.code}, message: ${err.message}`);
});

[h2]hideTextInput10+

hideTextInput(callback: AsyncCallback<void>): void

Exits the text editing mode. This API uses an asynchronous callback to return the result.

Meaning/Function: Hides the soft keyboard and makes the edit box exit the text editing state.

Usage scenarios: Called when a self-drawn component no longer needs input, for example, when the user taps an area outside the edit box or switches to another page.

Use effect: The soft keyboard is hidden, and the edit box exits the editing state. Calling this API does not unbind the input method. Calling showTextInput again can re-enter the editing state.

Preconditions: Call attach to complete the attachment first, and call showTextInput to enter the editing state.

Usage with related APIs: hideTextInput and showTextInput must be used in pairs. If input is needed again after hideTextInput is called, you must call showTextInput first to re-enter the editing state; other editing operations cannot be called directly.

Differences between similar APIs and selection principles:

If the soft keyboard is displayed when this API is called, it will be hidden.

Calling this API does not detach the edit box from the input method. The edit box can call showTextInput again to reenter the text editing mode.

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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.
12800009 input method client detached.

Example

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

inputMethod.getController().hideTextInput((err: BusinessError) => {
  if (err) {
    console.error(`Failed to hideTextInput, code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in hiding text input.');
});

[h2]hideTextInput10+

hideTextInput(): Promise<void>

Exits the text editing mode. This API uses a promise to return the result.

If the soft keyboard is displayed when this API is called, it will be hidden.

Calling this API does not detach the edit box from the input method. The edit box can call showTextInput again to reenter the text editing mode.

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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.
12800009 input method client detached.

Example

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

inputMethod.getController().hideTextInput().then(() => {
  console.info('Succeeded in hiding inputMethod.');
}).catch((err: BusinessError) => {
  console.error(`Failed to hideTextInput, code: ${err.code}, message: ${err.message}`);
})

[h2]detach10+

detach(callback: AsyncCallback<void>): void

Detaches the self-drawn component from the input method. This API uses an asynchronous callback to return the result.

Meaning/Function: Detaches the self-drawn component from the input method application and releases related resources.

Usage scenarios: Called when the self-drawn component no longer needs to interact with the input method (for example, page switching, edit box destruction, etc.).

Use effect: After detachment, APIs that require the attached state, such as showTextInput, hideTextInput, and updateCursor, can no longer be called. The input method soft keyboard will be hidden.

Usage with related APIs: detach must be used in pairs with attach. It is recommended that you call detach after hideTextInput. The complete flow is: attach → showTextInput → hideTextInput → detach.

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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

inputMethod.getController().detach((err: BusinessError) => {
  if (err) {
    console.error(`Failed to detach, code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in detaching inputMethod.');
});

[h2]detach10+

detach(): Promise<void>

Detaches the self-drawn component from the input method. This API uses a promise to return the result.

Meaning/Function: Detaches the self-drawn component from the input method application and releases related resources.

Usage scenarios: Called when the self-drawn component no longer needs to interact with the input method.

Use effect: After detachment, APIs that require the attached state can no longer be called. The input method soft keyboard will be hidden.

Usage with related APIs: detach must be used in pairs with attach.

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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

inputMethod.getController().detach().then(() => {
  console.info('Succeeded in detaching inputMethod.');
}).catch((err: BusinessError) => {
  console.error(`Failed to detach, code: ${err.code}, message: ${err.message}`);
});

[h2]setCallingWindow10+

setCallingWindow(windowId: number, callback: AsyncCallback<void>): void

Sets the window to be avoided by the input method. This API uses an asynchronous callback to return the result.

This API can be called to set the window that avoids the soft keyboard only after the edit box is attached to the input method.

Pass in the window ID of the application attached to the input method. This window can avoid the input method window.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
windowId number Yes Window ID of the application bound to the input method. 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 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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.
12800009 input method client detached.

Example

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

let windowId: number = 2000;
inputMethod.getController().setCallingWindow(windowId, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to setCallingWindow, code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in setting callingWindow.');
});

[h2]setCallingWindow10+

setCallingWindow(windowId: number): Promise<void>

Sets the window to avoid the soft keyboard. This API uses a promise to return the result.

After the window ID of the application bound to the input method is passed in the API, the input method window will not cover the window holding the application.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
windowId number Yes Window ID of the application bound to the input method. 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 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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.
12800009 input method client detached.

Example

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

let windowId: number = 2000;
inputMethod.getController().setCallingWindow(windowId).then(() => {
  console.info('Succeeded in setting callingWindow.');
}).catch((err: BusinessError) => {
  console.error(`Failed to setCallingWindow, code: ${err.code}, message: ${err.message}`);
});

[h2]updateCursor10+

updateCursor(cursorInfo: CursorInfo, callback: AsyncCallback<void>): void

Updates the cursor information in this edit box. This API can be called to notify the input method of the cursor changes. This API uses an asynchronous callback to return the result.

This API can be called to update the cursor information only after the edit box is attached to the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
cursorInfo CursorInfo Yes Cursor information.
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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.
12800009 input method client detached.

Example

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

let cursorInfo: inputMethod.CursorInfo = {
  left: 0,
  top: 0,
  width: 600,
  height: 800
};
inputMethod.getController().updateCursor(cursorInfo, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to updateCursor, code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in updating cursorInfo.');
});

[h2]updateCursor10+

updateCursor(cursorInfo: CursorInfo): Promise<void>

Updates the cursor information in this edit box. This API can be called to notify the input method of the cursor changes. This API uses a promise to return the result.

This API can be called to update the cursor information only after the edit box is attached to the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
cursorInfo CursorInfo Yes Cursor information.

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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.
12800009 input method client detached.

Example

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

let cursorInfo: inputMethod.CursorInfo = {
  left: 0,
  top: 0,
  width: 600,
  height: 800
};
inputMethod.getController().updateCursor(cursorInfo).then(() => {
  console.info('Succeeded in updating cursorInfo.');
}).catch((err: BusinessError) => {
  console.error(`Failed to updateCursor, code: ${err.code}, message: ${err.message}`);
});

[h2]changeSelection10+

changeSelection(text: string, start: number, end: number, callback: AsyncCallback<void>): void

Updates the information about the selected text in this edit box, to notify the input method when the selected text content or text range changes. This API uses an asynchronous callback to return the result.

This API can be called to update the text selection information only after the edit box is attached to the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
text string Yes All input text.
start number Yes Start position of the selected text. The value is an integer greater than or equal to 0.
end number Yes End position of the selected text. The value is an integer greater than or equal to 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.
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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.
12800009 input method client detached.

Example

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

inputMethod.getController().changeSelection('text', 0, 5, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to changeSelection, code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in changing selection.');
});

[h2]changeSelection10+

changeSelection(text: string, start: number, end: number): Promise<void>

Updates the information about the selected text in this edit box, to notify the input method when the selected text content or text range changes. This API uses a promise to return the result.

This API can be called to update the text selection information only after the edit box is attached to the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
text string Yes All input text.
start number Yes Start position of the selected text. The value is an integer greater than or equal to 0.
end number Yes End position of the selected text. The value is an integer greater than or equal to 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.
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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.
12800009 input method client detached.

Example

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

inputMethod.getController().changeSelection('test', 0, 5).then(() => {
  console.info('Succeeded in changing selection.');
}).catch((err: BusinessError) => {
  console.error(`Failed to changeSelection, code: ${err.code}, message: ${err.message}`);
});

[h2]updateAttribute10+

updateAttribute(attribute: InputAttribute, callback: AsyncCallback<void>): void

Updates the attribute information of this edit box. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
attribute InputAttribute Yes Attribute information.
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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.
12800009 input method client detached.

Example

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

let inputAttribute: inputMethod.InputAttribute = { textInputType: 0, enterKeyType: 1 };
inputMethod.getController().updateAttribute(inputAttribute, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to updateAttribute, code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in updating attribute.');
});

[h2]updateAttribute10+

updateAttribute(attribute: InputAttribute): Promise<void>

Updates the attribute information of this edit box. This API uses a promise to return the result.

This API can be called to update the edit box attribute information only after the edit box is attached to the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
attribute InputAttribute Yes Attribute information.

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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.
12800009 input method client detached.

Example

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

let inputAttribute: inputMethod.InputAttribute = { textInputType: 0, enterKeyType: 1 };
inputMethod.getController().updateAttribute(inputAttribute).then(() => {
  console.info('Succeeded in updating attribute.');
}).catch((err: BusinessError) => {
  console.error(`Failed to updateAttribute, code: ${err.code}, message: ${err.message}`);
});

[h2]stopInputSession9+

stopInputSession(callback: AsyncCallback<boolean>): void

Ends this input session. This API uses an asynchronous callback to return the result.

Meaning/Function: Ends the current input session and hides the soft keyboard.

Usage scenarios: Called when an application needs to proactively end the input session (for example, when the user has completed the input operation).

Use effect: The soft keyboard is hidden and the input session ends.

Preconditions: This API can be called only when the edit box is attached to the input method, that is, after the edit control is tapped.

Usage with related APIs: stopInputSession hides the soft keyboard and ends the input session. If the attach/showTextInput/hideTextInput/detach flow of a self-drawn component is used, it is recommended that you use hideTextInput instead of stopInputSession.

This API can be called only when the edit box is attached to the input method. That is, it can be called to end the input session only when the edit box is focused.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
callback AsyncCallback<boolean> Yes Callback. When the input session ends successfully, err is undefined and data is true; when it fails, 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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

inputMethod.getController().stopInputSession((err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to stopInputSession, code: ${err.code}, message: ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in stopping inputSession.');
  } else {
    console.error('Failed to stopInputSession.');
  }
});

[h2]stopInputSession9+

stopInputSession(): Promise<boolean>

Ends this input session. This API uses a promise to return the result.

This API can be called only when the edit box is attached to the input method. That is, it can be called to end the input session only when the edit box is focused.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
Promise<boolean> Promise used to return the result. The value true indicates that the input session is ended successfully, and false indicates the opposite.

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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

inputMethod.getController().stopInputSession().then((result: boolean) => {
  if (result) {
    console.info('Succeeded in stopping inputSession.');
  } else {
    console.error('Failed to stopInputSession.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to stopInputSession, code: ${err.code}, message: ${err.message}`);
});

[h2]showSoftKeyboard9+

showSoftKeyboard(callback: AsyncCallback<void>): void

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

Meaning/Function: Forcibly displays the soft keyboard of the current input method.

Usage scenarios: Used when a system application needs to forcibly display the input method soft keyboard (for example, a Settings application testing an input method).

Use effect: The input method soft keyboard is displayed.

Preconditions: This API can be called only when the edit box is attached to the input method.

Differences between similar APIs and selection principles:

This API can be called only when the edit box is attached to the input method. That is, it can be called to show the soft keyboard only when the edit box is focused.

Required permissions: ohos.permission.CONNECT_IME_ABILITY (for system applications only)

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 and Universal Error Codes.

ID Error Message
201 permissions check fails.
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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

inputMethod.getController().showSoftKeyboard((err: BusinessError) => {
  if (!err) {
    console.info('Succeeded in showing softKeyboard.');
  } else {
    console.error(`Failed to show softKeyboard, ${err.code}, message: ${err.message}`);
  }
});

[h2]showSoftKeyboard9+

showSoftKeyboard(): Promise<void>

Shows the soft keyboard. This API uses a promise to return the result.

This API can be called only when the edit box is attached to the input method. That is, it can be called to show the soft keyboard only when the edit box is focused.

Required permissions: ohos.permission.CONNECT_IME_ABILITY (for system applications only)

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 and Universal Error Codes.

ID Error Message
201 permissions check fails.
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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

inputMethod.getController().showSoftKeyboard().then(() => {
  console.info('Succeeded in showing softKeyboard.');
}).catch((err: BusinessError) => {
  console.error(`Failed to show softKeyboard, code: ${err.code}, message: ${err.message}`);
});

[h2]hideSoftKeyboard9+

hideSoftKeyboard(callback: AsyncCallback<void>): void

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

Meaning/Function: Forcibly hides the soft keyboard of the current input method.

Usage scenarios: Used when a system application needs to forcibly hide the input method soft keyboard.

Use effect: The input method soft keyboard is hidden.

Preconditions: This API can be called only when the edit box is attached to the input method.

Differences between similar APIs and selection principles:

This API can be called only when the edit box is attached to the input method. That is, it can be called to hide the soft keyboard only when the edit box is focused.

Required permissions: ohos.permission.CONNECT_IME_ABILITY (for system applications only)

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 and Universal Error Codes.

ID Error Message
201 permissions check fails.
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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

inputMethod.getController().hideSoftKeyboard((err: BusinessError) => {
  if (!err) {
    console.info('Succeeded in hiding softKeyboard.');
  } else {
    console.error(`Failed to hide softKeyboard, code: ${err.code}, message: ${err.message}`);
  }
})

[h2]hideSoftKeyboard9+

hideSoftKeyboard(): Promise<void>

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

This API can be called only when the edit box is attached to the input method. That is, it can be called to hide the soft keyboard only when the edit box is focused.

Required permissions: ohos.permission.CONNECT_IME_ABILITY (for system applications only)

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 and Universal Error Codes.

ID Error Message
201 permissions check fails.
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.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

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

[h2]sendMessage15+

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

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

This API can be called only when the edit box is attached to the input method and enters 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 input method application.
msgParam ArrayBuffer No Message body of the custom data to be sent 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);
inputMethod.getController().sendMessage(msgId, msgParam).then(() => {
  console.info('Succeeded send message.');
}).catch((err: BusinessError) => {
  console.error(`Failed to send message, code: ${err.code}, message: ${err.message}`);
});

[h2]recvMessage15+

recvMessage(msgHandler?: MessageHandler): void

Registers or unregisters MessageHandler.

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 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 Input Method Framework Error Codes and Universal Error Codes.

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

Example

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

let messageHandler: inputMethod.MessageHandler = {
  onTerminated(): void {
    console.info('OnTerminated.');
  },
  onMessage(msgId: string, msgParam?: ArrayBuffer): void {
    console.info('recv message.');
  }
};
let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();
inputMethodController.recvMessage(messageHandler);
// Unregister the MessageHandler.
inputMethodController.recvMessage();

[h2]stopInput(deprecated)

stopInput(callback: AsyncCallback<boolean>): void

Ends this input session. This API uses an asynchronous callback to return the result.

This API can be called only when the edit box is attached to the input method. That is, it can be called to end the input session only when the edit box is focused.

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

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
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';

inputMethod.getController().stopInput((err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to stopInput, code: ${err.code}, message: ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in stopping input.');
  } else {
    console.error('Failed to stopInput.');
  }
});

[h2]stopInput(deprecated)

stopInput(): Promise<boolean>

Ends this input session. This API uses a promise to return the result.

This API can be called only when the edit box is attached to the input method. That is, it can be called to end the input session only when the edit box is focused.

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

System capability: SystemCapability.MiscServices.InputMethodFramework

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.

Example

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

inputMethod.getController().stopInput().then((result: boolean) => {
  if (result) {
    console.info('Succeeded in stopping input.');
  } else {
    console.error('Failed to stopInput.');
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to stopInput, code: ${err.code}, message: ${err.message}`);
});

[h2]on('insertText')10+

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

Enables listening for the text insertion 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 Listening type. The value is fixed at 'insertText'.
callback (text: string) => void Yes

Callback used to return the text to be inserted.

The application needs to operate the content in the edit box based on the text content returned in the callback.

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.
12800009 input method client detached.

Example

const callback1 = (text: string): void => {
  console.info(`Succeeded in getting callback1, data: ${text}`);
}

const callback2 = (text: string): void => {
  console.info(`Succeeded in getting callback2, data: ${text}`);
}

let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();
// Register a callback.
inputMethodController.on('insertText', callback1);
inputMethodController.on('insertText', callback2);
// Cancel only callback1 of insertText.
inputMethodController.off('insertText', callback1);
// Cancel all callbacks of insertText.
inputMethodController.off('insertText');

[h2]off('insertText')10+

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

Disables listening for the text insertion event of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type. The value is fixed at 'insertText'.
callback (text: string) => void No

Callback used to disable listening, which must be the same as that passed by the on API.

If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.

Example

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

let onInsertTextCallback: Callback<string> = (text: string): void => {
  console.info(`Succeeded in subscribing insertText: ${text}`);
};

let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();
inputMethodController.off('insertText', onInsertTextCallback);
inputMethodController.off('insertText');

[h2]on('deleteLeft')10+

on(type: 'deleteLeft', callback: (length: number) => void): void

Enables listening for the leftward delete event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type. The value is fixed at 'deleteLeft'.
callback (length: number) => void Yes

Callback used to return the length of the text to be deleted leftward.

The application needs to operate the content in the edit box based on the length returned in the callback.

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.
12800009 input method client detached.

Example

inputMethod.getController().on('deleteLeft', (length: number) => {
  console.info(`Succeeded in subscribing deleteLeft, length: ${length}`);
});

[h2]off('deleteLeft')10+

off(type: 'deleteLeft', callback?: (length: number) => void): void

Disables listening for the leftward delete event.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type. The value is fixed at 'deleteLeft'.
callback (length: number) => void No

Callback used to disable listening, which must be the same as that passed by the on API.

If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.

Example

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

let onDeleteLeftCallback: Callback<number> = (length: number): void => {
  console.info(`Succeeded in subscribing deleteLeft, length: ${length}`);
};

let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();
inputMethodController.off('deleteLeft', onDeleteLeftCallback);
inputMethodController.off('deleteLeft');

[h2]on('deleteRight')10+

on(type: 'deleteRight', callback: (length: number) => void): void

Enables listening for the rightward delete event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type. The value is fixed at 'deleteRight'.
callback (length: number) => void Yes

Callback used to return the length of the text to be deleted rightward.

The application needs to operate the content in the edit box based on the length returned in the callback.

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.
12800009 input method client detached.

Example

inputMethod.getController().on('deleteRight', (length: number) => {
  console.info(`Succeeded in subscribing deleteRight, length: ${length}`);
});

[h2]off('deleteRight')10+

off(type: 'deleteRight', callback?: (length: number) => void): void

Disables listening for the rightward delete event.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type. The value is fixed at deleteRight.
callback (length: number) => void No

Callback used to disable listening, which must be the same as that passed by the on API.

If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.

Example

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

let onDeleteRightCallback: Callback<number> = (length: number): void => {
  console.info(`Succeeded in subscribing deleteRight, length: ${length}`);
};
let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();
inputMethodController.off('deleteRight', onDeleteRightCallback);
inputMethodController.off('deleteRight');

[h2]on('sendKeyboardStatus')10+

on(type: 'sendKeyboardStatus', callback: (keyboardStatus: KeyboardStatus) => void): void

Enables listening for the soft keyboard status 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 Listening type. The value is fixed at 'sendKeyboardStatus'.
callback (keyboardStatus: KeyboardStatus) => void Yes

Callback used to return the soft keyboard status.

The application needs to perform operations based on the soft keyboard state returned in the callback.

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.
12800009 input method client detached.

Example

inputMethod.getController().on('sendKeyboardStatus', (keyboardStatus: inputMethod.KeyboardStatus) => {
  console.info(`Succeeded in subscribing sendKeyboardStatus, keyboardStatus: ${keyboardStatus}`);
});

[h2]off('sendKeyboardStatus')10+

off(type: 'sendKeyboardStatus', callback?: (keyboardStatus: KeyboardStatus) => void): void

Disables listening for the input method soft keyboard status event of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type. The value is fixed at 'sendKeyboardStatus'.
callback (keyboardStatus: KeyboardStatus) => void No Callback used to disable listening. If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.

Example

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

let onSendKeyboardStatus: Callback<inputMethod.KeyboardStatus> = (keyboardStatus: inputMethod.KeyboardStatus): void => {
  console.info(`Succeeded in subscribing sendKeyboardStatus, keyboardStatus: ${keyboardStatus}`);
};

let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();
inputMethodController.off('sendKeyboardStatus', onSendKeyboardStatus);
inputMethodController.off('sendKeyboardStatus');

[h2]on('sendFunctionKey')10+

on(type: 'sendFunctionKey', callback: (functionKey: FunctionKey) => void): void

Enables listening for the function key sending 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 Listening type. The value is fixed at 'sendFunctionKey'.
callback (functionKey: FunctionKey) => void Yes

Callback used to return the function key information sent by the input method.

The application needs to perform operations based on the function key information returned in the callback.

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.
12800009 input method client detached.

Example

inputMethod.getController().on('sendFunctionKey', (functionKey: inputMethod.FunctionKey) => {
  console.info(`Succeeded in subscribing sendFunctionKey, functionKey.enterKeyType: ${functionKey.enterKeyType}`);
});

[h2]off('sendFunctionKey')10+

off(type: 'sendFunctionKey', callback?: (functionKey: FunctionKey) => void): void

Disables listening for the function key sending event of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type. The value is fixed at 'sendFunctionKey'.
callback (functionKey: FunctionKey) => void No

Callback used to disable listening, which must be the same as that passed by the on API.

If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.

Example

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

let onSendFunctionKey: Callback<inputMethod.FunctionKey> = (functionKey: inputMethod.FunctionKey): void => {
  console.info(`Succeeded in subscribing sendFunctionKey, functionKey: ${functionKey.enterKeyType}`);
};

let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();
inputMethodController.off('sendFunctionKey', onSendFunctionKey);
inputMethodController.off('sendFunctionKey');

[h2]on('moveCursor')10+

on(type: 'moveCursor', callback: (direction: Direction) => void): void

Enables listening for the cursor movement 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 Listening type. The value is fixed at 'moveCursor'.
callback (direction: Direction) => void Yes

Callback used to return the cursor movement direction.

The application needs to change the cursor position based on the cursor movement direction returned in the callback.

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.
12800009 input method client detached.

Example

inputMethod.getController().on('moveCursor', (direction: inputMethod.Direction) => {
  console.info(`Succeeded in subscribing moveCursor, direction: ${direction}`);
});

[h2]off('moveCursor')10+

off(type: 'moveCursor', callback?: (direction: Direction) => void): void

Disables listening for the cursor movement event of the input method.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type. The value is fixed at 'moveCursor'.
callback (direction: Direction) => void No

Callback used to disable listening, which must be the same as that passed by the on API.

If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.

Example

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

let onMoveCursorCallback: Callback<inputMethod.Direction> = (direction: inputMethod.Direction): void => {
  console.info(`Succeeded in subscribing moveCursor, direction: ${direction}`);
};

let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();
inputMethodController.off('moveCursor', onMoveCursorCallback);
inputMethodController.off('moveCursor');

[h2]on('handleExtendAction')10+

on(type: 'handleExtendAction', callback: (action: ExtendAction) => void): void

Enables listening for the extended action handling 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 Listening type. The value is fixed at 'handleExtendAction'.
callback (action: ExtendAction) => void Yes

Callback used to return the extended action type.

The application needs to perform operations based on the extended action type returned in the callback.

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.
12800009 input method client detached.

Example

inputMethod.getController().on('handleExtendAction', (action: inputMethod.ExtendAction) => {
  console.info(`Succeeded in subscribing handleExtendAction, action: ${action}`);
});

[h2]off('handleExtendAction')10+

off(type: 'handleExtendAction', callback?: (action: ExtendAction) => void): void

Disables listening for the extended action handling 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 Listening type. The value is fixed at 'handleExtendAction'.
callback (action: ExtendAction) => void No

Callback used to disable listening, which must be the same as that passed by the on API.

If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.

Example

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

let onHandleExtendActionCallback: Callback<inputMethod.ExtendAction> = (action: inputMethod.ExtendAction): void => {
  console.info(`Succeeded in subscribing handleExtendAction, action: ${action}`);
};

let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();
inputMethodController.off('handleExtendAction', onHandleExtendActionCallback);
inputMethodController.off('handleExtendAction');

[h2]on('selectByRange')10+

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

Enables listening for the select-by-range event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type. The value is fixed at 'selectByRange'.
callback Callback<Range> Yes

Callback used to return the range of the text to be selected.

The application needs to select the text based on the range returned in the callback.

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

inputMethod.getController().on('selectByRange', (range: inputMethod.Range) => {
  console.info(`Succeeded in subscribing selectByRange: start: ${range.start} , end: ${range.end}`);
});

[h2]off('selectByRange')10+

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

Disables listening for the select-by-range event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type. The value is fixed at 'selectByRange'.
callback Callback<Range> No

Callback used to disable listening, which must be the same as that passed by the on API.

If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.

Example

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

let onSelectByRangeCallback: Callback<inputMethod.Range> = (range: inputMethod.Range): void => {
  console.info(`Succeeded in subscribing selectByRange, start: ${range.start} , end: ${range.end}`);
};

let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();
inputMethodController.off('selectByRange', onSelectByRangeCallback);
inputMethodController.off('selectByRange');

[h2]on('selectByMovement')10+

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

Enables listening for the select-by-cursor-movement event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type. The value is fixed at 'selectByMovement'.
callback Callback<Movement> Yes

Callback used to return the direction in which the cursor moves.

The application needs to select the text based on the direction returned in the callback.

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

inputMethod.getController().on('selectByMovement', (movement: inputMethod.Movement) => {
  console.info('Succeeded in subscribing selectByMovement: direction: ' + movement.direction);
});

[h2]off('selectByMovement')10+

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

Disables listening for the select-by-cursor-movement event. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type. The value is fixed at 'selectByMovement'.
callback Callback<Movement> No

Callback used to disable listening, which must be the same as that passed by the on API.

If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.

Example

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

let onSelectByMovementCallback: Callback<inputMethod.Movement> = (movement: inputMethod.Movement): void => {
  console.info(`Succeeded in subscribing selectByMovement, movement.direction: ${movement.direction}`);
};

let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();
inputMethodController.off('selectByMovement', onSelectByMovementCallback);
inputMethodController.off('selectByMovement');

[h2]on('getLeftTextOfCursor')10+

on(type: 'getLeftTextOfCursor', callback: (length: number) => string): void

Enables listening for the event of obtaining the length of text deleted leftward. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type. The value is fixed at 'getLeftTextOfCursor'.
callback (length: number) => string Yes Callback used to obtain the text of the specified length deleted leftward.

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.
12800009 input method client detached.

Example

inputMethod.getController().on('getLeftTextOfCursor', (length: number) => {
  console.info(`Succeeded in subscribing getLeftTextOfCursor, length: ${length}`);
  let text: string = "";
  return text;
});

[h2]off('getLeftTextOfCursor')10+

off(type: 'getLeftTextOfCursor', callback?: (length: number) => string): void

Disables listening for the event of obtaining the length of text deleted leftward. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type. The value is fixed at 'getLeftTextOfCursor'.
callback (length: number) => string No

Callback used to disable listening, which must be the same as that passed by the on API.

If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.

Example

let getLeftTextOfCursorCallback: (length: number) => string = (length: number): string => {
  console.info(`Succeeded in unsubscribing getLeftTextOfCursor, length: ${length}`);
  let text: string = "";
  return text;
};

let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();
inputMethodController.off('getLeftTextOfCursor', getLeftTextOfCursorCallback);
inputMethodController.off('getLeftTextOfCursor');

[h2]on('getRightTextOfCursor')10+

on(type: 'getRightTextOfCursor', callback: (length: number) => string): void

Enables listening for the event of obtaining the length of text deleted rightward. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type. The value is fixed at 'getRightTextOfCursor'.
callback (length: number) => string Yes Callback used to obtain the text of the specified length deleted rightward.

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.
12800009 input method client detached.

Example

inputMethod.getController().on('getRightTextOfCursor', (length: number) => {
  console.info(`Succeeded in subscribing getRightTextOfCursor, length: ${length}`);
  let text: string = "";
  return text;
});

[h2]off('getRightTextOfCursor')10+

off(type: 'getRightTextOfCursor', callback?: (length: number) => string): void

Disables listening for the event of obtaining the length of text deleted rightward. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type. The value is fixed at 'getRightTextOfCursor'.
callback (length: number) => string No

Callback used to disable listening, which must be the same as that passed by the on API.

If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.

Example

let getRightTextOfCursorCallback: (length: number) => string = (length: number): string => {
  console.info(`Succeeded in unsubscribing getRightTextOfCursor, length: ${length}`);
  let text: string = "";
  return text;
};

let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();
inputMethodController.off('getRightTextOfCursor', getRightTextOfCursorCallback);
inputMethodController.off('getRightTextOfCursor');

[h2]on('getTextIndexAtCursor')10+

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

Enables listening for the event of obtaining the index of text at the cursor. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type. The value is fixed at 'getTextIndexAtCursor'.
callback () => number Yes Callback used to obtain the index of text at 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.
12800009 input method client detached.

Example

inputMethod.getController().on('getTextIndexAtCursor', () => {
  console.info(`Succeeded in subscribing getTextIndexAtCursor.`);
  let index: number = 0;
  return index;
});

[h2]off('getTextIndexAtCursor')10+

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

Disables listening for the event of obtaining the index of text at the cursor. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type. The value is fixed at 'getTextIndexAtCursor'.
callback () => number No

Callback used to disable listening, which must be the same as that passed by the on API.

If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.

Example

let getTextIndexAtCursorCallback: () => number = (): number => {
  console.info(`Succeeded in unsubscribing getTextIndexAtCursor.`);
  let index: number = 0;
  return index;
};

let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();
inputMethodController.off('getTextIndexAtCursor', getTextIndexAtCursorCallback);
inputMethodController.off('getTextIndexAtCursor');

[h2]on('setPreviewText')17+

on(type: 'setPreviewText', callback: SetPreviewTextCallback): void

Subscribes to the event for text preview operations in an input method application. This API uses an asynchronous callback to return the result.

To use the text preview function, you need to subscribe to this event before calling attach and subscribe to this event together with on('finishTextPreview').

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'setPreviewText'.
callback SetPreviewTextCallback Yes Callback used to return the result. It is used to receive and return the text preview.

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 setPreviewTextCallback1: inputMethod.SetPreviewTextCallback = (text: string, range: inputMethod.Range): void => {
  console.info(`SetPreviewTextCallback1: Received text - ${text}, Received range - start: ${range.start}, end: ${range.end}`);
};

let setPreviewTextCallback2: inputMethod.SetPreviewTextCallback = (text: string, range: inputMethod.Range): void => {
  console.info(`setPreviewTextCallback2: Received text - ${text}, Received range - start: ${range.start}, end: ${range.end}`);
};

let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();
inputMethodController.on('setPreviewText', setPreviewTextCallback1);
console.info(`SetPreviewTextCallback1 subscribed to setPreviewText`);
inputMethodController.on('setPreviewText', setPreviewTextCallback2);
console.info(`SetPreviewTextCallback2 subscribed to setPreviewText`);
// Cancel only the callback1 of setPreviewText.
inputMethodController.off('setPreviewText', setPreviewTextCallback1);
console.info(`SetPreviewTextCallback1 unsubscribed from setPreviewText`);
// Cancel all callbacks of setPreviewText.
inputMethodController.off('setPreviewText');
console.info(`All callbacks unsubscribed from setPreviewText`);

[h2]off('setPreviewText')17+

off(type: 'setPreviewText', callback?: SetPreviewTextCallback): void

Unsubscribes from the event for text preview operations in an input method application. 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 'setPreviewText'.
callback SetPreviewTextCallback No

Callback used to disable listening, which must be the same as that passed by the on API.

If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.

Example

let setPreviewTextCallback1: inputMethod.SetPreviewTextCallback = (text: string, range: inputMethod.Range): void => {
  console.info(`SetPreviewTextCallback1: Received text - ${text}, Received range - start: ${range.start}, end: ${range.end}`);
};

let setPreviewTextCallback2: inputMethod.SetPreviewTextCallback = (text: string, range: inputMethod.Range): void => {
  console.info(`setPreviewTextCallback2: Received text - ${text}, Received range - start: ${range.start}, end: ${range.end}`);
};

let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();
inputMethodController.on('setPreviewText', setPreviewTextCallback1);
console.info(`SetPreviewTextCallback1 subscribed to setPreviewText`);
inputMethodController.on('setPreviewText', setPreviewTextCallback2);
console.info(`SetPreviewTextCallback2 subscribed to setPreviewText`);
// Cancel only the callback1 of setPreviewText.
inputMethodController.off('setPreviewText', setPreviewTextCallback1);
console.info(`SetPreviewTextCallback1 unsubscribed from setPreviewText`);
// Cancel all callbacks of setPreviewText.
inputMethodController.off('setPreviewText');
console.info(`All callbacks unsubscribed from setPreviewText`);

[h2]on('finishTextPreview')17+

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

Subscribes to the event of finishing text preview. This API uses an asynchronous callback to return the result.

To use the text preview function, you need to subscribe to this event before calling attach and subscribe to this event together with on('setPreviewText').

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
type string Yes Event type, which is 'finishTextPreview'.
callback Callback<void> Yes Callback used to return the result. It is used to process the logic of finishing text preview. Return type: void

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 { Callback } from '@kit.BasicServicesKit';

let finishTextPreviewCallback1: Callback<void> = (): void => {
  console.info(`FinishTextPreviewCallback1: finishTextPreview event triggered`);
};
let finishTextPreviewCallback2: Callback<void> = (): void => {
  console.info(`FinishTextPreviewCallback2: finishTextPreview event triggered`);
};

let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();
inputMethodController.on('finishTextPreview', finishTextPreviewCallback1);
console.info(`FinishTextPreviewCallback1 subscribed to finishTextPreview`);
inputMethodController.on('finishTextPreview', finishTextPreviewCallback2);
console.info(`FinishTextPreviewCallback2 subscribed to finishTextPreview`);
// Cancel only the callback1 of finishTextPreview.
inputMethodController.off('finishTextPreview', finishTextPreviewCallback1);
console.info(`FinishTextPreviewCallback1 unsubscribed from finishTextPreview`);
// Cancel all callbacks of finishTextPreview.
inputMethodController.off('finishTextPreview');
console.info(`All callbacks unsubscribed from finishTextPreview`);

[h2]off('finishTextPreview')17+

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

Unsubscribes from the event of finishing text preview. 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 'finishTextPreview'.
callback Callback<void> No

Callback used to disable listening, which must be the same as that passed by the on API.

If this parameter is not specified, listening will be disabled for all callbacks corresponding to the specified type.

Example

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

let finishTextPreviewCallback1: Callback<void> = (): void => {
  console.info(`FinishTextPreviewCallback1: finishTextPreview event triggered`);
};
let finishTextPreviewCallback2: Callback<void> = (): void => {
  console.info(`FinishTextPreviewCallback2: finishTextPreview event triggered`);
};

let inputMethodController: inputMethod.InputMethodController = inputMethod.getController();
inputMethodController.on('finishTextPreview', finishTextPreviewCallback1);
console.info(`FinishTextPreviewCallback1 subscribed to finishTextPreview`);
inputMethodController.on('finishTextPreview', finishTextPreviewCallback2);
console.info(`FinishTextPreviewCallback2 subscribed to finishTextPreview`);
// Cancel only the callback1 of finishTextPreview.
inputMethodController.off('finishTextPreview', finishTextPreviewCallback1);
console.info(`FinishTextPreviewCallback1 unsubscribed from finishTextPreview`);
// Cancel all callbacks of finishTextPreview.
inputMethodController.off('finishTextPreview');
console.info(`All callbacks unsubscribed from finishTextPreview`);

InputMethodSetting8+

InputMethodSetting provides input method configuration and query capabilities, and offers the following features for foreground applications:

It must be used after you obtain the InputMethodSetting instance through getSetting.

For the following APIs, you must first use getSetting to obtain an InputMethodSetting instance, and then call the APIs using the obtained instance.

[h2]on('imeChange')9+

on(type: 'imeChange', callback: (inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => void): void

Enables listening for the input method and subtype 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 Listening type. The value is fixed at 'imeChange'.
callback (inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => void Yes Callback used to return the input method attributes and subtype.

Example

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

inputMethod.getSetting()
  .on('imeChange', (inputMethodProperty: inputMethod.InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => {
    console.info(`Succeeded in subscribing imeChange: inputMethodProperty.name: ${inputMethodProperty.name} ` +
      `, inputMethodSubtype.id: ${inputMethodSubtype.id}`);
  });

[h2]off('imeChange')9+

off(type: 'imeChange', callback?: (inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => void): void

Disables listening for the input method and subtype 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 Listening type. The value is fixed at 'imeChange'.
callback (inputMethodProperty: InputMethodProperty, inputMethodSubtype: InputMethodSubtype) => void No Callback used to return the input method attributes and subtype.

Example

inputMethod.getSetting().off('imeChange');

[h2]listInputMethodSubtype9+

listInputMethodSubtype(inputMethodProperty: InputMethodProperty, callback: AsyncCallback<Array<InputMethodSubtype>>): void

Obtains all subtypes of a specified input method. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
inputMethodProperty InputMethodProperty Yes Input method.
callback AsyncCallback<Array<InputMethodSubtype>> Yes Callback used to return all subtypes of the specified input method.

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.
12800001 bundle manager error.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

let inputMethodProperty: inputMethod.InputMethodProperty = {
  name: 'com.example.keyboard',
  id: 'propertyId',
  packageName: 'com.example.keyboard',
  methodId: 'propertyId'
}
let inputMethodSetting: inputMethod.InputMethodSetting = inputMethod.getSetting();

inputMethodSetting.listInputMethodSubtype(inputMethodProperty,
  (err: BusinessError, data: Array<InputMethodSubtype>) => {
    if (err) {
      console.error(`Failed to listInputMethodSubtype, code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info('Succeeded in listing inputMethodSubtype.');
  });

[h2]listInputMethodSubtype9+

listInputMethodSubtype(inputMethodProperty: InputMethodProperty): Promise<Array<InputMethodSubtype>>

Obtains all subtypes of a specified input method. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
inputMethodProperty InputMethodProperty Yes Input method.

Return value

Type Description
Promise<Array<InputMethodSubtype>> Promise object, which returns all subtypes of the specified input method application.

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.
12800001 bundle manager error.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

let inputMethodProperty: inputMethod.InputMethodProperty = {
  name: 'com.example.keyboard',
  id: 'propertyId',
  packageName: 'com.example.keyboard',
  methodId: 'propertyId'
}
let inputMethodSetting: inputMethod.InputMethodSetting = inputMethod.getSetting();

inputMethodSetting.listInputMethodSubtype(inputMethodProperty).then((data: Array<InputMethodSubtype>) => {
  console.info('Succeeded in listing inputMethodSubtype.');
}).catch((err: BusinessError) => {
  console.error(`Failed to listInputMethodSubtype, code: ${err.code}, message: ${err.message}`);
})

[h2]listCurrentInputMethodSubtype9+

listCurrentInputMethodSubtype(callback: AsyncCallback<Array<InputMethodSubtype>>): void

Obtains all subtypes of this input method. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
callback AsyncCallback<Array<InputMethodSubtype>> Yes Callback used to return all subtypes of the current input method.

Error codes

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

ID Error Message
12800001 bundle manager error.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

let inputMethodSetting: inputMethod.InputMethodSetting = inputMethod.getSetting();
inputMethodSetting.listCurrentInputMethodSubtype((err: BusinessError, data: Array<InputMethodSubtype>) => {
  if (err) {
    console.error(`Failed to listCurrentInputMethodSubtype, code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in listing currentInputMethodSubtype.');
});

[h2]listCurrentInputMethodSubtype9+

listCurrentInputMethodSubtype(): Promise<Array<InputMethodSubtype>>

Obtains all subtypes of this input method. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
Promise<Array<InputMethodSubtype>> Promise object, which returns all subtypes of the current input method application.

Error codes

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

ID Error Message
12800001 bundle manager error.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

let inputMethodSetting: inputMethod.InputMethodSetting = inputMethod.getSetting();

inputMethodSetting.listCurrentInputMethodSubtype().then((data: Array<InputMethodSubtype>) => {
  console.info('Succeeded in listing currentInputMethodSubtype.');
}).catch((err: BusinessError) => {
  console.error(`Failed to listCurrentInputMethodSubtype, code: ${err.code}, message: ${err.message}`);
})

[h2]getInputMethods9+

getInputMethods(enable: boolean, callback: AsyncCallback<Array<InputMethodProperty>>): void

Obtains a list of activated or deactivated input methods. This API uses an asynchronous callback to return the result.

An activated input method refers to an input method that is enabled. The default input method is enabled by default. Other input methods can be enabled or disabled as needed.

The list of activated input methods includes the default input method and enabled input methods. The list of deactivated input methods includes all installed input methods except the enabled ones.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
enable boolean Yes Whether to return a list of activated input methods. The value true means to return a list of activated input methods, and false means to return a list of deactivated input methods.
callback AsyncCallback<Array<InputMethodProperty>> Yes Callback used to return a list of activated or deactivated input methods.

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.
12800001 bundle manager error.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

inputMethod.getSetting().getInputMethods(true, (err: BusinessError, data: Array<inputMethod.InputMethodProperty>) => {
  if (err) {
    console.error(`Failed to getInputMethods, code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in getting inputMethods.');
});

[h2]getInputMethods9+

getInputMethods(enable: boolean): Promise<Array<InputMethodProperty>>

Obtains a list of activated or deactivated input methods. This API uses a promise to return the result.

An activated input method refers to an input method that is enabled. The default input method is enabled by default. Other input methods can be enabled or disabled as needed.

The list of activated input methods includes the default input method and enabled input methods. The list of deactivated input methods includes all installed input methods except the enabled ones.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
enable boolean Yes Whether to return a list of activated input methods. The value true means to return a list of activated input methods, and false means to return a list of deactivated input methods.

Return value

Type Description
Promise<Array<InputMethodProperty>> Promise object, returns the list of activated/inactivated input methods.

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.
12800001 bundle manager error.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

inputMethod.getSetting().getInputMethods(true).then((data: Array<inputMethod.InputMethodProperty>) => {
  console.info('Succeeded in getting inputMethods.');
}).catch((err: BusinessError) => {
  console.error(`Failed to getInputMethods, code: ${err.code}, message: ${err.message}`);
})

[h2]getInputMethodsSync11+

getInputMethodsSync(enable: boolean): Array<InputMethodProperty>

Obtains a list of activated or deactivated input methods. This API returns the result synchronously.

The synchronous API blocks the main thread and may easily affect UI interaction. Use it with caution.

Enabled input methods are input method applications that are enabled. The default input method is enabled by default, and other input methods can be set to enabled or disabled.

The enabled input method list includes the default input method and input method applications that have been set to enabled. The disabled input method list includes other installed input methods except the enabled input methods.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
enable boolean Yes Whether to return a list of activated input methods. The value true means to return a list of activated input methods, and false means to return a list of deactivated input methods.

Return value

Type Description
Array<InputMethodProperty> List of activated or deactivated input methods.

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.
12800001 bundle manager error.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

let imeProperty: Array<inputMethod.InputMethodProperty> = inputMethod.getSetting().getInputMethodsSync(true);

[h2]getAllInputMethods11+

getAllInputMethods(callback: AsyncCallback<Array<InputMethodProperty>>): void

Obtains a list of all input methods. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
callback AsyncCallback<Array<InputMethodProperty>> Yes Callback used to return a list of all input methods.

Error codes

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

ID Error Message
12800001 bundle manager error.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

inputMethod.getSetting().getAllInputMethods((err: BusinessError, data: Array<inputMethod.InputMethodProperty>) => {
  if (err) {
    console.error(`Failed to getAllInputMethods, code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in getting all inputMethods.');
});

[h2]getAllInputMethods11+

getAllInputMethods(): Promise<Array<InputMethodProperty>>

Obtains a list of all input methods. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
Promise<Array<InputMethodProperty>> Promise object, returns the list of all input methods.

Error codes

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

ID Error Message
12800001 bundle manager error.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

inputMethod.getSetting().getAllInputMethods().then((data: Array<inputMethod.InputMethodProperty>) => {
  console.info('Succeeded in getting all inputMethods.');
}).catch((err: BusinessError) => {
  console.error(`Failed to getAllInputMethods, code: ${err.code}, message: ${err.message}`);
})

[h2]getAllInputMethodsSync11+

getAllInputMethodsSync(): Array<InputMethodProperty>

Obtains a list of all input methods. This API returns the result synchronously.

The synchronous API blocks the main thread and may easily affect UI interaction. Use it with caution.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
Array<InputMethodProperty> List of all input methods.

Error codes

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

ID Error Message
12800001 bundle manager error.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

let imeProperty: Array<inputMethod.InputMethodProperty> = inputMethod.getSetting().getAllInputMethodsSync();

[h2]showOptionalInputMethods(deprecated)

showOptionalInputMethods(callback: AsyncCallback<boolean>): void

Displays a dialog box for selecting an input method. This API uses an asynchronous callback to return the result.

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

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
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.

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

Example

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

inputMethod.getSetting().showOptionalInputMethods((err: BusinessError, result: boolean) => {
  if (err) {
    console.error(`Failed to showOptionalInputMethods, code: ${err.code}, message: ${err.message}`);
    return;
  }
  if (result) {
    console.info('Succeeded in showing optionalInputMethods.');
  } else {
    console.error(`Failed to showOptionalInputMethods.`);
  }
});

[h2]showOptionalInputMethods(deprecated)

showOptionalInputMethods(): Promise<boolean>

Displays a dialog box for selecting an input method. This API uses a promise to return the result.

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

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
Promise<boolean> Promise object. Returns true if the input method selection dialog is displayed successfully, and false otherwise.

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.

Example

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

inputMethod.getSetting().showOptionalInputMethods().then((result: boolean) => {
  if (result) {
    console.info('Succeeded in showing optionalInputMethods.');
  } else {
    console.error(`Failed to showOptionalInputMethods.`);
  }
}).catch((err: BusinessError) => {
  console.error(`Failed to showOptionalInputMethods, code: ${err.code}, message: ${err.message}`);
})

[h2]listInputMethod(deprecated)

listInputMethod(callback: AsyncCallback<Array<InputMethodProperty>>): void

Obtains a list of installed input methods. This API uses an asynchronous callback to return the result.

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

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name Type Mandatory Description
callback AsyncCallback<Array<InputMethodProperty>> Yes Callback used to return the list of installed input methods.

Example

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

inputMethod.getSetting().listInputMethod((err: BusinessError, data: Array<inputMethod.InputMethodProperty>) => {
  if (err) {
    console.error(`Failed to listInputMethod, code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in listing inputMethod.');
});

[h2]listInputMethod(deprecated)

listInputMethod(): Promise<Array<InputMethodProperty>>

Obtains a list of installed input methods. This API uses a promise to return the result.

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

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
Promise<Array<InputMethodProperty>> Promise object, which returns the list of installed input methods.

Example

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

inputMethod.getSetting().listInputMethod().then((data: Array<inputMethod.InputMethodProperty>) => {
  console.info('Succeeded in listing inputMethod.');
}).catch((err: BusinessError) => {
  console.error(`Failed to listInputMethod, code: ${err.code}, message: ${err.message}`);
})

[h2]displayOptionalInputMethod(deprecated)

displayOptionalInputMethod(callback: AsyncCallback<void>): void

Displays a dialog box for selecting an input method. This API uses an asynchronous callback to return the result.

This API is supported since API version 8 and deprecated since API version 9. You are advised to use InputMethodListDialog 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';

inputMethod.getSetting().displayOptionalInputMethod((err: BusinessError) => {
  if (err) {
    console.error(`Failed to displayOptionalInputMethod, code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info('Succeeded in displaying optionalInputMethod.');
});

[h2]displayOptionalInputMethod(deprecated)

displayOptionalInputMethod(): Promise<void>

Displays a dialog box for selecting an input method. This API uses a promise to return the result.

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

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

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

Example

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

inputMethod.getSetting().displayOptionalInputMethod().then(() => {
  console.info('Succeeded in displaying optionalInputMethod.');
}).catch((err: BusinessError) => {
  console.error(`Failed to displayOptionalInputMethod, code: ${err.code}, message: ${err.message}`);
})

[h2]getInputMethodState15+

getInputMethodState(): Promise<EnabledState>

Obtains the input method state. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type Description
Promise<EnabledState> Promise object. Returns EnabledState.DISABLED if the input method is not enabled; returns EnabledState.BASIC_MODE if in basic mode; returns EnabledState.FULL_EXPERIENCE_MODE if in full experience mode.

Error codes

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

ID Error Message
12800004 not an input method application.
12800008 input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

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

inputMethod.getSetting().getInputMethodState().then((status: inputMethod.EnabledState) => {
  console.info(`Succeeded in getInputMethodState, status: ${status}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to getInputMethodState, code: ${err.code}, message: ${err.message}`);
});