1# Common Text Component APIs 2 3>**NOTE** 4> 5>This topic covers the common APIs of text components. 6>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. 7 8## CaretStyle<sup>10+</sup> 9 10**Atomic service API**: This API can be used in atomic services since API version 11. 11 12| Name| Type | Mandatory| Description| 13| ------ | ------------------------------------------ | ---- | -------- | 14| width | [Length](ts-types.md#length) | No | Caret size. It cannot be set in percentage.| 15| color | [ResourceColor](ts-types.md#resourcecolor) | No | Caret color.| 16 17## LayoutManager<sup>12+</sup> 18 19Implements a **LayoutManager** object. 20> **NOTE** 21> 22> 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. 23 24### Objects to Import 25The following uses the **Text** component as an example. 26``` 27controller: TextController = new TextController() 28let layoutManager: LayoutManager = this.controller.getLayoutManager(); 29``` 30 31### getLineCount 32 33getLineCount(): number 34 35Obtains the total number of lines in the component. 36 37**Atomic service API**: This API can be used in atomic services since API version 12. 38 39**Return value** 40 41| Type | Description | 42| ------ | --------- | 43| number | Total number of lines in the component.| 44 45### getGlyphPositionAtCoordinate 46 47getGlyphPositionAtCoordinate(x: number, y: number): PositionWithAffinity 48 49Obtains the position of a glyph close to a given coordinate. 50 51**Atomic service API**: This API can be used in atomic services since API version 12. 52 53**Parameters** 54 55| Name | Type | Mandatory | Description | 56| ------ | ------ | ---- | -------------------- | 57| x | number | Yes | X coordinate relative to the component, in px.| 58| y | number | Yes | Y coordinate relative to the component, in px.| 59 60**Return value** 61 62| Type | Description | 63| --------------------------------------------- | ----------- | 64| [PositionWithAffinity](#positionwithaffinity) | Position of the glyph.| 65 66### getLineMetrics 67 68getLineMetrics(lineNumber: number): LineMetrics 69 70Obtains the metrics information of a specified line. 71 72**Atomic service API**: This API can be used in atomic services since API version 12. 73 74**Parameters** 75 76| Name | Type | Mandatory | Description | 77| ------ | ------ | ---- | -------------------- | 78| lineNumber | number | Yes | Line number, starting at 0.| 79 80**Return value** 81 82| Type | Description | 83| ---------------------------------------- | -------- | 84| [LineMetrics](../../apis-arkgraphics2d/js-apis-graphics-text.md#linemetrics) | Button("Line Metrics")| 85 86## PositionWithAffinity 87 88Describes the position and affinity of a glyph. 89 90**System capability**: SystemCapability.ArkUI.ArkUI.Full 91 92| Name | Type | Read Only| Mandatory| Description | 93| --------- | --------------------- | ---- | ---- | ------------------------ | 94| position | number | Yes | Yes | Index of the glyph relative to the paragraph. The value is an integer. | 95| affinity | [Affinity](../../apis-arkgraphics2d/js-apis-graphics-text.md#affinity) | Yes | Yes | Affinity of the position. | 96 97## TextMenuItemId<sup>12+</sup> 98 99Provides the menu ID. 100 101**Atomic service API**: This API can be used in atomic services since API version 12. 102 103**System capability**: SystemCapability.ArkUI.ArkUI.Full 104 105### Attributes 106 107**Atomic service API**: This API can be used in atomic services since API version 12. 108 109**System capability**: SystemCapability.ArkUI.ArkUI.Full 110 111| Name | Type | Read Only | Mandatory | Description | 112| ------------ |---------------------| ---- | ---- | ------ | 113| CUT | [TextMenuItemId](#textmenuitemid12) | Yes | No | Cut operation by default.| 114| COPY | [TextMenuItemId](#textmenuitemid12) | Yes | No | Copy operation by default.| 115| PASTE | [TextMenuItemId](#textmenuitemid12) | Yes | No | Paste operation by default.| 116| SELECT_ALL | [TextMenuItemId](#textmenuitemid12) | Yes | No | Select-all operation by default.| 117| COLLABORATION_SERVICE | [TextMenuItemId](#textmenuitemid12) | Yes | No | Collaboration service.| 118| CAMERA_INPUT | [TextMenuItemId](#textmenuitemid12) | Yes | No | Camera input| 119 120### of 121 122static of(id: ResourceStr): TextMenuItemId 123 124Creates a **TextMenuItemId** object based on **id**. 125 126**Atomic service API**: This API can be used in atomic services since API version 12. 127 128**System capability**: SystemCapability.ArkUI.ArkUI.Full 129 130**Parameters** 131 132| Name | Type | Mandatory| Description | 133| ------- | --------------------------------- | ---- | ------------------------------------------------------------ | 134| id | [ResourceStr](ts-types.md#resourcestr) | Yes | Menu ID.| 135 136**Return value** 137 138| Type | Description | 139| ------- | --------------------------------- | 140| [TextMenuItemId](#textmenuitemid12) | **TextMenuItemId** object.| 141 142### equals 143 144equals(id: TextMenuItemId): boolean 145 146Checks whether this **TextMenuItemId** object is the same as another **TextMenuItemId** object. 147 148**System capability**: SystemCapability.ArkUI.ArkUI.Full 149 150**Parameters** 151 152| Name | Type | Mandatory| Description | 153| ------- | --------------------------------- | ---- | ------------------------------------------------------------ | 154| id | [TextMenuItemId](#textmenuitemid12) | Yes | ID of the **TextMenuItemId** object to compare.| 155 156**Return value** 157 158| Type | Description | 159| ------- | --------------------------------- | 160| boolean | Whether the two **TextMenuItemId** objects are the same.| 161 162## TextMenuItem 163 164**Atomic service API**: This API can be used in atomic services since API version 12. 165 166**System capability**: SystemCapability.ArkUI.ArkUI.Full 167 168| Name | Type | Mandatory| Description | 169| ------- | --------------------------------- | ---- | --------------------------------- | 170| content | [ResourceStr](ts-types.md#resourcestr) | Yes | Menu name.| 171| icon | [ResourceStr](ts-types.md#resourcestr) | No | Menu icon.<br>Online images are not supported.| 172| id | [TextMenuItemId](#textmenuitemid12) | Yes | Menu ID.| 173 174## EditMenuOptions 175 176**Atomic service API**: This API can be used in atomic services since API version 12. 177 178**System capability**: SystemCapability.ArkUI.ArkUI.Full 179 180### onCreateMenu 181 182onCreateMenu(menuItems: Array\<TextMenuItem>): Array\<TextMenuItem> 183 184Creates a menu with the specified menu items. 185 186**Atomic service API**: This API can be used in atomic services since API version 12. 187 188**System capability**: SystemCapability.ArkUI.ArkUI.Full 189 190**Parameters** 191 192| Name | Type | Mandatory| Description | 193| ------- | --------------------------------- | ---- | --------------------------------- | 194| menuItems | Array\<[TextMenuItem](#textmenuitem)> | Yes | Menu items.<br>**NOTE**<br>Changes to the name of the default menu item do not take effect.| 195 196**Return value** 197 198| Type | Description | 199| ------- | --------------------------------- | 200| Array\<[TextMenuItem](#textmenuitem)> | Menu items set.<br>**NOTE**<br>The icon of the default menu item is not returned.| 201 202### onMenuItemClick 203 204onMenuItemClick(menuItem: TextMenuItem, range: TextRange): boolean 205 206Called when the specified menu item is clicked. 207 208**Atomic service API**: This API can be used in atomic services since API version 12. 209 210**System capability**: SystemCapability.ArkUI.ArkUI.Full 211 212**Parameters** 213 214| Name | Type | Mandatory| Description | 215| ------- | --------------------------------- | ---- | --------------------------------- | 216| menuItem | [TextMenuItem](#textmenuitem) | Yes | Menu item.| 217| range | [TextRange](#textrange12) | Yes | Selected text.| 218 219**Return value** 220 221| Type | Description | 222| ------- | --------------------------------- | 223| boolean | Execution logic of the menu item.<br>Returns **true** if the default system logic is intercepted and only the custom logic is executed.<br>Returns **false** if the custom logic is executed before the default system logic.| 224 225## EditableTextOnChangeCallback<sup>12+</sup> 226 227type EditableTextOnChangeCallback = (value: string, previewText?: PreviewText) => void 228 229Invoked when the input in the text box changes. 230 231**Parameters** 232 233| Name| Type| Mandatory| Description| 234| -- | -- | -- | -- | 235| value | string | Yes| Text displayed in the text box.| 236| previewText | [PreviewText](#previewtext12) | No| Information about the preview text, including its start position and text content.| 237 238## TextDataDetectorType<sup>11+</sup> 239 240**Atomic service API**: This API can be used in atomic services since API version 12. 241 242**System capability**: SystemCapability.ArkUI.ArkUI.Full 243 244| Name | Description | 245| ----- | -------------------------------------- | 246| PHONE_NUMBER | Phone number.| 247| URL | URL.| 248| EMAIL | Email address.| 249| ADDRESS | Address.| 250| DATE_TIME | Time.| 251 252## TextDeleteDirection<sup>12+</sup> 253 254Defines the direction for deleting text. 255 256**Atomic service API**: This API can be used in atomic services since API version 12. 257 258**System capability**: SystemCapability.ArkUI.ArkUI.Full 259 260| Name | Value | Description | 261| ------- | ---- | ---------------------------------- | 262| BACKWARD | 0 | Backward delete.| 263| FORWARD | 1 | Forward delete.| 264 265## InsertValue<sup>12+</sup> 266 267**Atomic service API**: This API can be used in atomic services since API version 12. 268 269**System capability**: SystemCapability.ArkUI.ArkUI.Full 270 271| Name | Type | Mandatory| Description | 272| ------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 273| insertOffset | number | Yes | Position of the inserted text.| 274| insertValue | string | Yes | Content of the inserted text.| 275 276## DeleteValue<sup>12+</sup> 277 278**Atomic service API**: This API can be used in atomic services since API version 12. 279 280**System capability**: SystemCapability.ArkUI.ArkUI.Full 281 282| Name | Type | Mandatory| Description | 283| ------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 284| deleteOffset | number | Yes | Position of the deleted text.| 285| direction | [TextDeleteDirection](#textdeletedirection12) | Yes | Direction for deleting the text.| 286| deleteValue | string | Yes | Content of the deleted text.| 287 288## TextDataDetectorConfig<sup>11+</sup> 289 290**Atomic service API**: This API can be used in atomic services since API version 12. 291 292**System capability**: SystemCapability.ArkUI.ArkUI.Full 293 294| Name| Type | Mandatory| Description | 295| ------ | -------- | ---- | ------------------------------------------- | 296| types | [TextDataDetectorType[]](ts-text-common.md#textdatadetectortype11) | Yes | Entity types for text recognition. Values **null** and **[]** indicate that all types of entities can be recognized.| 297| onDetectResultUpdate | (result: string) => void | No | Callback invoked when text recognition succeeds.<br>- **result**: text recognition result, in JSON format.| 298 299## PreviewText<sup>12+</sup> 300 301Preview text. 302 303**Atomic service API**: This API can be used in atomic services since API version 12. 304 305**System capability**: SystemCapability.ArkUI.ArkUI.Full 306 307| Name | Type | Mandatory| Description | 308| -------- | ------------------------------------------------ | ---- | -------------------------------------------------------- | 309| offset | number | Yes | Start position of the preview text.| 310| value | string | Yes | Content of the preview text. | 311