1# @ohos.graphics.text (Text)
2
3The Text module allows you to create complex text paragraphs, with various text styles, paragraph styles, and line break rules. It then converts the information into layout data that can be efficiently rendered on the screen. This module uses the physical pixel unit, px.
4
5This module provides the following classes:
6
7- [TextStyle](#textstyle): text style, which controls the font type, size, and spacing of the text.
8- [FontCollection](#fontcollection): font manager, which controls various fonts.
9- [ParagraphStyle](#paragraphstyle): paragraph style, which controls the display style of a paragraph.
10- [Paragraph](#paragraph): paragraph, which is constructed by calling [build()](#build) in the **ParagraphBuilder** class.
11- [ParagraphBuilder](#paragraphbuilder): paragraph builder, which controls the generation of different paragraph objects.
12- [TextLine](#textline): carrier of the paragraph text in lines. It is obtained by calling [getTextLines()](#gettextlines) in the **Paragraph** class.
13- [Run](#run): rendering unit used for text typesetting. It is obtained by calling [getGlyphRuns()](#getglyphruns) in the **TextLine** class.
14
15> **NOTE**
16>
17> The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version.
18
19## Modules to Import
20
21```ts
22import { text } from '@kit.ArkGraphics2D';
23```
24
25## TextAlign
26
27Enumerates the text alignment modes.
28
29**System capability**: SystemCapability.Graphics.Drawing
30
31| Name       | Value  | Description                                         |
32| --------- | ---- | ---------------------------------------------- |
33| LEFT      | 0    | Left-aligned.                                 |
34| RIGHT     | 1    | Right-aligned.                                 |
35| CENTER    | 2    | Center-aligned.                                 |
36| JUSTIFY   | 3    | Justified, which means that each line (except the last line) is stretched so that every line has equal width, and the left and right margins are straight.                   |
37| START     | 4    | Aligned with the start position, which depends on [TextDirection](#textdirection).|
38| END       | 5    | Aligned with the end position, which depends on [TextDirection](#textdirection).|
39
40## TextDirection
41
42Enumerates the text directions.
43
44**System capability**: SystemCapability.Graphics.Drawing
45
46| Name    | Value  | Description             |
47| -------- | ---- | ---------------- |
48| RTL      | 0    | Right to left (RTL).|
49| LTR      | 1    | Left to right (LTR).|
50
51## BreakStrategy
52
53Enumerates the text break strategies.
54
55**System capability**: SystemCapability.Graphics.Drawing
56
57| Name         | Value  | Description                                           |
58| ------------- | ---- | ---------------------------------------------- |
59| GREEDY        | 0    | Each line is filled as much as possible during line break. No hyphen is automatically added.          |
60| HIGH_QUALITY  | 1    | Text continuity is preferentially considered during line break. If necessary, hyphens are automatically added.               |
61| BALANCED      | 2    | Each line of a paragraph has the same width. If necessary, hyphens are automatically added.|
62
63## WordBreak
64
65Enumerates the word break types.
66
67**System capability**: SystemCapability.Graphics.Drawing
68
69| Name       | Value  | Description                                                                                                                 |
70| ----------- | ---- | -------------------------------------------------------------------------------------------------------------------- |
71| NORMAL      | 0    | Default mode. Word breaks are allowed between words as appropriate to the relevant language writing systems.                                                                 |
72| BREAK_ALL   | 1    | Word breaks are allowed between any characters for non-CJK text. (CJK means Chinese, Japanese, and Korean.) This value is suitable for Asian text that contains some non-Asian text. For example, it can be used to break consecutive English characters.|
73| BREAK_WORD  | 2    | Works in the same way as **BREAK_ALL**, except that it does not break unbreakable words.                                  |
74
75## Decoration
76
77Describes a text decoration.
78
79**System capability**: SystemCapability.Graphics.Drawing
80
81| Name                     | Type                                                 | Read Only| Optional| Description                                        |
82| ------------------------- | --------------------------------------------------- | ---- | ---- | -------------------------------------------- |
83| textDecoration            | [TextDecorationType](#textdecorationtype)           | Yes  | Yes  | Type of the decoration. The default value is **NONE**.                      |
84| color                     | [common2D.Color](js-apis-graphics-common2D.md#color)| Yes  | Yes  | Color of the decoration. The default value is transparent.                      |
85| decorationStyle           | [TextDecorationStyle](#textdecorationstyle)         | Yes  | Yes  | Style of the decoration. The default value is **SOLID**.                     |
86| decorationThicknessScale  | number                                              | Yes  | Yes  | Ratio of the decoration thickness to the default value. The value is a floating point number. The default value is 1.0.|
87
88## TextDecorationType
89
90Enumerates the text decoration types.
91
92**System capability**: SystemCapability.Graphics.Drawing
93
94| Name          | Value| Description       |
95| -------------- | - | ----------- |
96| NONE           | 0 | No decoration is used.|
97| UNDERLINE      | 1 | An underline is used for decoration.     |
98| OVERLINE       | 2 | An overline is used for decoration.    |
99| LINE_THROUGH   | 3 | A strikethrough is used for decoration.     |
100
101## TextDecorationStyle
102
103Enumerates the text decoration styles.
104
105**System capability**: SystemCapability.Graphics.Drawing
106
107| Name  | Value| Description  |
108| ------ | - | ------ |
109| SOLID  | 0 | Solid style. |
110| DOUBLE | 1 | Double style.|
111| DOTTED | 2 | Dotted style.|
112| DASHED | 3 | Dashed style. |
113| WAVY   | 4 | Wavy style.|
114
115## FontWeight
116
117Enumerates the font weights.
118
119**System capability**: SystemCapability.Graphics.Drawing
120
121| Name | Value| Description  |
122| ----- | - | ------- |
123| W100  | 0 | Font weight W100.|
124| W200  | 1 | Font weight W200.|
125| W300  | 2 | Font weight W300.|
126| W400  | 3 | Font weight W400.|
127| W500  | 4 | Font weight W500.|
128| W600  | 5 | Font weight W600.|
129| W700  | 6 | Font weight W700.|
130| W800  | 7 | Font weight W800.|
131| W900  | 8 | Font weight W900.|
132
133## FontWidth
134
135Enumerates the font widths.
136
137**System capability**: SystemCapability.Graphics.Drawing
138
139| Name            | Value| Description      |
140| ---------------- | - | ---------- |
141| ULTRA_CONDENSED  | 1 | Ultra condensed. |
142| EXTRA_CONDENSED  | 2 | Extra condensed. |
143| CONDENSED        | 3 | Condensed. |
144| SEMI_CONDENSED   | 4 | Semi condensed. |
145| NORMAL           | 5 | Normal. |
146| SEMI_EXPANDED    | 6 | Semi expanded. |
147| EXPANDED         | 7 | Expanded. |
148| EXTRA_EXPANDED   | 8 | Extra expanded. |
149| ULTRA_EXPANDED   | 9 | Ultra expanded.|
150
151## FontStyle
152
153Enumerates the font styles.
154
155**System capability**: SystemCapability.Graphics.Drawing
156
157| Name   | Value| Description                                                |
158| ------- | - | ---------------------------------------------------- |
159| NORMAL  | 0 | Normal.                                           |
160| ITALIC  | 1 | Italic. If no italic version is available for the current font, the oblique version will be used instead. |
161| OBLIQUE | 2 | Oblique. If no oblique version is available for the current font, the italic version will be used instead.|
162
163## TextHeightBehavior
164
165Enumerates the text height modifier patterns.
166
167**System capability**: SystemCapability.Graphics.Drawing
168
169| Name                 |  Value| Description                                                 |
170| --------------------- | --- | ---------------------------------------------------- |
171| ALL                   | 0x0 | Enables ascent for the first and last rows of a paragraph.           |
172| DISABLE_FIRST_ASCENT  | 0x1 | Disables ascent for the first row of a paragraph.                  |
173| DISABLE_LAST_ASCENT   | 0x2 | Disables ascent for the last row of a paragraph.                |
174| DISABLE_ALL           | 0x3 | Disables ascent for the first and last rows of a paragraph.         |
175
176## TextBaseline
177
178Enumerates the text baseline types.
179
180**System capability**: SystemCapability.Graphics.Drawing
181
182| Name       | Value| Description|
183| ----------- | - | ---- |
184| ALPHABETIC  | 0 | Alphabetic baseline, where the letters in Latin alphabets sit on.|
185| IDEOGRAPHIC | 1 | Ideographic baseline, where the baseline is at the bottom of the text area. It is usually used for CJK text.|
186
187## EllipsisMode
188
189Enumerates the ellipsis styles.
190
191**EllipsisMode.START** and **EllipsisMode.MIDDLE** take effect only when text overflows in a single line.
192
193**System capability**: SystemCapability.Graphics.Drawing
194
195| Name  | Value| Description     |
196| ------ | - | --------- |
197| START  | 0 | Places the ellipsis in the text header.|
198| MIDDLE | 1 | Places the ellipsis in the middle of the text.|
199| END    | 2 | Places the ellipsis at the end of the text.|
200
201## TextShadow
202
203Describes the text shadow.
204
205**System capability**: SystemCapability.Graphics.Drawing
206
207| Name         | Type                                                | Read Only| Optional| Description                              |
208| ------------- | ---------------------------------------------------- | --  | ---  | --------------------------------- |
209| color         | [common2D.Color](js-apis-graphics-common2D.md#color) | Yes |  Yes  | Color of the text shadow. The default value is black (255, 0, 0, 0).       |
210| point         | [common2D.Point](js-apis-graphics-common2D.md#point12) | Yes |  Yes  | Position of the text shadow relative to the text. The horizontal and vertical coordinates must be greater than or equal to 0.   |
211| blurRadius    | number                                               | Yes |  Yes  | Blur radius. The value is a floating point number. The default value is **0.0px**.      |
212
213## RectStyle
214
215Describes the style of a rectangle.
216
217**System capability**: SystemCapability.Graphics.Drawing
218
219| Name              | Type                                                | Read Only| Optional| Description                                     |
220| -----------------  | ---------------------------------------------------- | --  | ---  | ---------------------------------------- |
221| color              | [common2D.Color](js-apis-graphics-common2D.md#color) | Yes |  No  | Color of the rectangle.                |
222| leftTopRadius      | number                                               | Yes |  No  | Left top radius of the rectangle.      |
223| rightTopRadius     | number                                               | Yes |  No  | Right top radius of the rectangle.      |
224| rightBottomRadius  | number                                               | Yes |  No  | Right bottom radius of the rectangle.      |
225| leftBottomRadius   | number                                               | Yes |  No  | Left bottom radius of the rectangle.      |
226
227## FontFeature
228
229Describes a font feature.
230
231**System capability**: SystemCapability.Graphics.Drawing
232
233| Name     | Type                                                | Read Only| Optional| Description                                      |
234| --------- | ---------------------------------------------------- | --  | ---  | ----------------------------------------- |
235| name      | string                                               | Yes |  No  | String identified by the keyword in the font feature key-value pair.      |
236| value     | number                                               | Yes |  No  | Value in the font feature key-value pair.                       |
237
238## FontVariation
239
240Describes a font variation.
241
242**System capability**: SystemCapability.Graphics.Drawing
243
244| Name     | Type                                                | Read Only| Optional| Description                                      |
245| --------- | ---------------------------------------------------- | --  | ---  | ----------------------------------------- |
246| axis      | string                                               | Yes |  No  | String identified by the keyword in the font variation key-value pair.      |
247| value     | number                                               | Yes |  No  | Value in the font variation key-value pair.                       |
248
249## TextStyle
250
251Describes a text style.
252
253**System capability**: SystemCapability.Graphics.Drawing
254
255| Name                     | Type                                    | Read Only| Optional| Description                                                  |
256| ------------- | ---------------------------------------------------- | -- | -- | --------------------------------------------------------- |
257| decoration    | [Decoration](#decoration)                            | Yes| Yes| Text decoration. The default value is the initial decoration.            |
258| color         | [common2D.Color](js-apis-graphics-common2D.md#color) | Yes| Yes| Font color. The default color is white.                        |
259| fontWeight    | [FontWeight](#fontweight)                            | Yes| Yes| Font weight. The default value is **W400**.                         |
260| fontStyle     | [FontStyle](#fontstyle)                              | Yes| Yes| Font style. The default value is **NORMAL**.                         |
261| baseline      | [TextBaseline](#textbaseline)                        | Yes| Yes| Text baseline type. The default value is **ALPHABETIC**.              |
262| fontFamilies  | Array\<string>                                       | Yes| Yes| List of font families. By default, the list corresponds to the system's default fonts.                   |
263| fontSize      | number                                               | Yes| Yes| Font size, in units of px. The value is a floating point number. The default value is **14.0**.  |
264| letterSpacing | number                                               | Yes| Yes| Letter spacing, in units of px. The value is a floating point number. The default value is **0.0**. A positive value causes characters to spread farther apart, and a negative value bring characters closer together.|
265| wordSpacing   | number                                               | Yes| Yes| Word spacing, in units of px. The value is a floating point number. The default value is **0.0**.                |
266| heightScale   | number                                               | Yes| Yes| Scale factor of the line height. The value is a floating point number. The default value is **1.0**. This parameter is valid only when **heightOnly** is set to** true**.              |
267| heightOnly    | boolean                                              | Yes| Yes| How the height of the text box is set. The value **true** means that the height of the text box is set based on the font size and the value of **heightScale**, and **false** means that the height is set based on the line height and line spacing. The default value is **false**.|
268| halfLeading   | boolean                                              | Yes| Yes| Whether half leading is enabled. Half leading is the leading split in half and applied equally to the top and bottom edges. The value **true** means that half leading is enabled, and **false** means the opposite. The default value is **false**.|
269| ellipsis      | string                                               | Yes| Yes| Ellipsis content, which will be used to replace the extra content.      |
270| ellipsisMode  | [EllipsisMode](#ellipsismode)                        | Yes| Yes| Ellipsis type. The default value is **END**, indicating that the ellipsis is at the end of a line.                       |
271| locale        | string                                               | Yes| Yes| Locale. For example, **'en'** indicates English, **'zh-Hans'** indicates Simplified Chinese, and **'zh-Hant'** indicates Traditional Chinese. For details, see ISO 639-1. The default value is an empty string.|
272| baselineShift | number                                               | Yes| Yes| Shift of the baseline. The value is a floating point number. The default value is **0.0px**.                |
273| fontFeatures  | Array\<[FontFeature](#fontfeature)>                  | Yes| Yes| Array of font features.|
274| fontVariations| Array\<[FontVariation](#fontvariation)>              | Yes| Yes| Array of font variations.|
275| textShadows   | Array\<[TextShadow](#textshadow)>                    | Yes| Yes| Array of text shadows.|
276| backgroundRect| [RectStyle](#rectstyle)                              | Yes| Yes| Rectangle style.|
277
278## StrutStyle
279
280Describes the strut style, which determines the line spacing, baseline alignment mode, and other properties related to the line height when drawing texts. The strut style is disabled by default.
281
282**System capability**: SystemCapability.Graphics.Drawing
283
284| Name                     | Type                                      | Read Only| Optional| Description                                                                |
285| -------------  | ---------------------------------------------------- | ---- | -- | --------------------------------------------------------------------- |
286| fontFamilies   | Array\<string>                                       | Yes  | Yes| Font families. The default value is the system fonts.                                              |
287| fontStyle      | [FontStyle](#fontstyle)                              | Yes  | Yes| Font style. The default value is **NORMAL**.                                              |
288| fontWidth      | [FontWidth](#fontwidth)                              | Yes  | Yes| Font width. The default value is **NORMAL**.                                               |
289| fontWeight     | [FontWeight](#fontweight)                            | Yes  | Yes| Font weight. The default value is **W400**.                                                     |
290| fontSize       | number                                               | Yes  | Yes| Font size, in units of px. The value is a floating point number. The default value is **14.0**.                             |
291| height         | number                                               | Yes  | Yes| Scale factor of the line height. The value is a floating point number. The default value is **1.0**.                                        |
292| leading        | number                                               | Yes  | Yes| Custom leading to be applied to the strut. The value is a floating point number. The default value is **-1.0**.                         |
293| forceHeight    | boolean                                              | Yes  | Yes| Whether to forcibly use the strut height for all lines. The value **true** means to forcibly use the strut height for all lines, and **false** means the opposite. The default value is **false**.    |
294| enabled        | boolean                                              | Yes  | Yes| Whether to enable the strut style. The value **true** means to enable the strut style, and **false** means the opposite. The default value is **false**.             |
295| heightOverride | boolean                                              | Yes  | Yes| Whether to override the height. The value **true** means to override the height, and **false** means the opposite. The default value is **false**.                 |
296| halfLeading    | boolean                                              | Yes  | Yes| Whether half leading is enabled. Half leading is the leading split in half and applied equally to the top and bottom edges. The value **true** means that half leading is enabled, and **false** means the opposite. The default value is **false**.          |
297
298## FontCollection
299
300Implements a font manager.
301
302### getGlobalInstance
303
304static getGlobalInstance(): FontCollection
305
306Obtains a global **FontCollection** instance.
307
308**System capability**: SystemCapability.Graphics.Drawing
309
310**Return value**
311
312| Type  | Description               |
313| ------ | ------------------ |
314| [FontCollection](#fontcollection) | **FontCollection** instance.|
315
316**Example**
317
318```ts
319import { text } from "@kit.ArkGraphics2D"
320
321function textFunc() {
322  let fontCollection = text.FontCollection.getGlobalInstance();
323}
324
325@Entry
326@Component
327struct Index {
328  fun: Function = textFunc;
329  build() {
330    Column() {
331      Button().onClick(() => {
332        this.fun();
333      })
334    }
335  }
336}
337```
338
339### loadFontSync
340
341loadFontSync(name: string, path: string | Resource): void
342
343Loads a font from a file in the specified path. This API returns the result synchronously. In this API, **name** specifies the alias of the font, and the custom font effect can be displayed only when the value of **name** is set in **fontFamilies** in **[TextStyle](#textstyle)**. The supported font file formats are .ttf and .otf.
344
345**System capability**: SystemCapability.Graphics.Drawing
346
347**Parameters**
348
349| Name| Type              | Mandatory| Description                             |
350| ----- | ------------------ | ---- | --------------------------------------------------------------------------------- |
351| name  | string             | Yes  | Name of the font.                                               |
352| path  | string \| [Resource](../apis-arkui/arkui-ts/ts-types.md#resource) | Yes  | Path of the font file to import. The value must be **file://***absolute path of the font file* or **rawfile/***directory or file name*.|
353
354**Example**
355
356```ts
357import { text } from "@kit.ArkGraphics2D"
358
359let fontCollection: text.FontCollection = new text.FontCollection();
360
361@Entry
362@Component
363struct RenderTest {
364  LoadFontSyncTest() {
365    fontCollection.loadFontSync('Clock_01', 'file:///system/fonts/HarmonyClock_01.ttf')
366    let fontFamilies: Array<string> = ["Clock_01"]
367    let myTextStyle: text.TextStyle = {
368      fontFamilies: fontFamilies
369    };
370    let myParagraphStyle: text.ParagraphStyle = {
371      textStyle: myTextStyle,
372    }
373    let paragraphBuilder: text.ParagraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection);
374
375    let textData = "Test loadFontSync to load the font HarmonyClock_01.ttf."
376    paragraphBuilder.addText(textData);
377    let paragraph: text.Paragraph = paragraphBuilder.build();
378    paragraph.layoutSync(600);
379  }
380
381  aboutToAppear() {
382    this.LoadFontSyncTest();
383  }
384
385  build() {
386  }
387}
388```
389
390### clearCaches
391
392clearCaches(): void
393
394Clears the font cache.
395
396The font cache has a memory limit and a clearing mechanism. It occupies limited memory. You are not advised to clear it unless otherwise required.
397
398**System capability**: SystemCapability.Graphics.Drawing
399
400**Example**
401
402```ts
403import { text } from "@kit.ArkGraphics2D"
404
405@Entry
406@Component
407struct Index {
408  build() {
409    Column() {
410      Button().onClick(() => {
411        text.FontCollection.getGlobalInstance().clearCaches();
412      })
413    }
414  }
415}
416```
417
418## ParagraphStyle
419
420Describes a paragraph style.
421
422**System capability**: SystemCapability.Graphics.Drawing
423
424| Name                | Type                                       | Read Only| Optional| Description                                         |
425| -------------------- | ------------------------------------------ | ---- | ---- | -------------------------------------------- |
426| textStyle            | [TextStyle](#textstyle)                    | Yes  | Yes  | Text style applied to the paragraph. The default value is the initial text style.|
427| textDirection        | [TextDirection](#textdirection)            | Yes  | Yes  | Text direction. The default value is **LTR**.                         |
428| align                | [TextAlign](#textalign)                    | Yes  | Yes  | Text alignment mode. The default value is **START**.                    |
429| wordBreak            | [WordBreak](#wordbreak)                    | Yes  | Yes  | Word break type. The default value is **BREAK_WORD**.                   |
430| maxLines             | number                                     | Yes  | Yes  | Maximum number of lines. The value is an integer. The default value is **1e9**.                 |
431| breakStrategy        | [BreakStrategy](#breakstrategy)            | Yes  | Yes  | Text break strategy. The default value is **GREEDY**.                       |
432| strutStyle           | [StrutStyle](#strutstyle)                  | Yes  | Yes  | Strut style. The default value is the initial **StrutStyle** object.              |
433| textHeightBehavior   | [TextHeightBehavior](#textheightbehavior)  | Yes  | Yes  | Text height modifier pattern. The default value is **ALL**.                             |
434
435
436## PlaceholderAlignment
437
438Enumerates the vertical alignment modes of a placeholder relative to the surrounding text.
439
440**System capability**: SystemCapability.Graphics.Drawing
441
442| Name               | Value| Description                  |
443| ------------------- | - | ---------------------- |
444| OFFSET_AT_BASELINE  | 0 | Aligns the baseline of the placeholder to the baseline of the text.    |
445| ABOVE_BASELINE      | 1 | Aligns the bottom edge of the placeholder to the baseline of the text.  |
446| BELOW_BASELINE      | 2 | Aligns the top edge of the placeholder to the baseline of the text.  |
447| TOP_OF_ROW_BOX      | 3 | Aligns the top edge of the placeholder to the bottom edge of the text.  |
448| BOTTOM_OF_ROW_BOX   | 4 | Aligns the bottom edge of the placeholder to the bottom edge of the text.  |
449| CENTER_OF_ROW_BOX   | 5 | Aligns the middle of the placeholder to the middle of the text.|
450
451![image_PlaceholderAlignment.png](figures/image_PlaceholderAlignment.png)
452
453> **NOTE**
454>
455> The preceding figure shows only the last three alignment modes. The first three alignment modes are similar. The only difference is that the comparison position changes to the text baseline, which is the green line shown below.
456>
457>![image_Baseline.png](figures/image_Baseline.png)
458
459## PlaceholderSpan
460
461Describes the carrier of a placeholder style.
462
463**System capability**: SystemCapability.Graphics.Drawing
464
465| Name          | Type                                          | Read Only| Optional| Description                        |
466| -------------- | --------------------------------------------- | ---- | --- | --------------------------- |
467| width          | number                                        | Yes  | No  | Width of the placeholder, in units of px. The value is a floating point number.|
468| height         | number                                        | Yes  | No  | Height of the placeholder, in units of px. The value is a floating point number.|
469| align          | [PlaceholderAlignment](#placeholderalignment) | Yes  | No  | Vertical alignment of the placeholder relative to the surrounding text.|
470| baseline       | [TextBaseline](#textbaseline)                 | Yes  | No  | Type of the text baseline.                  |
471| baselineOffset | number                                        | Yes  | No  | Offset to the text baseline, in units of px. The value is a floating point number. |
472
473## Range
474
475Describes a left-closed and right-open interval.
476
477**System capability**: SystemCapability.Graphics.Drawing
478
479| Name  | Type  | Read Only| Optional| Description           |
480| ----- | ------ | ---- | --- | --------------- |
481| start | number | Yes  | No  | Index of the leftmost point of the interval. The value is an integer.|
482| end   | number | Yes  | No  | Index of the rightmost point of the interval. The value is an integer.|
483
484## Paragraph
485
486Implements a carrier that stores the text content and style. You can perform operations such as typography and drawing.
487
488Before calling any of the following APIs, you must use [build()](#build) of the [ParagraphBuilder](#paragraphbuilder) class to create a **Paragraph** object.
489
490### layoutSync
491
492layoutSync(width: number): void
493
494Performs typography and calculates the positions of all glyphs.
495
496**System capability**: SystemCapability.Graphics.Drawing
497
498**Parameters**
499
500| Name| Type  | Mandatory| Description          |
501| ----- | ------ | ---- | -------------- |
502| width | number | Yes  | Maximum width of a single line, in units of px. The value is a floating point number.|
503
504**Example**
505
506```ts
507paragraph.layoutSync(100);
508```
509
510### paint
511
512paint(canvas: drawing.Canvas, x: number, y: number): void
513
514Paints the text on the canvas with the coordinate point (x, y) as the upper left corner.
515
516**System capability**: SystemCapability.Graphics.Drawing
517
518**Parameters**
519
520| Name| Type                                                 | Mandatory| Description                   |
521| ------ | ---------------------------------------------------- | ---- | ---------------------- |
522| canvas | [drawing.Canvas](js-apis-graphics-drawing.md#canvas) | Yes  | Target canvas.        |
523|    x   | number                                               | Yes  | X coordinate of the upper left corner. The value is a floating point number.|
524|    y   | number                                               | Yes  | Y coordinate of the upper left corner. The value is a floating point number.|
525
526**Example**
527
528```ts
529const color: ArrayBuffer = new ArrayBuffer(160000);
530let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 200, width: 200 } }
531let pixelMap: image.PixelMap = image.createPixelMapSync(color, opts);
532let canvas = new drawing.Canvas(pixelMap);
533paragraph.paint(canvas, 0, 0);
534```
535
536### paintOnPath
537
538paintOnPath(canvas: drawing.Canvas, path: drawing.Path, hOffset: number, vOffset: number): void
539
540Draws text along a path on the canvas.
541
542**System capability**: SystemCapability.Graphics.Drawing
543
544**Parameters**
545
546| Name| Type                                                 | Mandatory| Description                   |
547| ------ | ---------------------------------------------------- | ---- | ---------------------- |
548| canvas | [drawing.Canvas](js-apis-graphics-drawing.md#canvas) | Yes  | Target canvas.        |
549| path | [drawing.Path](js-apis-graphics-drawing.md#path) | Yes  | Path along which the text is drawn.        |
550|    hOffset   | number                                               | Yes  | Horizontal offset along the path direction. A positive number indicates a position that is ahead along the path from its start point, and a negative number indicates a position that is behind from the start point.|
551|    vOffset   | number                                               | Yes  | Vertical offset along the path direction. A positive number indicates a position on the left side of the path, and a negative number indicates a position on the right side of the path.|
552
553**Example**
554
555```ts
556const color: ArrayBuffer = new ArrayBuffer(160000);
557let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 200, width: 200 } }
558let pixelMap: image.PixelMap = image.createPixelMapSync(color, opts);
559let canvas = new drawing.Canvas(pixelMap);
560let path = new drawing.Path();
561path.arcTo(20, 20, 180, 180, 180, 90);
562paragraph.paintOnPath(canvas, path, 0, 0);
563```
564
565### getMaxWidth
566
567getMaxWidth(): number
568
569Obtains the maximum width of the line in the text.
570
571**System capability**: SystemCapability.Graphics.Drawing
572
573**Return value**
574
575| Type  | Description      |
576| ------ | --------- |
577| number | Maximum line width, in units of px. The value is a floating point number.|
578
579**Example**
580
581```ts
582let maxWidth = paragraph.getMaxWidth();
583```
584
585### getHeight
586
587getHeight(): number
588
589Obtains the total height of the text.
590
591**System capability**: SystemCapability.Graphics.Drawing
592
593**Return value**
594
595| Type  | Description  |
596| ------ | ----- |
597| number | Total height, in units of px. The value is a floating point number.|
598
599**Example**
600
601```ts
602let height = paragraph.getHeight();
603```
604
605### getLongestLine
606
607getLongestLine(): number
608
609Obtains the longest line in the text.
610
611**System capability**: SystemCapability.Graphics.Drawing
612
613**Return value**
614
615| Type  | Description          |
616| ------ | ------------- |
617| number | Longest line, in units of px. The value is a floating point number.|
618
619**Example**
620
621```ts
622let longestLine = paragraph.getLongestLine();
623```
624
625### getLongestLineWithIndent<sup>13+</sup>
626
627getLongestLineWithIndent(): number
628
629Obtains the width of the longest line, including its indentation, in the text. You are advised to round up the return value in actual use. If the text content is empty, **0** is returned.
630
631**System capability**: SystemCapability.Graphics.Drawing
632
633**Return value**
634
635| Type  | Description          |
636| ------ | ------------- |
637| number | Width of the longest line, including its indentation. The value is a floating point number, in px.|
638
639**Example**
640
641```ts
642let longestLineWithIndent = paragraph.getLongestLineWithIndent();
643```
644
645### getMinIntrinsicWidth
646
647getMinIntrinsicWidth(): number
648
649Obtains the minimum intrinsic width of the paragraph.
650
651**System capability**: SystemCapability.Graphics.Drawing
652
653**Return value**
654
655| Type  | Description                          |
656| ------ | ----------------------------- |
657| number | Minimum intrinsic width, in units of px. The value is a floating point number.|
658
659**Example**
660
661```ts
662let minIntrinsicWidth = paragraph.getMinIntrinsicWidth();
663```
664
665### getMaxIntrinsicWidth
666
667getMaxIntrinsicWidth(): number
668
669Obtains the maximum intrinsic width of the paragraph.
670
671**System capability**: SystemCapability.Graphics.Drawing
672
673**Return value**
674
675| Type  | Description                          |
676| ------ | ----------------------------- |
677| number | Maximum intrinsic width, in units of px. The value is a floating point number.|
678
679**Example**
680
681```ts
682let maxIntrinsicWidth = paragraph.getMaxIntrinsicWidth();
683```
684
685### getAlphabeticBaseline
686
687getAlphabeticBaseline(): number
688
689Obtains the alphabetic baseline.
690
691**System capability**: SystemCapability.Graphics.Drawing
692
693**Return value**
694
695| Type  | Description               |
696| ------ | ------------------ |
697| number | Alphabetic baseline, in units of px. The value is a floating point number.|
698
699**Example**
700
701```ts
702let alphabeticBaseline = paragraph.getAlphabeticBaseline();
703```
704
705### getIdeographicBaseline
706
707getIdeographicBaseline(): number
708
709Obtains the ideographic baseline.
710
711**System capability**: SystemCapability.Graphics.Drawing
712
713**Return value**
714
715| Type  | Description                 |
716| ------ | -------------------- |
717| number | Ideographic baseline, in units of px. The value is a floating point number.|
718
719**Example**
720
721```ts
722let ideographicBaseline = paragraph.getIdeographicBaseline();
723```
724
725### getRectsForRange
726
727getRectsForRange(range: Range, widthStyle: RectWidthStyle, heightStyle: RectHeightStyle): Array\<TextBox>
728
729Obtains the rectangles occupied by the characters in the range of the text under the given rectangle width and height.
730
731**System capability**: SystemCapability.Graphics.Drawing
732
733**Parameters**
734
735| Name     | Type                                | Mandatory| Description                    |
736| ----------- | ----------------------------------- | ---- | ------------------------ |
737| range       | [Range](#range)                     | Yes  | Range of the text. |
738| widthStyle  | [RectWidthStyle](#rectwidthstyle)   | Yes  | Width of the rectangle.|
739| heightStyle | [RectHeightStyle](#rectheightstyle) | Yes  | Height of the rectangle.|
740
741**Return value**
742
743| Type                        | Description       |
744| --------------------------- | ----------- |
745| Array\<[TextBox](#textbox)> | Array holding the rectangles obtained.|
746
747**Example**
748
749```ts
750let range: text.Range = { start: 0, end: 1};
751let rects = paragraph.getRectsForRange(range, text.RectWidthStyle.TIGHT, text.RectHeightStyle.TIGHT);
752```
753
754### getRectsForPlaceholders
755
756getRectsForPlaceholders(): Array\<TextBox>
757
758Obtains the rectangles occupied by all placeholders in the text.
759
760**System capability**: SystemCapability.Graphics.Drawing
761
762**Return value**
763
764| Type                        | Description       |
765| --------------------------- | ----------- |
766| Array\<[TextBox](#textbox)> | Array holding the rectangles obtained.|
767
768**Example**
769
770```ts
771let placeholderRects = paragraph.getRectsForPlaceholders();
772```
773
774### getGlyphPositionAtCoordinate
775
776getGlyphPositionAtCoordinate(x: number, y: number): PositionWithAffinity
777
778Obtains the position of a glyph close to a given coordinate.
779
780**System capability**: SystemCapability.Graphics.Drawing
781
782**Parameters**
783
784| Name| Type  | Mandatory| Description  |
785| ----- | ------ | ---- | ------ |
786| x     | number | Yes  | X coordinate. The value is a floating point number.|
787| y     | number | Yes  | Y coordinate. The value is a floating point number.|
788
789**Return value**
790
791| Type                                         | Description       |
792| --------------------------------------------- | ----------- |
793| [PositionWithAffinity](#positionwithaffinity) | Position of the glyph.|
794
795**Example**
796
797```ts
798let positionWithAffinity = paragraph.getGlyphPositionAtCoordinate(0, 0);
799```
800
801### getWordBoundary
802
803getWordBoundary(offset: number): Range
804
805Obtains the range of the word where the glyph with a given offset is located.
806
807**System capability**: SystemCapability.Graphics.Drawing
808
809**Parameters**
810
811| Name| Type   | Mandatory| Description       |
812| ------ | ------ | ---- | ----------- |
813| offset | number | Yes  | Offset of the glyph. The value is an integer.|
814
815**Return value**
816
817| Type           | Description           |
818| --------------- | -------------- |
819| [Range](#range) | Range of the word.|
820
821**Example**
822
823```ts
824let wordRange = paragraph.getWordBoundary(0);
825```
826
827### getLineCount
828
829getLineCount(): number
830
831Obtains the number of text lines.
832
833**System capability**: SystemCapability.Graphics.Drawing
834
835**Return value**
836
837| Type  | Description      |
838| ------ | --------- |
839| number | Number of text lines. The value is an integer.|
840
841**Example**
842
843```ts
844let lineCount = paragraph.getLineCount();
845```
846
847### getLineHeight
848
849getLineHeight(line: number): number
850
851Obtains the height of a given line.
852
853**System capability**: SystemCapability.Graphics.Drawing
854
855**Parameters**
856
857| Name| Type  | Mandatory| Description     |
858| ----- | ------ | ---- | --------- |
859| line  | number | Yes  | Index of the line. The value is an integer.|
860
861**Return value**
862
863| Type  | Description |
864| ------ | ---- |
865| number | Line height.|
866
867**Example**
868
869```ts
870let lineHeight = paragraph.getLineHeight(0);
871```
872
873### getLineWidth
874
875getLineWidth(line: number): number
876
877Obtains the width of a given line.
878
879**System capability**: SystemCapability.Graphics.Drawing
880
881**Parameters**
882
883| Name| Type  | Mandatory| Description     |
884| ----- | ------ | ---- | --------- |
885| line  | number | Yes  | Index of the line. The value is an integer.|
886
887**Return value**
888
889| Type  | Description |
890| ------ | ---- |
891| number | Line width.|
892
893**Example**
894
895```ts
896let lineWidth = paragraph.getLineWidth(0);
897```
898
899### didExceedMaxLines
900
901didExceedMaxLines(): boolean
902
903Checks whether the number of lines in the paragraph exceeds the maximum.
904
905**System capability**: SystemCapability.Graphics.Drawing
906
907**Return value**
908
909| Type   | Description                                                     |
910| ------- | -------------------------------------------------------- |
911| boolean | **true**: The number of lines exceeds the maximum.<br>**false**: The number of lines does not exceed the maximum.|
912
913**Example**
914
915```ts
916let didExceed = paragraph.didExceedMaxLines();
917```
918
919### getTextLines
920
921getTextLines(): Array\<TextLine>
922
923Obtains all the text lines.
924
925**System capability**: SystemCapability.Graphics.Drawing
926
927**Return value**
928
929| Type                         | Description         |
930| ----------------------------- | ------------- |
931| Array\<[TextLine](#textline)> | Array of text lines.|
932
933**Example**
934
935```ts
936let lines = paragraph.getTextLines();
937```
938
939### getActualTextRange
940
941getActualTextRange(lineNumber: number, includeSpaces: boolean): Range
942
943Obtains the actually visible text range in the specified line, excluding the ellipsis displayed due to text overflow.
944
945**System capability**: SystemCapability.Graphics.Drawing
946
947**Parameters**
948
949| Name| Type  | Mandatory| Description     |
950| ----- | ------ | ---- | --------- |
951| lineNumber  | number | Yes  | Line number of the text range, starting from 0.|
952| includeSpaces  | boolean | Yes  | Whether spaces are included. The value **true** means that spaces are contained, and **false** means the opposite.|
953
954**Return value**
955
956| Type            | Description                                             |
957| ---------------- | ------------------------------------------------ |
958| [Range](#range)  | Text range obtained.                              |
959
960**Example**
961
962```ts
963let rang = paragraph.getActualTextRange(0, true);
964```
965
966
967### getLineMetrics
968
969getLineMetrics(): Array\<LineMetrics>
970
971Obtains an array of line measurement information.
972
973**System capability**: SystemCapability.Graphics.Drawing
974
975**Return value**
976
977| Type                         | Description         |
978| ----------------------------- | ------------- |
979| Array\<[LineMetrics](#linemetrics)> | Array of line measurement information.|
980
981**Example**
982
983```ts
984let arrLineMetrc =  paragraph.getLineMetrics();
985```
986
987### getLineMetrics
988
989getLineMetrics(lineNumber: number): LineMetrics | undefined
990
991Obtains the line measurement information of a line.
992
993**System capability**: SystemCapability.Graphics.Drawing
994
995**Parameters**
996
997| Name| Type  | Mandatory| Description     |
998| ----- | ------ | ---- | --------- |
999| lineNumber  | number | Yes  | Line number, starting from 0.|
1000
1001**Return value**
1002
1003| Type            | Description                                             |
1004| ---------------- | ------------------------------------------------ |
1005| [LineMetrics](#linemetrics) | **LineMetrics** object containing the measurement information if the specified line number is valid and the measurement information exists. If the line number is invalid or the measurement information cannot be obtained, **undefined** is returned.                 |
1006
1007**Example**
1008
1009```ts
1010let lineMetrics =  paragraph.getLineMetrics(0);
1011```
1012
1013## RunMetrics
1014
1015Describes the layout information and measurement information of a run of text in a text line.
1016
1017**System capability**: SystemCapability.Graphics.Drawing
1018
1019| Name     | Type                                               | Read Only| Optional| Description       |
1020| --------- | -------------------------------------------------- | ---- | ---- | ----------- |
1021| textStyle | [TextStyle](#textstyle)                             | Yes  | No  | Text style.|
1022| fontMetrics | [drawing.FontMetrics](js-apis-graphics-drawing.md#fontmetrics)| Yes  | No  | Font measurement information.   |
1023
1024## LineMetrics
1025
1026Describes the measurement information of a single line of text in the text layout.
1027
1028**System capability**: SystemCapability.Graphics.Drawing
1029
1030| Name     | Type                                               | Read Only| Optional| Description       |
1031| --------- | -------------------------------------------------- | ---- | ---- | ----------- |
1032| startIndex | number                                            | Yes  | No  | Start index of the line in the text buffer.|
1033| endIndex   | number                                            | Yes  | No  | End index of the line in the text buffer.|
1034| ascent     | number                                            | Yes  | No  | Ascent, that is, the distance from the baseline to the top of the character.|
1035| descent    | number                                            | Yes  | No  | Descent, that is, the distance from the baseline to the bottom of the character.|
1036| height     | number                                            | Yes  | No  | Height of the line, which is Math.round(ascent + descent).|
1037| width      | number                                            | Yes  | No  | Width of the line.                     |
1038| left       | number                        | Yes  | No  | Left edge of the line. The right edge is the value of **left** plus the value of **width**.|
1039| baseline   | number                        | Yes  | No  | Y coordinate of the baseline in the line relative to the top of the paragraph.|
1040| lineNumber   | number                        | Yes  | No  | Line number, starting from 0.|
1041| topHeight   | number                        | Yes  | No  | Height from the top to the current line.|
1042| runMetrics   | Map<number, [RunMetrics](#runmetrics)>                        | Yes  | No  | Mapping between the text index range and the associated font measurement information.|
1043
1044## TextBox
1045
1046Describes the rectangle that holds the text.
1047
1048**System capability**: SystemCapability.Graphics.Drawing
1049
1050| Name     | Type                                               | Read Only| Optional| Description       |
1051| --------- | -------------------------------------------------- | ---- | ---- | ----------- |
1052| rect      | [common2D.Rect](js-apis-graphics-common2D.md#rect) | Yes  | No  | Information about the rectangle.|
1053| direction | [TextDirection](#textdirection)                    | Yes  | No  | Text direction.   |
1054
1055## PositionWithAffinity
1056
1057Describes the position and affinity of a glyph.
1058
1059**System capability**: SystemCapability.Graphics.Drawing
1060
1061| Name     | Type                  | Read Only| Optional| Description                     |
1062| --------- | --------------------- | ---- | ---- | ------------------------ |
1063| position  | number                | Yes  | No  | Index of the glyph relative to the paragraph. The value is an integer. |
1064| affinity  | [Affinity](#affinity) | Yes  | No  | Affinity of the position.              |
1065
1066## RectWidthStyle
1067
1068Enumerates the rectangle width styles.
1069
1070**System capability**: SystemCapability.Graphics.Drawing
1071
1072| Name | Value| Description                                  |
1073| ----- | - | -------------------------------------- |
1074| TIGHT | 0 | If **letterSpacing** is not set, the rectangle conforms tightly to the text it contains. However, if **letterSpacing** is set, a gap is introduced between the rectangle and text.                           |
1075| MAX   | 1 | The rectangle's width is extended to align with the widest rectangle across all lines.  |
1076
1077## RectHeightStyle
1078
1079Enumerates the rectangle height styles.
1080
1081**System capability**: SystemCapability.Graphics.Drawing
1082
1083| Name                     | Value| Description                                          |
1084| ------------------------- | - | ---------------------------------------------- |
1085| TIGHT                     | 0 | Tight style.                                   |
1086| MAX                       | 1 | Extends the height to match the highest rectangle in all lines.          |
1087| INCLUDE_LINE_SPACE_MIDDLE | 2 | Includes half of the line spacing to both the top and bottom of the rectangle.|
1088| INCLUDE_LINE_SPACE_TOP    | 3 | Includes the line spacing to the top of the rectangle.                     |
1089| INCLUDE_LINE_SPACE_BOTTOM | 4 | Includes the line spacing to the bottom of the rectangle.                     |
1090| STRUT                     | 5 | Sets the height according to the strut style.                         |
1091
1092## Affinity
1093
1094Enumerates the affinity modes.
1095
1096**System capability**: SystemCapability.Graphics.Drawing
1097
1098| Name      | Value| Description                         |
1099| ---------- | - | ----------------------------- |
1100| UPSTREAM   | 0 | The position has affinity for the upstream side of the text position.|
1101| DOWNSTREAM | 1 | The position has affinity for the downstream side of the text position.|
1102
1103## ParagraphBuilder
1104
1105Implements a paragraph builder.
1106
1107### constructor
1108
1109constructor(paragraphStyle: ParagraphStyle, fontCollection: FontCollection)
1110
1111A constructor used to create a **ParagraphBuilder** object.
1112
1113**System capability**: SystemCapability.Graphics.Drawing
1114
1115**Parameters**
1116
1117| Name        | Type                              | Mandatory| Description       |
1118| -------------- | --------------------------------- | ---- | ----------- |
1119| paragraphStyle | [ParagraphStyle](#paragraphstyle) | Yes  | Paragraph style.  |
1120| fontCollection | [FontCollection](#fontcollection) | Yes  | Font manager.|
1121
1122**Example**
1123
1124```ts
1125import { text } from "@kit.ArkGraphics2D";
1126
1127function textFunc() {
1128  let myTextStyle: text.TextStyle = {
1129    color: { alpha: 255, red: 255, green: 0, blue: 0 },
1130    fontSize: 33,
1131  };
1132  let myParagraphStyle: text.ParagraphStyle = {
1133    textStyle: myTextStyle,
1134    align: text.TextAlign.END,
1135  };
1136  let fontCollection = new text.FontCollection();
1137  let ParagraphGraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection);
1138}
1139
1140@Entry
1141@Component
1142struct Index {
1143  fun: Function = textFunc;
1144  build() {
1145    Column() {
1146      Button().onClick(() => {
1147        this.fun();
1148      })
1149    }
1150  }
1151}
1152```
1153
1154### pushStyle
1155
1156 pushStyle(textStyle: TextStyle): void
1157
1158Pushes a text style.
1159
1160> **NOTE**
1161>
1162> This API pushes the style of the current text blob until [popStyle](#popstyle), which restores to the previous text style, is called.
1163
1164**System capability**: SystemCapability.Graphics.Drawing
1165
1166**Parameters**
1167
1168| Name   | Type      | Mandatory| Description                                                                                                  |
1169| --------- | --------- | ---- | ------------------------------------------------------------------------------------------------------ |
1170| textStyle | [TextStyle](#textstyle) | Yes  | Text style, which describes various visual attributes of text, such as font, font size, color, font weight, word spacing, line spacing, decoration (such as underline and strikethrough), and text shadow.|
1171
1172**Example**
1173
1174```ts
1175import { drawing } from '@kit.ArkGraphics2D'
1176import { text } from "@kit.ArkGraphics2D"
1177import { common2D } from "@kit.ArkGraphics2D"
1178import { image } from '@kit.ImageKit';
1179
1180function textFunc() {
1181  let myTextStyle: text.TextStyle = {
1182    color: { alpha: 255, red: 255, green: 0, blue: 0 },
1183    fontSize: 33,
1184  };
1185  let myParagraphStyle: text.ParagraphStyle = {
1186    textStyle: myTextStyle,
1187    align: text.TextAlign.CENTER,
1188  };
1189  let fontCollection = new text.FontCollection();
1190  let ParagraphGraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection);
1191  ParagraphGraphBuilder.pushStyle(myTextStyle);
1192}
1193
1194@Entry
1195@Component
1196struct Index {
1197  fun: Function = textFunc;
1198  build() {
1199    Column() {
1200      Button().onClick(() => {
1201        this.fun();
1202      })
1203    }
1204  }
1205}
1206```
1207
1208### popStyle
1209
1210popStyle(): void
1211
1212Restores to the previous text style.
1213
1214**System capability**: SystemCapability.Graphics.Drawing
1215
1216**Example**
1217
1218```ts
1219import { drawing } from '@kit.ArkGraphics2D'
1220import { text } from "@kit.ArkGraphics2D"
1221import { common2D } from "@kit.ArkGraphics2D"
1222import { image } from '@kit.ImageKit';
1223
1224function textFunc() {
1225  let myTextStyle: text.TextStyle = {
1226    color: { alpha: 255, red: 255, green: 0, blue: 0 },
1227    fontSize: 33,
1228  };
1229  let myParagraphStyle: text.ParagraphStyle = {
1230    textStyle: myTextStyle,
1231    align: text.TextAlign.END,
1232  };
1233  let fontCollection = new text.FontCollection();
1234  let ParagraphGraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection);
1235  ParagraphGraphBuilder.pushStyle(myTextStyle);
1236  ParagraphGraphBuilder.popStyle();
1237}
1238
1239@Entry
1240@Component
1241struct Index {
1242  fun: Function = textFunc;
1243  build() {
1244    Column() {
1245      Button().onClick(() => {
1246        this.fun();
1247      })
1248    }
1249  }
1250}
1251```
1252
1253### addText
1254
1255addText(text: string): void
1256
1257Inserts a text string into the paragraph being built.
1258
1259**System capability**: SystemCapability.Graphics.Drawing
1260
1261**Parameters**
1262
1263| Name  | Type   | Mandatory| Description                      |
1264| ------- | ------- | ---- | -------------------------- |
1265| text    | string  | Yes  | Text string to insert.|
1266
1267**Example**
1268
1269```ts
1270import { drawing } from '@kit.ArkGraphics2D'
1271import { text } from "@kit.ArkGraphics2D"
1272import { common2D } from "@kit.ArkGraphics2D"
1273import { image } from '@kit.ImageKit';
1274
1275function textFunc() {
1276  let myTextStyle: text.TextStyle = {
1277    color: { alpha: 255, red: 255, green: 0, blue: 0 },
1278    fontSize: 33,
1279  };
1280  let myParagraphStyle: text.ParagraphStyle = {
1281    textStyle: myTextStyle,
1282    align: text.TextAlign.END,
1283  };
1284  let fontCollection = new text.FontCollection();
1285  let ParagraphGraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection);
1286  ParagraphGraphBuilder.addText("123666");
1287}
1288
1289@Entry
1290@Component
1291struct Index {
1292  fun: Function = textFunc;
1293  build() {
1294    Column() {
1295      Button().onClick(() => {
1296        this.fun();
1297      })
1298    }
1299  }
1300}
1301```
1302
1303### addPlaceholder
1304
1305addPlaceholder(placeholderSpan: PlaceholderSpan): void
1306
1307Inserts a placeholder into the paragraph being built.
1308
1309**System capability**: SystemCapability.Graphics.Drawing
1310
1311**Parameters**
1312
1313| Name         | Type                                | Mandatory| Description                                               |
1314| --------------- | ----------------------------------- | ---- | --------------------------------------------------- |
1315| placeholderSpan | [PlaceholderSpan](#placeholderspan) | Yes  | Placeholder span, which describes the size, alignment, baseline type, and baseline offset of the placeholder. |
1316
1317**Example**
1318
1319```ts
1320import { drawing } from '@kit.ArkGraphics2D'
1321import { text } from "@kit.ArkGraphics2D"
1322import { common2D } from "@kit.ArkGraphics2D"
1323import { image } from '@kit.ImageKit';
1324
1325function textFunc() {
1326  let myParagraphStyle: text.ParagraphStyle = {
1327    align: text.TextAlign.END,
1328  };
1329  let myPlaceholderSpan: text.PlaceholderSpan = {
1330    width: 10000,
1331    height: 10000000,
1332    align: text.PlaceholderAlignment.ABOVE_BASELINE,
1333    baseline: text.TextBaseline.ALPHABETIC,
1334    baselineOffset: 100000
1335  };
1336  let fontCollection = new text.FontCollection();
1337  let ParagraphGraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection);
1338  ParagraphGraphBuilder.addPlaceholder(myPlaceholderSpan);
1339}
1340
1341@Entry
1342@Component
1343struct Index {
1344  fun: Function = textFunc;
1345  build() {
1346    Column() {
1347      Button().onClick(() => {
1348        this.fun();
1349      })
1350    }
1351  }
1352}
1353```
1354
1355### build
1356
1357build(): Paragraph
1358
1359Creates a paragraph object that can be used for subsequent typography and rendering.
1360
1361**System capability**: SystemCapability.Graphics.Drawing
1362
1363**Return value**
1364
1365| Type                    | Description                          |
1366| ------------------------ | ------------------------------ |
1367| [Paragraph](#paragraph)  | **Paragraph** object that can be used for subsequent typography and rendering.|
1368
1369**Example**
1370
1371```ts
1372import { drawing, text, common2D } from '@kit.ArkGraphics2D'
1373import { image } from '@kit.ImageKit';
1374
1375function textFunc() {
1376  let myParagraphStyle: text.ParagraphStyle = {
1377    align: text.TextAlign.END,
1378  };
1379  let fontCollection = new text.FontCollection();
1380  let ParagraphGraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection);
1381  let paragraph = ParagraphGraphBuilder.build();
1382}
1383
1384@Entry
1385@Component
1386struct Index {
1387  fun: Function = textFunc;
1388  build() {
1389    Column() {
1390      Button().onClick(() => {
1391        this.fun();
1392      })
1393    }
1394  }
1395}
1396```
1397
1398### addSymbol
1399
1400addSymbol(symbolId: number): void
1401
1402Inserts a symbol into the paragraph being built.
1403
1404**System capability**: SystemCapability.Graphics.Drawing
1405
1406**Parameters**
1407
1408| Name   | Type   | Mandatory| Description                                                       |
1409| -------- | ------- | ---- | ----------------------------------------------------------- |
1410| symbolId | number  | Yes  | Symbol code to insert. The value is a hexadecimal number in the range 0xF0000–0xF0C97. For details about the configurable symbol codes and symbol names, see the **value** and **name** fields in the [JSON file](https://gitee.com/openharmony/global_system_resources/blob/master/systemres/main/resources/base/element/symbol.json).|
1411
1412**Example**
1413
1414```ts
1415import { text } from "@kit.ArkGraphics2D";
1416
1417function textFunc() {
1418  let myTextStyle: text.TextStyle = {
1419    color: { alpha: 255, red: 255, green: 0, blue: 0 },
1420    fontSize: 33,
1421  };
1422  let myParagraphStyle: text.ParagraphStyle = {
1423    textStyle: myTextStyle,
1424    align: text.TextAlign.END,
1425  };
1426  let fontCollection = new text.FontCollection();
1427  let ParagraphGraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection);
1428  ParagraphGraphBuilder.addSymbol(0xF0000);
1429  let paragraph = ParagraphGraphBuilder.build();
1430}
1431
1432@Entry
1433@Component
1434struct Index {
1435  fun: Function = textFunc;
1436  build() {
1437    Column() {
1438      Button().onClick(() => {
1439        this.fun();
1440      })
1441    }
1442  }
1443}
1444```
1445
1446## TextLine
1447
1448Implements a carrier that describes the basic text line structure of a paragraph.
1449
1450Before calling any of the following APIs, you must use [getTextLines()](#gettextlines) of the [Paragraph](#paragraph) class to create a **TextLine** object.
1451
1452### getGlyphCount
1453
1454getGlyphCount(): number
1455
1456Obtains the number of glyphs in this text line.
1457
1458**System capability**: SystemCapability.Graphics.Drawing
1459
1460**Return value**
1461
1462| Type   | Description              |
1463| ------- | ------------------ |
1464| number  | Number of glyphs. The value is an integer.|
1465
1466**Example**
1467
1468```ts
1469import { text } from "@kit.ArkGraphics2D"
1470
1471function textFunc() {
1472  let GlyphCount = lines[0].getGlyphCount();
1473}
1474
1475@Entry
1476@Component
1477struct Index {
1478  fun: Function = textFunc;
1479  build() {
1480    Column() {
1481      Button().onClick(() => {
1482        this.fun();
1483      })
1484    }
1485  }
1486}
1487```
1488
1489### getTextRange
1490
1491getTextRange(): Range
1492
1493Obtains the range of the text in this text line in the entire paragraph.
1494
1495**System capability**: SystemCapability.Graphics.Drawing
1496
1497**Return value**
1498
1499| Type            | Description                                             |
1500| ---------------- | ------------------------------------------------ |
1501| [Range](#range)  | Range of the text in this text line in the entire paragraph.|
1502
1503**Example**
1504
1505```ts
1506import { text } from "@kit.ArkGraphics2D"
1507
1508function textFunc() {
1509  let textRange = lines[0].getTextRange();
1510}
1511
1512@Entry
1513@Component
1514struct Index {
1515  fun: Function = textFunc;
1516  build() {
1517    Column() {
1518      Button().onClick(() => {
1519        this.fun();
1520      })
1521    }
1522  }
1523}
1524```
1525
1526### getGlyphRuns
1527
1528getGlyphRuns(): Array\<Run>
1529
1530Obtains the glyph runs in this text line.
1531
1532**System capability**: SystemCapability.Graphics.Drawing
1533
1534**Return value**
1535
1536| Type        | Description                        |
1537| ------------ | --------------------------- |
1538| Array\<[Run](#run)>  | Array of the glyph runs obtained.|
1539
1540**Example**
1541
1542```ts
1543import { text } from "@kit.ArkGraphics2D"
1544
1545function textFunc() {
1546  let runs = lines[0].getGlyphRuns();
1547}
1548
1549@Entry
1550@Component
1551struct Index {
1552  fun: Function = textFunc;
1553  build() {
1554    Column() {
1555      Button().onClick(() => {
1556        this.fun();
1557      })
1558    }
1559  }
1560}
1561```
1562
1563### paint
1564
1565paint(canvas: drawing.Canvas, x: number, y: number): void
1566
1567Paints this text line on the canvas with the coordinate point (x, y) as the upper left corner.
1568
1569**System capability**: SystemCapability.Graphics.Drawing
1570
1571**Parameters**
1572
1573| Name| Type                                                 | Mandatory| Description                   |
1574| ------ | ---------------------------------------------------- | ---- | ---------------------- |
1575| canvas | [drawing.Canvas](js-apis-graphics-drawing.md#canvas) | Yes  | Target canvas.     |
1576|    x   | number                                               | Yes  | X coordinate of the upper left corner. The value is a floating point number.|
1577|    y   | number                                               | Yes  | Y coordinate of the upper left corner. The value is a floating point number.|
1578
1579**Example**
1580
1581```ts
1582import { drawing } from '@kit.ArkGraphics2D'
1583import { text } from "@kit.ArkGraphics2D"
1584import { common2D } from "@kit.ArkGraphics2D"
1585import { image } from '@kit.ImageKit';
1586
1587function textFunc() {
1588  const color: ArrayBuffer = new ArrayBuffer(160000);
1589  let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 200, width: 200 } }
1590  let pixelMap: image.PixelMap = image.createPixelMapSync(color, opts);
1591  let canvas = new drawing.Canvas(pixelMap);
1592  lines[0].paint(canvas, 0, 0);
1593}
1594
1595@Entry
1596@Component
1597struct Index {
1598  fun: Function = textFunc;
1599  build() {
1600    Column() {
1601      Button().onClick(() => {
1602        this.fun();
1603      })
1604    }
1605  }
1606}
1607```
1608
1609## Run
1610
1611Implements a rendering unit for text typesetting.
1612
1613Before calling any of the following APIs, you must use [getGlyphRuns()](#getglyphruns) of the [TextLine](#textline) class to create a **Run** object.
1614
1615### getGlyphCount
1616
1617getGlyphCount(): number
1618
1619Obtains the number of glyphs in this glyph run.
1620
1621**System capability**: SystemCapability.Graphics.Drawing
1622
1623**Return value**
1624
1625| Type    | Description               |
1626| ------- | -------------------- |
1627| number  | Number of glyphs. The value is an integer.|
1628
1629**Example**
1630
1631```ts
1632import { text } from "@kit.ArkGraphics2D"
1633
1634function textFunc() {
1635  let glyphs = runs[0].getGlyphCount();
1636}
1637
1638@Entry
1639@Component
1640struct Index {
1641  fun: Function = textFunc;
1642  build() {
1643    Column() {
1644      Button().onClick(() => {
1645        this.fun();
1646      })
1647    }
1648  }
1649}
1650```
1651
1652### getGlyphs
1653
1654getGlyphs(): Array\<number>
1655
1656Obtains the index of each glyph in this glyph run.
1657
1658**System capability**: SystemCapability.Graphics.Drawing
1659
1660**Return value**
1661
1662| Type           | Description                            |
1663| --------------- | -------------------------------- |
1664| Array\<number>  | Array holding the index of each glyph in this glyph run.|
1665
1666**Example**
1667
1668```ts
1669import { text } from "@kit.ArkGraphics2D"
1670
1671function textFunc() {
1672  let glyph = runs[0].getGlyphs();
1673}
1674
1675@Entry
1676@Component
1677struct Index {
1678  fun: Function = textFunc;
1679  build() {
1680    Column() {
1681      Button().onClick(() => {
1682        this.fun();
1683      })
1684    }
1685  }
1686}
1687```
1688
1689### getPositions
1690
1691getPositions(): Array<common2D.Point>
1692
1693Obtains the index of each glyph relative to the respective line in this glyph run.
1694
1695**System capability**: SystemCapability.Graphics.Drawing
1696
1697**Return value**
1698
1699| Type                  | Description                                  |
1700| ---------------------- | ------------------------------------- |
1701| Array<[common2D.Point](js-apis-graphics-common2D.md#point12)>  | Array holding the index of each glyph relative to the respective line in this glyph run.|
1702
1703**Example**
1704
1705```ts
1706import { text } from "@kit.ArkGraphics2D";
1707
1708function textFunc() {
1709  let positions = runs[0].getPositions();
1710}
1711
1712@Entry
1713@Component
1714struct Index {
1715  fun: Function = textFunc;
1716  build() {
1717    Column() {
1718      Button().onClick(() => {
1719        this.fun();
1720      })
1721    }
1722  }
1723}
1724```
1725
1726### getOffsets
1727
1728getOffsets(): Array<common2D.Point>
1729
1730Obtains the offset of each glyph in this glyph run relative to its index.
1731
1732**System capability**: SystemCapability.Graphics.Drawing
1733
1734**Return value**
1735
1736| Type                  | Description          |
1737| ---------------------- | -------------- |
1738| Array<[common2D.Point](js-apis-graphics-common2D.md#point12)>  | Array holding the offset of each glyph in this glyph run relative to its index.|
1739
1740**Example**
1741
1742```ts
1743import { text } from "@kit.ArkGraphics2D";
1744
1745function textFunc() {
1746  let offsets = runs[0].getOffsets();
1747}
1748
1749@Entry
1750@Component
1751struct Index {
1752  fun: Function = textFunc;
1753  build() {
1754    Column() {
1755      Button().onClick(() => {
1756        this.fun();
1757      })
1758    }
1759  }
1760}
1761```
1762
1763### getFont
1764
1765getFont(): drawing.Font
1766
1767Obtains the **Font** object of this glyph run.
1768
1769**System capability**: SystemCapability.Graphics.Drawing
1770
1771**Return value**
1772
1773| Type                  | Description          |
1774| ------------------------------------------------- | -------------------------- |
1775| [drawing.Font](js-apis-graphics-drawing.md#font)  | **Font** object of this glyph run.|
1776
1777**Example**
1778
1779```ts
1780import { drawing } from '@kit.ArkGraphics2D'
1781import { text } from "@kit.ArkGraphics2D";
1782
1783function textFunc() {
1784  let font = runs[0].getFont();
1785}
1786
1787@Entry
1788@Component
1789struct Index {
1790  fun: Function = textFunc;
1791  build() {
1792    Column() {
1793      Button().onClick(() => {
1794        this.fun();
1795      })
1796    }
1797  }
1798}
1799```
1800
1801### paint
1802
1803paint(canvas: drawing.Canvas, x: number, y: number): void
1804
1805Paints this glyph run on the canvas with the coordinate point (x, y) as the upper left corner.
1806
1807**System capability**: SystemCapability.Graphics.Drawing
1808
1809**Parameters**
1810
1811| Name| Type                                                 | Mandatory| Description                   |
1812| ------ | ---------------------------------------------------- | ---- | ---------------------- |
1813| canvas | [drawing.Canvas](js-apis-graphics-drawing.md#canvas) | Yes  | Target canvas.     |
1814|    x   | number                                               | Yes  | X coordinate of the upper left corner. The value is a floating point number.|
1815|    y   | number                                               | Yes  | Y coordinate of the upper left corner. The value is a floating point number.|
1816
1817**Example**
1818
1819```ts
1820import { drawing } from '@kit.ArkGraphics2D'
1821import { text } from "@kit.ArkGraphics2D"
1822import { common2D } from "@kit.ArkGraphics2D"
1823import { image } from '@kit.ImageKit';
1824
1825function textFunc() {
1826  const color: ArrayBuffer = new ArrayBuffer(160000);
1827  let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 200, width: 200 } }
1828  let pixelMap: image.PixelMap = image.createPixelMapSync(color, opts);
1829  let canvas = new drawing.Canvas(pixelMap);
1830  runs[0].paint(canvas, 0, 0);
1831}
1832
1833@Entry
1834@Component
1835struct Index {
1836  fun: Function = textFunc;
1837  build() {
1838    Column() {
1839      Button().onClick(() => {
1840        this.fun();
1841      })
1842    }
1843  }
1844}
1845```
1846