This module provides word selection management capabilities, including creating, displaying, moving, hiding, and destroying panels, listening for word selection events using a mouse or touchpad, and retrieving the selected text. The typical usage process is as follows:
- Call on('selectionCompleted') to subscribe to the selection completion event.
- In the callback, call getSelectionContent to obtain the selected text.
- Call createPanel to create a word selection panel.
- Call setUiContent to load the page content.
- Call moveToGlobalDisplay to move the panel to a specified position.
- Call show to display the panel.
- Call show to display the panel.
- Call off('selectionCompleted') to unsubscribe from the selection completion event.
- The initial APIs of this module are supported since API version 24. Newly added APIs will be marked with a superscript to indicate their earliest API version.
- This module is supported only on PCs/2-in-1 devices. You can use canIUse('SystemCapability.SelectionInput.Selection') to check whether the current device supports this function.
- APIs of this module can be called only by apps that integrate the extension ability for word selection. For details about how to implement the extension ability for word selection, see SelectionExtensionAbility.
selectionManager
System capability: SystemCapability.SelectionInput.Selection
Model restriction: This API can be used only in the stage model.
[h2]selectionManager.on('selectionCompleted')
on(type: 'selectionCompleted', callback: Callback<SelectionInfo>): void
Subscribes to the word selection completion event. This API is used together with off('selectionCompleted'). off('selectionCompleted') is used to unsubscribe from the event.
System capability: SystemCapability.SelectionInput.Selection
Model restriction: This API can be used only in the stage model.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| type | string | Yes | Event type, which is 'selectionCompleted'. |
| callback | Callback<SelectionInfo> | Yes | Callback used to return SelectionInfo. This callback is triggered only when the user selects text using the mouse or touchpad (by double-clicking, triple-clicking, or sliding the left mouse button) and then presses Ctrl. |
Error codes
For details about the following error codes, see Word Selection Error Codes. For details about other common error codes, see Universal Error Codes.
| ID | Error Message |
|---|---|
| 33600003 | The application calling the API does not match the application selected in the system settings. |
Example
import { selectionManager } from '@kit.BasicServicesKit';
try {
// Subscribe to the word selection completion event.
selectionManager.on('selectionCompleted', (info: selectionManager.SelectionInfo) => {
console.info('Enter the callback function.');
});
} catch (err) {
console.error(`Failed to register selectionCompleted callback. Error code: ${err.code}, error message: ${err.message}`);
} [h2]selectionManager.off('selectionCompleted')
off(type: 'selectionCompleted', callback?: Callback<SelectionInfo>): void
Unsubscribes from the word selection completion event. This method is used together with on('selectionCompleted').
System capability: SystemCapability.SelectionInput.Selection
Model restriction: This API can be used only in the stage model.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| type | string | Yes | Type of the event to unsubscribe from. The value is fixed to 'selectionCompleted'. |
| callback | Callback<SelectionInfo> | No | Callback to be unregistered (that is, the callback instance registered using on). If this parameter is not specified, this API unregisters all callbacks for the specified type. |
Example
import { selectionManager } from '@kit.BasicServicesKit';
// Define a callback used to listen for the word selection completion event, which will be registered and unregistered.
let selectionChangeCallback = (info: selectionManager.SelectionInfo) => {
console.info('Enter the callback function.');
};
// Register a callback used to listen for the word selection completion event, preparing for subsequent unsubscription.
selectionManager.on('selectionCompleted', selectionChangeCallback);
try {
// Unsubscribe from the word selection completion event.
selectionManager.off('selectionCompleted', selectionChangeCallback);
} catch (err) {
console.error(`Failed to unregister selectionCompleted. Error code: ${err.code}, error message: ${err.message}`);
} [h2]getSelectionContent()
getSelectionContent(): Promise<string>
Obtains the content of the selected text. This API uses a promise to return the result. This API must be called in the on('selectionCompleted') callback and is valid only after the word selection completion event is triggered.
System capability: SystemCapability.SelectionInput.Selection
Model restriction: This API can be used only in the stage model.
Return value
| Type | Description |
|---|---|
| Promise<string> | Promise used to return the content of the selected text. |
Error codes
For details about the following error codes, see Word Selection Error Codes. For details about other common error codes, see Universal Error Codes.
| ID | Error Message |
|---|---|
| 33600001 | Selection service invocation exception. |
| 33600004 | The interface is called too frequently. |
| 33600005 | The interface is called at the wrong time. |
| 33600006 | The current application is prohibited from accessing content. |
| 33600007 | The length of selected content is out of range. |
| 33600008 | Getting the selected content times out. |
Example
import { selectionManager } from '@kit.BasicServicesKit';
// Subscribe to the word selection completion event and obtain the selected text in the callback.
selectionManager.on('selectionCompleted', async (info: selectionManager.SelectionInfo) => {
try {
// Obtain the content of the selected text.
let content = await selectionManager.getSelectionContent();
console.info(`Succeeded in getting selection content: ${content}`);
} catch (err) {
console.error(`Failed to get selection content. Error code: ${err.code}, error message: ${err.message}`);
}
}); [h2]createPanel
createPanel(ctx: Context, info: PanelInfo): Promise<Panel>
Creates a word selection panel, which is used to display the service-related operation UI or text processing result. After the panel is used, call destroyPanel to destroy the panel and release resources. This API uses a promise to return the result.
Only one MENU_PANEL and one MAIN_PANEL can be created for one word selection application.
System capability: SystemCapability.SelectionInput.Selection
Model restriction: This API can be used only in the stage model.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| ctx | Context | Yes | Context that the current word selection panel depends on, which is provided by SelectionExtensionAbility. |
| info | PanelInfo | Yes | Configuration information of the word selection panel, which is used to specify the panel type, position, width, and height. Only one MENU_PANEL and one MAIN_PANEL can be created for one word selection app. |
Return value
| Type | Description |
|---|---|
| Promise<Panel> | Promise used to return the Panel object created, which can be used to set, display, hide, and move the panel, and subscribe to events. |
Error codes
For details about the following error codes, see Word Selection Error Codes. For details about other common error codes, see Universal Error Codes.
| ID | Error Message |
|---|---|
| 33600001 | Selection service exception. |
| 33600003 | The application calling the API does not match the application selected in the system settings. |
Example
import { selectionManager, SelectionExtensionAbility, PanelInfo, PanelType, BusinessError } from '@kit.BasicServicesKit';
import { rpc } from '@kit.IPCKit';
import { Want } from '@kit.AbilityKit';
class SelectionAbilityStub extends rpc.RemoteObject {
constructor(descriptor: string) {
super(descriptor);
}
onRemoteMessageRequest(
code: number,
data: rpc.MessageSequence,
reply: rpc.MessageSequence,
options: rpc.MessageOption
): boolean | Promise<boolean> {
return true;
}
}
class ServiceExtAbility extends SelectionExtensionAbility {
onConnect(want: Want): rpc.RemoteObject {
// Configure the word selection panel, including the panel type, position, and size.
let panelInfo: PanelInfo = {
panelType: PanelType.MENU_PANEL,
x: 0,
y: 0,
width: 500,
height: 200
};
let selectionPanel: selectionManager.Panel | undefined = undefined;
// Create a word selection panel. Obtain this.context by inheriting SelectionExtensionAbility.
selectionManager.createPanel(this.context, panelInfo)
.then((panel: selectionManager.Panel) => {
selectionPanel = panel;
console.info('Succeed in creating panel.');
}).catch((err: BusinessError) => {
console.error(`Failed to create panel. Error code: ${err.code}, error message: ${err.message}`);
});
return new SelectionAbilityStub('remote');
}
}
export default ServiceExtAbility; [h2]destroyPanel
destroyPanel(panel: Panel): Promise<void>
Destroys the word selection panel. This API is used together with createPanel to destroy the panel object created by createPanel(). This API uses a promise to return the result.
System capability: SystemCapability.SelectionInput.Selection
Model restriction: This API can be used only in the stage model.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| panel | Panel | Yes | Word selection panel to destroy. |
Return value
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
Error codes
For details about the following error codes, see Word Selection Error Codes. For details about other common error codes, see Universal Error Codes.
| ID | Error Message |
|---|---|
| 33600001 | Selection service exception. |
Example
import { selectionManager, SelectionExtensionAbility, PanelInfo, PanelType, BusinessError } from '@kit.BasicServicesKit';
import { rpc } from '@kit.IPCKit';
import { Want } from '@kit.AbilityKit';
class SelectionAbilityStub extends rpc.RemoteObject {
constructor(descriptor: string) {
super(descriptor);
}
onRemoteMessageRequest(
code: number,
data: rpc.MessageSequence,
reply: rpc.MessageSequence,
options: rpc.MessageOption
): boolean | Promise<boolean> {
return true;
}
}
class ServiceExtAbility extends SelectionExtensionAbility {
onConnect(want: Want): rpc.RemoteObject {
// Configure the word selection panel, including the panel type, position, and size.
let panelInfo: PanelInfo = {
panelType: PanelType.MENU_PANEL,
x: 0,
y: 0,
width: 500,
height: 200
};
let selectionPanel: selectionManager.Panel | undefined = undefined;
// Create a word selection panel first. Obtain a Panel instance to be destroyed later. Obtain this.context by inheriting SelectionExtensionAbility.
selectionManager.createPanel(this.context, panelInfo)
.then((panel: selectionManager.Panel) => {
console.info('Succeed in creating panel.');
selectionPanel = panel;
try {
if (selectionPanel) {
// Destroy the word selection panel.
selectionManager.destroyPanel(selectionPanel).then(() => {
console.info('Succeed in destroying panel.');
}).catch((err: BusinessError) => {
console.error(`Failed to destroy panel. Error code: ${err.code}, error message: ${err.message}`);
});
}
} catch (err) {
console.error(`Failed to destroy panel. Error code: ${err.code}, error message: ${err.message}`);
}
}).catch((err: BusinessError) => {
console.error(`Failed to create panel. Error code: ${err.code}, error message: ${err.message}`);
});
return new SelectionAbilityStub('remote');
}
}
export default ServiceExtAbility; SelectionInfo
Defines the information of a word selection event.
System capability: SystemCapability.SelectionInput.Selection
Model restriction: This API can be used only in the stage model.
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| selectionType | SelectionType | No | No | Word selection types. |
| startDisplayX | number | No | No | X-coordinate of the screen where the word selection starts, in px. |
| startDisplayY | number | No | No | Y-coordinate of the screen where the word selection starts, in px. |
| endDisplayX | number | No | No | X-coordinate of the screen where the word selection ends, in px. |
| endDisplayY | number | No | No | Y-coordinate of the screen where the word selection ends, in px. |
| startWindowX | number | No | No | X-coordinate of the window where the word selection starts, in px. |
| startWindowY | number | No | No | Y-coordinate of the window where the word selection starts, in px. |
| endWindowX | number | No | No | X-coordinate of the window where the word selection ends, in px. |
| endWindowY | number | No | No | Y-coordinate of the window where the word selection ends, in px. |
| displayID | number | No | No | ID of the screen where the window with selected words is located. |
| windowID | number | No | No | ID of the window where words are selected. |
| bundleName | string | No | No | Bundle name of the application where words are selected. |
Panel
Describes a Panel object, which is created using createPanel. This method can be used to set, display, hide, and move the panel, as well as subscribe to events. It is applicable to scenarios where a custom operation UI needs to be displayed to users after word selection is complete.
System capability: SystemCapability.SelectionInput.Selection
Model restriction: This API can be used only in the stage model.
In the following APIs, you must first use createPanel to obtain a Panel instance, and then call the APIs using the obtained instance.
[h2]setUiContent
setUiContent(path: string): Promise<void>
Sets the UI content for the current word selection panel, for example, to display translation results, search suggestions, or custom action buttons. This API can be called only after a Panel instance is obtained by calling createPanel. This API uses a promise to return the result.
System capability: SystemCapability.SelectionInput.Selection
Model restriction: This API can be used only in the stage model.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| path | string | Yes | Path of the page content to be set. This path is configured in the resources/base/profile/main_pages.json file of the project in the stage model. The FA model is not supported. |
Return value
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
Error codes
For details about the following error codes, see Word Selection Error Codes. For details about other common error codes, see Universal Error Codes.
| ID | Error Message |
|---|---|
| 33600001 | Selection service exception. |
| 33600002 | This selection window has been destroyed. |
Example
import { BusinessError } from '@kit.BasicServicesKit';
try {
// Load page content for the word selection panel. selectionPanel is a Panel instance created by createPanel.
selectionPanel.setUiContent('pages/Index').then(() => {
console.info('Succeeded in setting the content.');
}).catch((err: BusinessError) => {
console.error(`Failed to setUiContent. Error code: ${err.code}, error message: ${err.message}`);
});
} catch (err) {
console.error(`Failed to setUiContent. Error code: ${err.code}, error message: ${err.message}`);
} [h2]show
show(): Promise<void>
Shows the word selection panel. This API is used together with hide. This API can be called only after a Panel instance is obtained by calling createPanel. This API uses a promise to return the result.
System capability: SystemCapability.SelectionInput.Selection
Model restriction: This API can be used only in the stage model.
Return value
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
Error codes
For details about the following error codes, see Word Selection Error Codes. For details about other common error codes, see Universal Error Codes.
| ID | Error Message |
|---|---|
| 33600001 | Selection service exception. |
| 33600002 | This selection window has been destroyed. |
Example
import { BusinessError } from '@kit.BasicServicesKit';
// Show the word selection panel. selectionPanel is a Panel instance created by createPanel.
selectionPanel.show().then(() => {
console.info('Succeeded in showing the panel.');
}).catch((err: BusinessError) => {
console.error(`Failed to show panel. Error code: ${err.code}, error message: ${err.message}`);
}); [h2]hide
hide(): Promise<void>
Hides the word selection panel. This API is used together with show. This API can be called only after a Panel instance is obtained by calling createPanel. This API uses a promise to return the result. If this API is not called, the panel is automatically hidden when it loses focus.
System capability: SystemCapability.SelectionInput.Selection
Model restriction: This API can be used only in the stage model.
Return value
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
Error codes
For details about the following error codes, see Word Selection Error Codes. For details about other common error codes, see Universal Error Codes.
| ID | Error Message |
|---|---|
| 33600001 | Selection service exception. |
| 33600002 | This selection window has been destroyed. |
Example
import { BusinessError } from '@kit.BasicServicesKit';
// Hide the word selection panel. selectionPanel is a Panel instance created by createPanel.
selectionPanel.hide().then(() => {
console.info('Succeeded in hiding the panel.');
}).catch((err: BusinessError) => {
console.error(`Failed to hide panel. Error code: ${err.code}, error message: ${err.message}`);
}); [h2]startMoving
startMoving(): Promise<void>
Sets whether the word selection panel can be dragged along with the mouse, touchpad, or touchscreen. The panel automatically stops moving after the pointer is released. This API can be called only after a Panel instance is obtained by calling createPanel. This API uses a promise to return the result. This API must be called in the onTouch callback, and the event type must be TouchType.Down.
System capability: SystemCapability.SelectionInput.Selection
Model restriction: This API can be used only in the stage model.
Return value
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
Error codes
For details about the following error codes, see Word Selection Error Codes. For details about other common error codes, see Universal Error Codes.
| ID | Error Message |
|---|---|
| 33600001 | Selection service exception. |
| 33600002 | This selection window has been destroyed. |
Example
import { BusinessError } from '@kit.BasicServicesKit';
// This code must be placed in build() of the ArkUI page component. RelativeContainer is a built-in component of ArkUI. TouchEvent and TouchType are built-in types of ArkUI.
RelativeContainer() {
/*
* Page layout content, which should be defined based on your actual needs.
*/
}
.onTouch((event: TouchEvent) => {
if (event.type === TouchType.Down) {
if (selectionPanel !== undefined) {
// Enable the word selection panel to be dragged along with the mouse, touchpad, or touchscreen. selectionPanel is a Panel instance created by createPanel.
selectionPanel.startMoving().then(() => {
console.info('Succeeded in startMoving the panel.');
}).catch((err: BusinessError) => {
console.error(`Failed to startMoving panel. Error code: ${err.code}, error message: ${err.message}`);
});
}
}
}) [h2]moveToGlobalDisplay
moveToGlobalDisplay(x: number, y: number): Promise<void>
Moves the word selection panel to the specified coordinates in the global coordinate system of the screen. The panel can be moved to an extended screen. This API can be called only after a Panel instance is obtained by calling createPanel. This API uses a promise to return the result.
System capability: SystemCapability.SelectionInput.Selection
Model restriction: This API can be used only in the stage model.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| x | number | Yes | X-coordinate of the target position in the global coordinate system of the screen, in px. The upper left corner of the main screen is the origin of the global coordinate system, and the positive direction of the X axis is rightward. The x-coordinate of an extended screen may be negative, depending on the screen layout. |
| y | number | Yes | Y-coordinate of the target position in the global coordinate system of the screen, in px. The upper left corner of the main screen is the origin of the global coordinate system, and the positive direction of the Y axis is downward. The y-coordinate of an extended screen may be negative, depending on the screen layout. |
Return value
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
Error codes
For details about the following error codes, see Word Selection Error Codes. For details about other common error codes, see Universal Error Codes.
| ID | Error Message |
|---|---|
| 33600001 | Selection service exception. |
| 33600002 | This selection window has been destroyed. |
Example
import { BusinessError } from '@kit.BasicServicesKit';
try {
// Move the word selection panel to the specified coordinates on the screen. selectionPanel is a Panel instance created by createPanel.
selectionPanel.moveToGlobalDisplay(200, 200).then(() => {
console.info('Succeeded in moving the panel.');
}).catch((err: BusinessError) => {
console.error(`Failed to move panel. Error code: ${err.code}, error message: ${err.message}`);
});
} catch (err) {
console.error(`Failed to move panel. Error code: ${err.code}, error message: ${err.message}`);
} [h2]on('destroyed')
on(type: 'destroyed', callback: Callback<void>): void
Subscribes to the word selection panel destruction event. This API is used together with off('destroyed'). This API can be called only after a Panel instance is obtained by calling createPanel.
System capability: SystemCapability.SelectionInput.Selection
Model restriction: This API can be used only in the stage model.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| type | string | Yes | Event type, which is 'destroyed'. |
| callback | Callback<void> | Yes | Callback used to return the result, which is triggered when destroyPanel is called to destroy the panel. |
Example
try {
// Subscribe to the word selection panel destruction event. selectionPanel is a Panel instance created by createPanel.
selectionPanel.on('destroyed', () => {
console.info('Panel has been destroyed.');
});
} catch (err) {
console.error(`Failed to register destroyed callback. Error code: ${err.code}, error message: ${err.message}`);
} [h2]off('destroyed')
off(type: 'destroyed', callback?: Callback<void>): void
Unsubscribes from the word selection panel destruction event. This API is used together with on('destroyed'). This API can be called only after a Panel instance is obtained by calling createPanel.
System capability: SystemCapability.SelectionInput.Selection
Model restriction: This API can be used only in the stage model.
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| type | string | Yes | Type of the event to unsubscribe from. The value is fixed to 'destroyed'. |
| callback | Callback<void> | No | Callback to be unregistered (that is, the callback instance registered using on). If this parameter is not specified, this API unregisters all callbacks for the specified type. |
Example
try {
// Unsubscribe from the word selection panel destruction event. selectionPanel is a Panel instance created by createPanel.
selectionPanel.off('destroyed');
} catch (err) {
console.error(`Failed to unregister destroyed. Error code: ${err.code}, error message: ${err.message}`);
} SelectionType
Enumerates the word selection types.
System capability: SystemCapability.SelectionInput.Selection
Model restriction: This API can be used only in the stage model.
| Name | Value | Description |
|---|---|---|
| MOUSE_MOVE | 1 | Word selection by sliding the mouse or touchpad. |
| DOUBLE_CLICK | 2 | Word selection by double-clicking the mouse or touchpad. |
| TRIPLE_CLICK | 3 | Word selection by triple-clicking the mouse or touchpad. |