@ohos.inputMethod (Input Method Framework) (System API)

The inputMethod module is oriented to common foreground applications (system applications such as Notes, Messaging, and Settings). It provides input method control and management capabilities, including displaying or hiding the soft keyboard, switching between input methods, and obtaining the list of all input methods.

NOTE

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

Modules to Import

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

inputMethod.switchInputMethod¹¹⁺

switchInputMethod(bundleName: string, subtypeId?: string): Promise<void>

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

Required permissions: ohos.permission.CONNECT_IME_ABILITY

System capability: SystemCapability.MiscServices.InputMethodFramework

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name of the target input method.
subtypeId	string	No	Input method subtype.

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.
202	not system application.
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';

async function switchInputMethodWithSubtype() {
  // 1. Obtain the current input method.
  const currentIme: inputMethod.InputMethodProperty = inputMethod.getCurrentInputMethod();
  if (!currentIme) {
    console.error("Failed to get current input method");
    return;
  }
  // 2. Switch the input method.
  await inputMethod.switchInputMethod(currentIme.name);
  console.info('Succeeded in switching inputmethod.');
  // 3. Obtain the current input method subtype.
  const currentSubtype: InputMethodSubtype = inputMethod.getCurrentInputMethodSubtype();
  if (!currentSubtype) {
    console.error("Failed to get current input subtype");
    return;
  }
  // 4. Switch the input method subtype.
  await inputMethod.switchInputMethod(currentIme.name, currentSubtype.id);
  console.info('Succeeded in switching inputmethod.');
}

switchInputMethodWithSubtype();

InputMethodSetting

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

on('imeShow')¹⁰⁺

on(type: 'imeShow', callback: (info: Array<InputWindowInfo>) => void): void

Subscribes to the soft keyboard show event of the input method panel in the fixed state. This API uses an asynchronous callback to return the result.

System API: This is a system API.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'imeShow'.
callback	(info: Array<InputWindowInfo>) => void	Yes	Callback used to return the soft keyboard information of the input method panel in the fixed state.

Error codes

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

ID	Error Message
202	not system application.

Example

inputMethod.getSetting().on('imeShow', (info: Array<inputMethod.InputWindowInfo>) => {
  console.info('Succeeded in subscribing imeShow event.');
});

on('imeHide')¹⁰⁺

on(type: 'imeHide', callback: (info: Array<InputWindowInfo>) => void): void

Subscribes to the soft keyboard hide event of the input method panel in the fixed state. This API uses an asynchronous callback to return the result.

System API: This is a system API.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'imeHide'.
callback	(info: Array<InputWindowInfo>) => void	Yes	Callback used to return the soft keyboard information of the input method panel in the fixed state.

Error codes

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

ID	Error Message
202	not system application.

Example

inputMethod.getSetting().on('imeHide', (info: Array<inputMethod.InputWindowInfo>) => {
  console.info('Succeeded in subscribing imeHide event.');
});

off('imeShow')¹⁰⁺

off(type: 'imeShow', callback?: (info: Array<InputWindowInfo>) => void): void

Unsubscribes from the soft keyboard show event of the input method panel in the fixed state.

System API: This is a system API.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

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

Example

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

off('imeHide')¹⁰⁺

off(type: 'imeHide', callback?: (info: Array<InputWindowInfo>) => void): void

Unsubscribes from the soft keyboard hide event of the input method panel in the fixed state.

System API: This is a system API.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

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

Example

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

isPanelShown¹¹⁺

isPanelShown(panelInfo: PanelInfo): boolean

Checks whether the input method panel of a specified type is shown.

System API: This is a system API.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
panelInfo	PanelInfo	Yes	Information about the input method panel.

Return value

Type	Description
boolean	Whether the input method panel is shown. - The value true means that the input method panel is shown. - The value false means that the input method panel is hidden.

Error codes

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

ID	Error Message
202	not system application.
401	parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
12800008	input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.

Example

import { PanelInfo, PanelType, PanelFlag } from '@kit.IMEKit';

let info: PanelInfo = {
  type: PanelType.SOFT_KEYBOARD,
  flag: PanelFlag.FLAG_FIXED
}

let result: boolean = inputMethod.getSetting().isPanelShown(info);
console.info('Succeeded in querying isPanelShown, result: ' + result);

isPanelShown²³⁺

isPanelShown(panelInfo: PanelInfo, displayId: number): boolean

Checks whether the input method panel of a specified type is shown on a specified screen.

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

System API: This is a system API.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
panelInfo	PanelInfo	Yes	Information about the input method panel.
displayId	number	Yes	Display ID.

Return value

Type	Description
boolean	Whether the input method panel is shown. - The value true means that the input method panel is shown. - The value false means that the input method panel is hidden.

Error codes

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

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

Example

import { PanelInfo, PanelType, PanelFlag } from '@kit.IMEKit';

let displayId: number = 10;
let info: PanelInfo = {
  type: PanelType.SOFT_KEYBOARD,
  flag: PanelFlag.FLAG_FIXED
}

