openharmony 鸿蒙 ts-text-common

2025-06-12 浏览 (1)

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

NameTypeMandatoryDescription
widthLengthNoCaret size. It cannot be set in percentage.
Default value: '2vp'.
colorResourceColorNoCaret color.
Default value: '#ff007dff'.

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

TypeDescription
numberTotal 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

NameTypeMandatoryDescription
xnumberYesX coordinate relative to the component.
Unit: px
ynumberYesY coordinate relative to the component.
Unit: px

Return value

TypeDescription
PositionWithAffinityPosition of the glyph.

getLineMetrics

getLineMetrics(lineNumber: number): LineMetrics

Obtains the information about the specified line, including line metrics, text style information, and font properties.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

NameTypeMandatoryDescription
lineNumbernumberYesLine number, which is zero-based.

Return value

TypeDescription
LineMetricsInformation about the specified line, including line metrics, text style information, and font properties.
Returns an invalid value if the line number is less than 0 or exceeds the actual number of lines.

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

NameTypeMandatoryDescription
rangeTextRangeYesText range for which to obtain the area information.
widthStyleRectWidthStyleYesWidth of the rectangle.
heightStyleRectHeightStyleYesHeight of the rectangle.

Return value

TypeDescription
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

NameTypeRead OnlyOptionalDescription
positionnumberYesNoIndex of the glyph relative to the paragraph. The value is an integer.
affinityAffinityYesYesAffinity of the position.

TextMenuItemId12+

Defines the unique identifier for a custom menu item. It is used to identify menu items. The IDs for built-in menu items are listed in the table below.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Properties

System capability: SystemCapability.ArkUI.ArkUI.Full

NameTypeRead OnlyOptionalDescription
CUTTextMenuItemIdYesYesID for the cut menu item.
Atomic service API: This API can be used in atomic services since API version 12.
COPYTextMenuItemIdYesYesID for the paste menu item.
Atomic service API: This API can be used in atomic services since API version 12.
PASTETextMenuItemIdYesYesID for the paste menu item.
Atomic service API: This API can be used in atomic services since API version 12.
SELECT_ALLTextMenuItemIdYesYesID for the select-all menu item.
Atomic service API: This API can be used in atomic services since API version 12.
COLLABORATION_SERVICETextMenuItemIdYesYesID for the collaboration service menu item.
Atomic service API: This API can be used in atomic services since API version 12.
CAMERA_INPUTTextMenuItemIdYesYesID for the camera input menu item.
Atomic service API: This API can be used in atomic services since API version 12.
AI_WRITER13+TextMenuItemIdYesYesID for the menu item involving text enhancement features, such as polishing, summary extraction, and formatting, for selected text. This menu item requires foundation model capabilities to function.
Atomic service API: This API can be used in atomic services since API version 13.
TRANSLATE15+TextMenuItemIdYesYesID for the translate menu item.
Atomic service API: This API can be used in atomic services since API version 15.
SHARE18+TextMenuItemIdYesYesID for the share menu item, which launches a window for sharing the selected text.
Atomic service API: This API can be used in atomic services since API version 18.
SEARCH18+TextMenuItemIdYesYesID for the search menu item, which launches a browser to search the selected text.
Atomic service API: This API can be used in atomic services since API version 18.

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

NameTypeMandatoryDescription
idResourceStrYesMenu ID.

Return value

TypeDescription
TextMenuItemIdTextMenuItemId 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

NameTypeMandatoryDescription
idTextMenuItemIdYesID of the TextMenuItemId object to compare.

Return value

TypeDescription
booleanWhether 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

NameTypeMandatoryDescription
contentResourceStrYesMenu name.
iconResourceStrNoMenu icon.
Online images are not supported.
idTextMenuItemIdYesMenu ID.
labelInfo15+ResourceStrNoShortcut key hint.
This field is only supported on 2-in-1 devices.
Atomic service API: This API can be used in atomic services since API version 15.

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

NameTypeMandatoryDescription
menuItemsArray<TextMenuItem>YesMenu items.
NOTE
Changes to the name of the default menu item do not take effect.

Return value

TypeDescription
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

NameTypeMandatoryDescription
menuItemTextMenuItemYesMenu item.
rangeTextRangeYesSelected text.

Return value

TypeDescription
booleanExecution 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

NameTypeMandatoryDescription
startnumberNoStart index.
endnumberNoEnd index.

EditableTextOnChangeCallback12+

type EditableTextOnChangeCallback = (value: string, previewText?: PreviewText, options?: TextChangeOptions) => void

Represents the callback triggered when the content 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

NameTypeMandatoryDescription
valuestringYesText displayed in the text box.
previewTextPreviewTextNoInformation about the preview text, including its start position and text content.
options15+TextChangeOptionsNoInformation about the text change, including the selection range before and after the change, the text content before the change, and the preview text information.

TextDataDetectorType11+

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

NameValueDescription
PHONE_NUMBER0Phone number.
URL1URL.
EMAIL2Email address.
ADDRESS3Address.
DATE_TIME12+4Time.

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

NameValueDescription
BACKWARD0Backward delete.
FORWARD1Forward 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

NameValueDescription
SELECTION_MENU0Text selection menu.
PREVIEW_MENU1Preview menu.

KeyboardAppearance15+

Enumerates the appearance modes of the keyboard.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.ArkUI.ArkUI.Full

NameValueDescription
NONE_IMMERSIVE0Default appearance mode, not using immersive style.
IMMERSIVE1Immersive style, following the system color mode.
LIGHT_IMMERSIVE2Immersive style in light mode.
DARK_IMMERSIVE3Immersive style in dark mode.

