1# Text Component Common 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## TextRange<sup>12+</sup>
226
227Defines the text range.
228
229**Atomic service API**: This API can be used in atomic services since API version 12.
230
231| Name| Type| Mandatory| Description|
232| -- | -- | -- | -- |
233| start | number | No| Start index.|
234| end | number | No| End index.|
235
236## EditableTextOnChangeCallback<sup>12+</sup>
237
238type EditableTextOnChangeCallback = (value: string, previewText?: PreviewText) => void
239
240Invoked when the input in the text box changes.
241
242**Parameters**
243
244| Name| Type| Mandatory| Description|
245| -- | -- | -- | -- |
246| value | string | Yes| Text displayed in the text box.|
247| previewText | [PreviewText](#previewtext12) | No| Information about the preview text, including its start position and text content.|
248
249## TextDataDetectorType<sup>11+</sup>
250
251**Atomic service API**: This API can be used in atomic services since API version 12.
252
253**System capability**: SystemCapability.ArkUI.ArkUI.Full
254
255| Name | Description                                  |
256| ----- | -------------------------------------- |
257| PHONE_NUMBER  | Phone number.|
258| URL | URL.|
259| EMAIL | Email address.|
260| ADDRESS | Address.|
261| DATE_TIME | Time.|
262
263## TextDeleteDirection<sup>12+</sup>
264
265Defines the direction for deleting text.
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   | Value  | Description                              |
272| ------- | ---- | ---------------------------------- |
273| BACKWARD | 0    | Backward delete.|
274| FORWARD    | 1    | Forward delete.|
275
276## InsertValue<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| insertOffset  | number | Yes  | Position of the inserted text.|
285| insertValue  | string | Yes  | Content of the inserted text.|
286
287## DeleteValue<sup>12+</sup>
288
289**Atomic service API**: This API can be used in atomic services since API version 12.
290
291**System capability**: SystemCapability.ArkUI.ArkUI.Full
292
293| Name   | Type                                                   | Mandatory| Description                                                        |
294| ------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ |
295| deleteOffset  | number | Yes  | Position of the deleted text.|
296| direction  | [TextDeleteDirection](#textdeletedirection12) | Yes  | Direction for deleting the text.|
297| deleteValue  | string | Yes  | Content of the deleted text.|
298
299## TextDataDetectorConfig<sup>11+</sup>
300
301**Atomic service API**: This API can be used in atomic services since API version 12.
302
303**System capability**: SystemCapability.ArkUI.ArkUI.Full
304
305| Name| Type | Mandatory| Description |
306| ------ | -------- | ---- | ------------------------------------------- |
307| 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.|
308| onDetectResultUpdate   | (result: string) => void | No  | Callback invoked when text recognition succeeds.<br>- **result**: text recognition result, in JSON format.|
309| color<sup>12+</sup>   | [ResourceColor](ts-types.md#resourcecolor) | No  | Entity color when text recognition succeeds.<br>Default value: **'#ff007dff'**|
310| decoration<sup>12+</sup>  | [DecorationStyleInterface](ts-universal-styled-string.md#decorationstyleinterface)| No  | Style of the entity decorative line when text recognition succeeds.<br>Default value:<br>{<br> type: TextDecorationType.Underline,<br> color: consistent with the entity color,<br> style: TextDecorationStyle.SOLID <br>} |
311## PreviewText<sup>12+</sup>
312
313Preview text.
314
315**Atomic service API**: This API can be used in atomic services since API version 12.
316
317**System capability**: SystemCapability.ArkUI.ArkUI.Full
318
319| Name    | Type                                            | Mandatory| Description                                                    |
320| -------- | ------------------------------------------------ | ---- | -------------------------------------------------------- |
321| offset | number | Yes  | Start position of the preview text.|
322| value    | string         | Yes  | Content of the preview text.        |
323
324## FontSettingOptions<sup>12+</sup>
325
326Defines the font settings.
327
328**Widget capability**: This API can be used in ArkTS widgets since API version 12.
329
330**Atomic service API**: This API can be used in atomic services since API version 12.
331
332**System capability**: SystemCapability.ArkUI.ArkUI.Full
333
334| Name    | Type                                            | Mandatory| Description                                                    |
335| -------- | ------------------------------------------------ | ---- | -------------------------------------------------------- |
336| enableVariableFontWeight | boolean | No  | Whether to support variable font weight adjustment.|
337
338## OnDidChangeCallback<sup>12+</sup>
339
340type OnDidChangeCallback = (rangeBefore: TextRange, rangeAfter: TextRange) => void
341
342Represents the callback invoked after text changes.
343
344**Parameters**
345
346| Name| Type| Mandatory| Description|
347| -- | -- | -- | -- |
348| rangeBefore | [TextRange](#textrange12) | Yes| Range of the text to be changed.|
349| rangeAfter | [TextRange](#textrange12) | Yes| Range of the text added.|
350
351## StyledStringChangedListener<sup>12+</sup>
352
353Defines the listener for changes of the styled string text content.
354
355**Atomic service API**: This API can be used in atomic services since API version 12.
356
357**System capability**: SystemCapability.ArkUI.ArkUI.Full
358
359| Name| Type| Mandatory| Description|
360| -- | -- | -- | -- |
361| onWillChange | Callback<[StyledStringChangeValue](ts-basic-components-richeditor.md#styledstringchangevalue12), boolean> | No| Callback invoked when text is about to change.|
362| onDidChange | [OnDidChangeCallback](#ondidchangecallback12) | No| Callback invoked when text is changed.|
363
364## StyledStringChangeValue<sup>12+</sup>
365
366Describes the text changes of the styled string.
367
368**Atomic service API**: This API can be used in atomic services since API version 12.
369
370**System capability**: SystemCapability.ArkUI.ArkUI.Full
371
372| Name| Type| Mandatory| Description|
373| -- | -- | -- | -- |
374| range | TextRange | Yes| Range of the styled string to be replaced in the original string.|
375| replacementString | [StyledString](ts-universal-styled-string.md#styledstring) | Yes| Styled string used for replacement.|
376