let result: boolean = inputMethod.getSetting().isPanelShown(info, displayId);
console.info('Succeeded in querying isPanelShown, result: ' + result);

enableInputMethod²⁰⁺

enableInputMethod(bundleName: string, extensionName: string, enabledState: EnabledState): Promise<void>

Enables or disables an input method. This API uses a promise to return the result.

Required permissions: ohos.permission.CONNECT_IME_ABILITY

System capability: SystemCapability.MiscServices.InputMethodFramework

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name of the input method.
extensionName	string	Yes	Extension name of the input method.
enabledState	EnabledState	Yes	Whether the input method is enabled.

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.
202	not system application.
12800008	input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.
12800018	the input method is not found.
12800019	current operation cannot be applied to the preconfigured default input method.

Example

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

function enableInputMethodSafely() {
  const currentIme: inputMethod.InputMethodProperty = inputMethod.getCurrentInputMethod();
  if (!currentIme) {
    console.error("Failed to get current input method");
    return;
  }

  inputMethod.getSetting()
    .enableInputMethod(currentIme.name, currentIme.id, inputMethod.EnabledState.BASIC_MODE)
    .then(() => {
      console.info('Succeeded in enable inputmethod.');
    })
    .catch((err: BusinessError) => {
      console.error(`Failed to enableInputMethod. Code: ${err.code}, message: ${err.message}`);
    });
}

enableInputMethodSafely();

getCursorInfo

getCursorInfo(userId?: number): CursorInfo

Obtains the cursor information of a specified user. If the edit box does not notify the input method service of the cursor information, all attribute values returned are 0.

Since: 26.0.0

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

System API: This is a system API.

System capability: SystemCapability.MiscServices.InputMethodFramework

Parameters

Name	Type	Mandatory	Description
userId	number	No	User ID. If the caller is not an application of user 0, the value of this parameter is the user ID of the caller by default. If the caller is an application of user 0, the value of this parameter is the foreground user ID of the main screen.

Return value

Type	Description
CursorInfo	Cursor information of the specified user.

Error codes

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

ID	Error Message
202	not system application.
12800003	input method client error. Possible causes:1. No edit box is bound to the current input method application under the specified user.
12800008	input method manager service error. Possible cause: a system error, such as null pointer, IPC exception.
12800023	the specified user does not exist.
12800024	the specified user is not in the foreground.
12800025	cross-user operation denied. Only user 0 applications are authorized for this operation.

Example

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

try {
  let cursorInfo: inputMethod.CursorInfo = inputMethod.getSetting().getCursorInfo();
  console.info(`get cursorInfo success, left: ${cursorInfo.left}, top: ${cursorInfo.top}, width: ${cursorInfo.width}, height: ${cursorInfo.height}, displayId: ${cursorInfo.displayId}`);
} catch (err) {
  let error = err as BusinessError;
  console.error(`Failed to get cursorInfo. Code: ${error.code}, message: ${error.message}`);
}

getDefaultInputMethodAbility

getDefaultInputMethodAbility(): InputMethodProperty

Obtains the default input method capabilities. To optimize performance, the returned InputMethodProperty object ensures that only the name and id attributes that uniquely identify the input method capability are correct. Other attributes may be empty.

Since: 26.0.0

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

System API: This is a system API.

System capability: SystemCapability.MiscServices.InputMethodFramework

Return value

Type	Description
InputMethodProperty	Default input method attributes. Only the name and id attributes are guaranteed to be correct. Other attributes may be empty.

Error codes

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

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

Example

try {
  const defaultAbility: inputMethod.InputMethodProperty = inputMethod.getSetting().getDefaultInputMethodAbility();
  console.info('Succeeded in getting default input method ability, name: ' + defaultAbility.name + ', id: ' + defaultAbility.id);
} catch (err) {
  console.error(`Failed to getDefaultInputMethodAbility. Code: ${err.code}, message: ${err.message}`);
}

InputMethodController

A control class that encapsulates APIs for input method management, which can only be invoked after an InputMethodController instance is obtained via getController.

showSoftKeyboard²³⁺

showSoftKeyboard(displayId: number): Promise<void>

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

NOTE

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

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

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

System capability: SystemCapability.MiscServices.InputMethodFramework

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
displayId	number	Yes	Display ID.

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.
202	not system application.
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 displayId: number = 20;
inputMethod.getController().showSoftKeyboard(displayId).then(() => {
  console.info('Succeeded in showing softKeyboard.');
}).catch((err: BusinessError) => {
  console.error(`Failed to show softKeyboard, code: ${err.code}, message: ${err.message}`);
});

hideSoftKeyboard²³⁺

hideSoftKeyboard(displayId: number): Promise<void>

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

NOTE

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

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

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

System capability: SystemCapability.MiscServices.InputMethodFramework

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
displayId	number	Yes	Display ID.

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.
202	not system application.
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 displayId: number = 30;
inputMethod.getController().hideSoftKeyboard(displayId).then(() => {
  console.info('Succeeded in hiding softKeyboard.');
}).catch((err: BusinessError) => {
  console.error(`Failed to hide softKeyboard, code: ${err.code}, message: ${err.message}`);
});