InsertValue12+

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

NameTypeMandatoryDescription
insertOffsetnumberYesPosition of the inserted text.
insertValuestringYesContent 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

NameTypeMandatoryDescription
deleteOffsetnumberYesPosition of the deleted text.
directionTextDeleteDirectionYesDirection for deleting the text.
deleteValuestringYesContent 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

NameTypeMandatoryDescription
typesTextDataDetectorType[]YesEntity types for text recognition. Values null and [] indicate that all types of entities can be recognized.
onDetectResultUpdate(result: string) => voidNoCallback invoked when text recognition succeeds.
- result: text recognition result, in JSON format.
color12+ResourceColorNoEntity color when text recognition succeeds.
Default value: '#ff0a59f7'
decoration12+DecorationStyleInterfaceNoStyle 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

NameTypeMandatoryDescription
offsetnumberYesStart position of the preview text.
valuestringYesContent 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

NameTypeMandatoryDescription
enableVariableFontWeightbooleanNoWhether to support variable font weight adjustment.
Default value: false.
true: Support variable font weight adjustment.
false: Do not support variable font weight adjustment.

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

NameTypeMandatoryDescription
rangeBeforeTextRangeYesRange of the text to be changed.
rangeAfterTextRangeYesRange 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

NameTypeMandatoryDescription
onWillChangeCallback<StyledStringChangeValue, boolean>NoCallback invoked when text is about to change.
onDidChangeOnDidChangeCallbackNoCallback 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

NameTypeMandatoryDescription
rangeTextRangeYesRange of the styled string to be replaced in the original string.
replacementStringStyledStringYesStyled string used for replacement.
previewTextStyledStringNoPreview 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:

  1. If the component has a menu with a selection handle, the menu remains open and is relocated according to the selection.

  2. If the component has a menu without a selection handle, the menu remains open and its position remains unchanged.

  3. 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

NameTypeMandatoryDescription
selectionStartnumberYesStart position of the selection.
Values less than 0 are treated as 0.
selectionEndnumberYesEnd position of the selection.
If the value exceeds the text length, the current text length is used instead.
optionsSelectionOptionsNoConfiguration 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

TypeDescription
LayoutManagerImplements 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

TypeDescription
booleanEditing 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

TypeDescription
numberPosition 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

NameTypeMandatoryDescription
offsetnumberYesOffset of the cursor. If the offset is outside the range of all content, the setting fails.

Return value

TypeDescription
booleanWhether 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

TypeDescription
PreviewTextPreview 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

NameTypeMandatoryDescription
styledStringStyledStringYesStyled 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

TypeDescription
MutableStyledStringStyled 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

NameTypeMandatoryDescription
typeTextDecorationTypeYesType of the text decorative line.
colorResourceColorYesColor of the text decorative line.
styleTextDecorationStyleNoStyle 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

TypeDescription
LineMetricsMeasurement 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

TypeDescription
AffinityAffinity 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

TypeDescription
TextBoxRectangle 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

TypeDescription
RectHeightStyleRectangle 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

TypeDescription
RectWidthStyleRectangle width style enum.

TextChangeOptions15+

Provides information about the text before and after a change, including the selection ranges.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.ArkUI.ArkUI.Full

NameTypeMandatoryDescription
rangeBeforeTextRangeYesSelection range before the change.
rangeAfterTextRangeYesSelection range after the change.
oldContentstringYesText content before the change.
oldPreviewTextPreviewTextYesPreview text before the change.

EditableTextChangeValue15+

Provides detailed information of text changes, including preview text.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.ArkUI.ArkUI.Full

NameTypeMandatoryDescription
contentstringYesCurrent text content.
previewTextPreviewTextNoPreview text.
optionsTextChangeOptionsNoInformation about the text change.

TextMenuShowMode16+

Enumerates the display modes for context menus on selection.

Atomic service API: This API can be used in atomic services since API version 16.

System capability: SystemCapability.ArkUI.ArkUI.Full

NameValueDescription
DEFAULT0The menu is displayed in the current window.
PREFER_WINDOW1The menu is preferentially displayed in a separate window. If a separate window is not supported, the menu is displayed in the current window.
NOTE
The context menu on selection cannot be displayed in a separate window under the following scenarios:
Windows other than the main application window, application subwindows, system modal windows, and system home screen windows
DevEco Studio Previewer
UIExtension
Text component that is already displayed in a child window (for example, Popup, Dialog, Toast, and Menu)
TextInput or TextArea components that support AutoFill

TextMenuOptions16+

Provides the options for customizing the context menu on selection.

Atomic service API: This API can be used in atomic services since API version 16.

System capability: SystemCapability.ArkUI.ArkUI.Full

NameTypeMandatoryDescription
showModeTextMenuShowModeNoMenu display mode.
Default value: TextMenuShowMode.DEFAULT

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArcButton

harmony 鸿蒙ArcSlider

harmony 鸿蒙Chip

harmony 鸿蒙ChipGroup

harmony 鸿蒙ComposeListItem

harmony 鸿蒙ComposeTitleBar

harmony 鸿蒙advanced.Counter

harmony 鸿蒙Dialog Box (Dialog)

harmony 鸿蒙DialogV2

harmony 鸿蒙DownloadFileButton

  • 所属分类: 后端技术
  • 本文标签: 软件 鸿蒙
  • 版权声明: 本文链接 https://seaxiang.com/blog/ZaBlBR