Text Component Common APIs
NOTE
This topic covers the common APIs of text components. The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
CaretStyle10+
Atomic service API: This API can be used in atomic services since API version 11.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| width | Length | No | Caret size. It cannot be set in percentage. |
| color | ResourceColor | No | Caret color. |
LayoutManager12+
Implements a LayoutManager object.
NOTE
After the text content is changed, you must wait for the layout to be completed before you can obtain the most up-to-date layout information.
Objects to Import
The following uses the Text component as an example.
controller: TextController = new TextController()
let layoutManager: LayoutManager = this.controller.getLayoutManager();
getLineCount
getLineCount(): number
Obtains the total number of lines in the component.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Return value
| Type | Description |
|---|---|
| number | Total number of lines in the component. |
getGlyphPositionAtCoordinate
getGlyphPositionAtCoordinate(x: number, y: number): PositionWithAffinity
Obtains the position of a glyph close to a given coordinate.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| x | number | Yes | X coordinate relative to the component, in px. |
| y | number | Yes | Y coordinate relative to the component, in px. |
Return value
| Type | Description |
|---|---|
| PositionWithAffinity | Position of the glyph. |
getLineMetrics
getLineMetrics(lineNumber: number): LineMetrics
Obtains the metrics information of a specified line.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| lineNumber | number | Yes | Line number, starting at 0. |
Return value
| Type | Description |
|---|---|
| LineMetrics | Button("Line Metrics") |
getRectsForRange14+
getRectsForRange(range: TextRange, widthStyle: RectWidthStyle, heightStyle: RectHeightStyle): Array<TextBox>
Obtains the drawing area information for characters or placeholders within a specified text range, based on the specified width and height of a rectangle.
Atomic service API: This API can be used in atomic services since API version 14.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| range | TextRange | Yes | Text range for which to obtain the area information. |
| widthStyle | RectWidthStyle | Yes | Width of the rectangle. |
| heightStyle | RectHeightStyle | Yes | Height of the rectangle. |
Return value
| Type | Description |
|---|---|
| Array<TextBox> | Array holding the rectangles obtained. |
PositionWithAffinity12+
Describes the position and affinity of a glyph.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Read Only | Optional | Description |
|---|---|---|---|---|
| position | number | Yes | No | Index of the glyph relative to the paragraph. The value is an integer. |
| affinity | Affinity | Yes | Yes | Affinity of the position. |
TextMenuItemId12+
Provides the menu ID.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Attributes
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Read Only | Optional | Description |
|---|---|---|---|---|
| CUT | TextMenuItemId | Yes | Yes | Cut operation by default. Atomic service API: This API can be used in atomic services since API version 12. |
| COPY | TextMenuItemId | Yes | Yes | Copy operation by default. Atomic service API: This API can be used in atomic services since API version 12. |
| PASTE | TextMenuItemId | Yes | Yes | Paste operation by default. Atomic service API: This API can be used in atomic services since API version 12. |
| SELECT_ALL | TextMenuItemId | Yes | Yes | Select-all operation by default. Atomic service API: This API can be used in atomic services since API version 12. |
| COLLABORATION_SERVICE | TextMenuItemId | Yes | Yes | Collaboration service. Atomic service API: This API can be used in atomic services since API version 12. |
| CAMERA_INPUT | TextMenuItemId | Yes | Yes | Camera input Atomic service API: This API can be used in atomic services since API version 12. |
| AI_WRITER13+ | TextMenuItemId | Yes | Yes | Text enhancement features, such as polishing, summary extraction, and formatting, for selected text. This menu item requires large model capabilities to function. Atomic service API: This API can be used in atomic services since API version 13. |
of
static of(id: ResourceStr): TextMenuItemId
Creates a TextMenuItemId object based on id.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| id | ResourceStr | Yes | Menu ID. |
Return value
| Type | Description |
|---|---|
| TextMenuItemId | TextMenuItemId object. |
equals
equals(id: TextMenuItemId): boolean
Checks whether this TextMenuItemId object is the same as another TextMenuItemId object.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| id | TextMenuItemId | Yes | ID of the TextMenuItemId object to compare. |
Return value
| Type | Description |
|---|---|
| boolean | Whether the two TextMenuItemId objects are the same. |
TextMenuItem12+
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| content | ResourceStr | Yes | Menu name. |
| icon | ResourceStr | No | Menu icon. Online images are not supported. |
| id | TextMenuItemId | Yes | Menu ID. |
EditMenuOptions
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
onCreateMenu12+
onCreateMenu(menuItems: Array<TextMenuItem>): Array<TextMenuItem>
Creates a menu with the specified menu items.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| menuItems | Array<TextMenuItem> | Yes | Menu items. NOTE Changes to the name of the default menu item do not take effect. |
Return value
| Type | Description |
|---|---|
| Array<TextMenuItem> | Menu items set. NOTE The icon of the default menu item is not returned. |
onMenuItemClick12+
onMenuItemClick(menuItem: TextMenuItem, range: TextRange): boolean
Called when the specified menu item is clicked.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| menuItem | TextMenuItem | Yes | Menu item. |
| range | TextRange | Yes | Selected text. |
Return value
| Type | Description |
|---|---|
| boolean | Execution logic of the menu item. Returns true if the default system logic is intercepted and only the custom logic is executed. Returns false if the custom logic is executed before the default system logic. |
TextRange12+
Defines the text range.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Attributes
| Name | Type | Mandatory | Description |
|---|---|---|---|
| start | number | No | Start index. |
| end | number | No | End index. |
EditableTextOnChangeCallback12+
type EditableTextOnChangeCallback = (value: string, previewText?: PreviewText) => void
Invoked when the input in the text box changes.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| value | string | Yes | Text displayed in the text box. |
| previewText | PreviewText | No | Information about the preview text, including its start position and text content. |
TextDataDetectorType11+
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Description |
|---|---|
| PHONE_NUMBER | Phone number. |
| URL | URL. |
| Email address. | |
| ADDRESS | Address. |
| DATE_TIME12+ | Time. |
TextDeleteDirection12+
Defines the direction for deleting text.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Value | Description |
|---|---|---|
| BACKWARD | 0 | Backward delete. |
| FORWARD | 1 | Forward delete. |
MenuType13+
Enumerates the menu types.
Atomic service API: This API can be used in atomic services since API version 13.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Value | Description |
|---|---|---|
| SELECTION_MENU | 0 | Text selection menu. |
| PREVIEW_MENU | 1 | Preview menu. |
InsertValue12+
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| insertOffset | number | Yes | Position of the inserted text. |
| insertValue | string | Yes | Content of the inserted text. |
DeleteValue12+
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| deleteOffset | number | Yes | Position of the deleted text. |
| direction | TextDeleteDirection | Yes | Direction for deleting the text. |
| deleteValue | string | Yes | Content of the deleted text. |
TextDataDetectorConfig11+
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| types | TextDataDetectorType[] | Yes | Entity types for text recognition. Values null and [] indicate that all types of entities can be recognized. |
| onDetectResultUpdate | (result: string) => void | No | Callback invoked when text recognition succeeds. - result: text recognition result, in JSON format. |
| color12+ | ResourceColor | No | Entity color when text recognition succeeds. Default value: '#ff0a59f7' |
| decoration12+ | DecorationStyleInterface | No | Style of the entity decorative line when text recognition succeeds. Default value: { type: TextDecorationType.Underline, color: same as the entity style: TextDecorationStyle.SOLID } |
PreviewText12+
Preview text.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| offset | number | Yes | Start position of the preview text. |
| value | string | Yes | Content of the preview text. |
FontSettingOptions12+
Defines the font settings, including smooth and continuous adjustments for the font weight for components in your application.
Widget capability: This API can be used in ArkTS widgets since API version 12.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| enableVariableFontWeight | boolean | No | Whether to support variable font weight adjustment. Default value: false |
OnDidChangeCallback12+
type OnDidChangeCallback = (rangeBefore: TextRange, rangeAfter: TextRange) => void
Represents the callback invoked after text changes.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| rangeBefore | TextRange | Yes | Range of the text to be changed. |
| rangeAfter | TextRange | Yes | Range of the text added. |
StyledStringChangedListener12+
Defines the listener for changes of the styled string text content.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| onWillChange | Callback<StyledStringChangeValue, boolean> | No | Callback invoked when text is about to change. |
| onDidChange | OnDidChangeCallback | No | Callback invoked when text is changed. |
StyledStringChangeValue12+
Describes the text changes of the styled string.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| range | TextRange | Yes | Range of the styled string to be replaced in the original string. |
| replacementString | StyledString | Yes | Styled string used for replacement. |
| previewText | StyledString | No | Preview styled string. |
TextBaseController12+
Defines a text selection controller.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
setSelection12+
setSelection(selectionStart: number, selectionEnd: number, options?: SelectionOptions): void
Sets the range of content selection. The selected content is highlighted.
If both selectionStart and selectionEnd are set to -1, the entire content is selected.
The component must be focused for the API call to have effect.
Since API version 12, on 2-in-1 devices, regardless of the value of options, calling the setSelection API will not display a menu; if a menu is already open, calling the API will close it.
On non-2-in-1 devices, when options is set to MenuPolicy.DEFAULT, the following rules apply after the API is called:
-
If the component has a menu with a selection handle, the menu remains open and is relocated according to the selection.
-
If the component has a menu without a selection handle, the menu remains open and its position remains unchanged.
-
If there is no menu open, no menu will appear after the selection.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| selectionStart | number | Yes | Start position of the selection. |
| selectionEnd | number | Yes | End position of the selection. |
| options12+ | SelectionOptions | No | Configuration of options. |
closeSelectionMenu12+
closeSelectionMenu(): void
Closes the custom or default text selection menu.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
getLayoutManager12+
getLayoutManager(): LayoutManager
Obtains a LayoutManager object.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Return value
| Type | Description |
|---|---|
| LayoutManager | Implements a LayoutManager object. |
TextEditControllerEx12+
Implements an extended text editing controller.
Inherits TextBaseController.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
isEditing12+
isEditing(): boolean
Obtains the editing status of the rich text.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Return value
| Type | Description |
|---|---|
| boolean | Editing status of the rich text. true means that the text is in editable state, and false means the opposite. |
stopEditing12+
stopEditing(): void
Stops editing.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
getCaretOffset12+
getCaretOffset(): number
Obtains the current position of the cursor.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Return value
| Type | Description |
|---|---|
| number | Position of the cursor. |
setCaretOffset12+
setCaretOffset(offset: number): boolean
Sets the cursor offset.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| offset | number | Yes | Offset of the cursor. If the offset is outside the range of all content, the setting fails. |
Return value
| Type | Description |
|---|---|
| boolean | Whether the cursor is set successfully. |
getPreviewText12+
getPreviewText?(): PreviewText
Obtains the preview text.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Return value
| Type | Description |
|---|---|
| PreviewText | Preview text. |
StyledStringController12+
Defines a styled string controller.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
setStyledString12+
setStyledString(styledString: StyledString): void
Sets the styled string displayed in the rich text component.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| styledString | StyledString | Yes | Styled string to set. NOTE The child class MutableStyledString of StyledString can also serve as the argument. |
getStyledString12+
getStyledString(): MutableStyledString;
Obtains the styled string displayed in the rich text component.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
Return value
| Type | Description |
|---|---|
| MutableStyledString | Styled string displayed in the rich text component. |
DecorationStyleResult12+
Provides the text decorative line information returned by the backend.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Name | Type | Mandatory | Description |
|---|---|---|---|
| type | TextDecorationType | Yes | Type of the text decorative line. |
| color | ResourceColor | Yes | Color of the text decorative line. |
| style | TextDecorationStyle | No | Style of the text decorative line. |
LineMetrics12+
type LineMetrics = LineMetrics
Describes the measurement information of a single line of text in the text layout.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Type | Description |
|---|---|
| LineMetrics | Measurement information of a single line of text in the text layout. |
Affinity12+
type Affinity = Affinity
Enumerates the affinity modes.
Atomic service API: This API can be used in atomic services since API version 12.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Type | Description |
|---|---|
| Affinity | Affinity mode enum. |
TextBox14+
type TextBox = TextBox
Describes the rectangle that holds the text.
Atomic service API: This API can be used in atomic services since API version 14.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Type | Description |
|---|---|
| TextBox | Rectangle that holds the text. |
RectHeightStyle14+
type RectHeightStyle = RectHeightStyle
Enumerates the rectangle height styles.
Atomic service API: This API can be used in atomic services since API version 14.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Type | Description |
|---|---|
| RectHeightStyle | Rectangle height style enum. |
RectWidthStyle14+
type RectWidthStyle = RectWidthStyle
Enumerates the rectangle width styles.
Atomic service API: This API can be used in atomic services since API version 14.
System capability: SystemCapability.ArkUI.ArkUI.Full
| Type | Description |
|---|---|
| RectWidthStyle | Rectangle width style enum. |