1# @ohos.graphics.text (文本模块) 2<!--Kit: ArkGraphics 2D--> 3<!--Subsystem: Graphics--> 4<!--Owner: @oh_wangxk; @gmiao522; @Lem0nC--> 5<!--Designer: @liumingxiang--> 6<!--Tester: @yhl0101--> 7<!--Adviser: @ge-yafang--> 8本模块提供一系列用于文本布局和字体管理的编程接口。文本布局相关的接口旨在提供高质量的排版，包括字符到字形的转换、字距调整、换行、对齐、文本测量等。字体管理接口提供字体注册、字体描述符、字体集管理等功能。 9 10该模块提供以下创建复杂样式的文本段落的常用类： 11 12- [TextStyle](#textstyle)：文本样式，控制文本的字体类型、大小、间距等属性。 13- [FontCollection](#fontcollection)：字体集，控制各种不同的字体。 14- [FontDescriptor](#fontdescriptor14)：字体描述符信息。 15- [ParagraphStyle](#paragraphstyle)：段落样式，控制整个段落的断行策略、断词策略等属性。 16- [ParagraphBuilder](#paragraphbuilder)：段落生成器，控制生成不同的段落对象。 17- [Paragraph](#paragraph)：段落，由ParagraphBuilder类调用[build()](#build)接口构建而成。 18- [LineTypeset](#linetypeset18)：行排版器，由ParagraphBuilder类调用[buildLineTypeset()](#buildlinetypeset18)接口构建而成。 19- [TextLine](#textline)：以行为单位的段落文本的载体，由Paragraph类调用[getTextLines()](#gettextlines)接口获取。 20- [Run](#run)：文本排版单元，由TextLine类调用[getGlyphRuns()](#getglyphruns)接口获取。 21 22> **说明：** 23> 24> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 25 26## 导入模块 27 28```ts 29import { text } from '@kit.ArkGraphics2D' 30``` 31 32## text.setTextHighContrast<sup>20+</sup> 33 34setTextHighContrast(action: TextHighContrast): void 35 36用于设置文字渲染高对比度模式。 37 38该接口设置后整个进程都会生效，进程内所有页面共用相同模式。 39 40可调用此接口设置，也可通过系统设置界面中**高对比度文字配置开关**进行开启/关闭。使用此接口设置开启/关闭文字渲染高对比度配置的优先级高于系统开关设置。 41 42该接口针对应用的文字自绘制场景不生效。 43 44**系统能力**：SystemCapability.Graphics.Drawing 45 46**参数：** 47 48| 参数名 | 类型 | 必填 | 说明 | 49| ----- | ------------------ | ---- | --------------------------------------------------------------------------------- | 50| action | [TextHighContrast](#texthighcontrast20) | 是 | 文字渲染高对比度模式。 | 51 52**示例：** 53 54```ts 55text.setTextHighContrast(text.TextHighContrast.TEXT_APP_DISABLE_HIGH_CONTRAST) 56``` 57 58## text.setTextUndefinedGlyphDisplay<sup>20+</sup> 59 60setTextUndefinedGlyphDisplay(noGlyphShow: TextUndefinedGlyphDisplay): void 61 62设置字符映射到.notdef（未定义）字形时要使用的字形类型。 63 64影响此调用后呈现的所有文本。 65 66此配置会影响显示字体中未定义字符的方式： 67 68- 默认行为遵循字体的内部.notdef字形设计。 69- 开启后将强制使缺失字形的字符以豆腐块形式显示。 70 71**系统能力**：SystemCapability.Graphics.Drawing 72 73**参数：** 74 75| 参数名 | 类型 | 必填 | 说明 | 76| ----- | ------------------ | ---- | ------------------------------------------------------------------------------- | 77| noGlyphShow | [TextUndefinedGlyphDisplay](#textundefinedglyphdisplay20) | 是 | 无法塑形字符的显示方式。 | 78 79**示例：** 80 81```ts 82text.setTextUndefinedGlyphDisplay(text.TextUndefinedGlyphDisplay.USE_TOFU) 83``` 84 85## text.matchFontDescriptors<sup>18+</sup> 86 87matchFontDescriptors(desc: FontDescriptor): Promise<Array<FontDescriptor>> 88 89根据指定的字体描述符返回所有符合要求的系统字体描述符，使用Promise异步回调。 90 91**系统能力**：SystemCapability.Graphics.Drawing 92 93**参数：** 94 95| 参数名 | 类型 | 必填 | 说明 | 96| - | - | - | - | 97| desc | [FontDescriptor](#fontdescriptor14) | 是 | 指定需要用来做匹配的字体描述符。如果不指定任何字段，则返回系统的所有字体描述符。如果填写了指定字段，则按照指定字段进行匹配。如果匹配失败，返回空数组。 | 98 99**返回值：** 100 101| 类型 | 说明 | 102| - | - | 103| Promise<Array<[FontDescriptor](#fontdescriptor14)>> | Promise对象，返回所有匹配到的系统字体描述符。 | 104 105**错误码：** 106 107以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 108 109| 错误码ID | 错误信息 | 110| ------- | --------------------------------------------| 111| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | 112 113**示例：** 114 115```ts 116import { text } from '@kit.ArkGraphics2D' 117import { BusinessError } from '@kit.BasicServicesKit' 118 119@Entry 120@Component 121struct Index { 122 build() { 123 Row() { 124 Column() { 125 Button("font descriptor") 126 .fontSize(30) 127 .fontWeight(FontWeight.Bold) 128 .width(300) 129 .height(80) 130 .onClick(() => { 131 console.info(`Get font descriptor start`) 132 let promise = text.matchFontDescriptors({ 133 weight: text.FontWeight.W400, 134 }) 135 promise.then((data) => { 136 console.info(`Font descriptor array size: ${data.length}`); 137 console.info(`Font descriptor result: ${JSON.stringify(data)}`) 138 }).catch((error: BusinessError) => { 139 console.error(`Failed to match the font descriptor, error: ${JSON.stringify(error)}`); 140 }); 141 }) 142 } 143 .width('100%') 144 } 145 .height('100%') 146 } 147} 148``` 149 150## text.getSystemFontFullNamesByType<sup>14+</sup> 151 152getSystemFontFullNamesByType(fontType: SystemFontType): Promise<Array<string>> 153 154根据字体类型返回该类型对应的所有字体的字体名称，使用Promise异步回调。 155 156**系统能力：** SystemCapability.Graphics.Drawing 157 158**参数：** 159 160| 参数名 | 类型 | 必填 | 说明 | 161| - | - | - | - | 162| fontType | [SystemFontType](#systemfonttype14) | 是 | 指定的字体类型。 | 163 164**返回值：** 165 166| 类型 | 说明 | 167| - | - | 168| Promise<Array<string>> | Promise对象，返回相应字体类型的所有字体的fullName。 | 169 170**错误码：** 171 172以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 173 174| 错误码ID | 错误信息 | 175| ------- | --------------------------------------------| 176| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 177 178**示例：** 179 180```ts 181import { text } from '@kit.ArkGraphics2D' 182import { BusinessError } from '@kit.BasicServicesKit' 183 184@Entry 185@Component 186struct Index { 187 build() { 188 Row() { 189 Column() { 190 Button("get font list") 191 .fontSize(30) 192 .fontWeight(FontWeight.Bold) 193 .width(300) 194 .height(80) 195 .onClick(() => { 196 let fontType:text.SystemFontType = text.SystemFontType.GENERIC 197 let promise = text.getSystemFontFullNamesByType(fontType) 198 promise.then((data) => { 199 console.info(`then font list size: ${data.length}`) 200 data.forEach((fontItem) => { 201 console.info(fontItem) 202 }) 203 }).catch((error: BusinessError) => { 204 console.error(`Failed to get font fullNames by type, error: ${JSON.stringify(error)}`); 205 }); 206 }) 207 } 208 .width('100%') 209 } 210 .height('100%') 211 } 212} 213``` 214 215## text.getFontDescriptorByFullName<sup>14+</sup> 216 217getFontDescriptorByFullName(fullName: string, fontType: SystemFontType): Promise<FontDescriptor> 218 219根据字体名称和类型获取字体描述符，使用Promise异步回调。 220 221字体描述符是描述字体特征的数据结构，包含字体外观和属性的详细信息。 222 223**系统能力：** SystemCapability.Graphics.Drawing 224 225**参数：** 226 227| 参数名 | 类型 | 必填 | 说明 | 228| - | - | - | - | 229| fullName | string | 是 | 指定的字体名称。可以使用[getSystemFontFullNamesByType](#textgetsystemfontfullnamesbytype14)获取。 | 230| fontType | [SystemFontType](#systemfonttype14) | 是 | 指定的字体类型。 | 231 232**返回值：** 233 234| 类型 | 说明 | 235| - | - | 236| Promise<[FontDescriptor](#fontdescriptor14)> | Promise对象，返回指定的字体描述符。 | 237 238**错误码：** 239 240以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 241 242| 错误码ID | 错误信息 | 243| ------- | --------------------------------------------| 244| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 245 246**示例：** 247 248```ts 249import { text } from '@kit.ArkGraphics2D' 250import { BusinessError } from '@kit.BasicServicesKit' 251 252@Entry 253@Component 254struct Index { 255 build() { 256 Row() { 257 Column() { 258 Button("get fontDesciptor") 259 .fontSize(30) 260 .fontWeight(FontWeight.Bold) 261 .width(300) 262 .height(80) 263 .onClick(() => { 264 let fontType:text.SystemFontType = text.SystemFontType.GENERIC 265 let promise = text.getFontDescriptorByFullName("HarmonyOS Sans", fontType) 266 promise.then((fontdecriptor) => { 267 console.info(`desc: ${JSON.stringify(fontdecriptor)}`) 268 }).catch((error: BusinessError) => { 269 console.error(`Failed to get fontDescriptor by fullName, error: ${JSON.stringify(error)}`); 270 }); 271 }) 272 } 273 .width('100%') 274 } 275 .height('100%') 276 } 277} 278``` 279 280## TextHighContrast<sup>20+</sup> 281 282文字渲染高对比度配置类型枚举。 283 284**系统能力：** SystemCapability.Graphics.Drawing 285 286| 名称 | 值 | 说明 | 287| ---------------------------------- | ---- | ---------------------------------------------- | 288| TEXT_FOLLOW_SYSTEM_HIGH_CONTRAST | 0 | 跟随系统设置中的高对比度文字配置。 | 289| TEXT_APP_DISABLE_HIGH_CONTRAST | 1 | 关闭APP的文字渲染高对比度配置，该模式的优先级要高于系统设置中的高对比度文字配置。 | 290| TEXT_APP_ENABLE_HIGH_CONTRAST | 2 | 开启APP的文字渲染高对比度配置，该模式的优先级要高于系统设置中的高对比度文字配置。 | 291 292## TextUndefinedGlyphDisplay<sup>20+</sup> 293 294文本未定义字形时的显示方式枚举。 295 296**系统能力：** SystemCapability.Graphics.Drawing 297 298| 名称 | 值 | 说明 | 299| -------------- | ---- | ------------------------------------ | 300| USE_DEFAULT | 0 | 使用字体的内部.notdef字形。遵循字体的内部.notdef字形设计，可以是空框、空格或自定义符号。| 301| USE_TOFU | 1 | 总是用显式的豆腐块替换未定义的字形，覆盖字体的默认行为。用于调试缺失字符或强制一致的缺失符号显示。| 302 303## TextAlign 304 305文本对齐方式枚举。 306 307**系统能力：** SystemCapability.Graphics.Drawing 308 309| 名称 | 值 | 说明 | 310| --------- | ---- | ---------------------------------------------- | 311| LEFT | 0 | 文本靠左对齐。 | 312| RIGHT | 1 | 文本靠右对齐。 | 313| CENTER | 2 | 文本居中对齐。 | 314| JUSTIFY | 3 | 文本两侧对齐，对最后一行无效。 | 315| START | 4 | 基于文本的方向[TextDirection](#textdirection)，文本靠开头方向对齐。 | 316| END | 5 | 基于文本的方向[TextDirection](#textdirection)，文本以结束方向对齐。 | 317 318## TextVerticalAlign<sup>20+</sup> 319 320文本垂直对齐方式枚举。 321 322**系统能力：** SystemCapability.Graphics.Drawing 323 324| 名称 | 值 | 说明 | 325| --------- | ---- | ---------------------------------------------- | 326| BASELINE | 0 | 文本基线对齐。 | 327| BOTTOM | 1 | 文本底部对齐。 | 328| CENTER | 2 | 文本居中对齐。 | 329| TOP | 3 | 文本顶部对齐。 | 330 331## TextDirection 332 333文本排版方向枚举。 334 335**系统能力：** SystemCapability.Graphics.Drawing 336 337| 名称 | 值 | 说明 | 338| -------- | ---- | ---------------- | 339| RTL | 0 | 文本从右到左排版。 | 340| LTR | 1 | 文本从左到右排版。 | 341 342## BreakStrategy 343 344断行策略枚举。 345 346**系统能力：** SystemCapability.Graphics.Drawing 347 348| 名称 | 值 | 说明 | 349| ------------- | ---- | ---------------------------------------------- | 350| GREEDY | 0 | 尽可能将当前行填满，不会自动添加连词符。 | 351| HIGH_QUALITY | 1 | 布局优化，必要时会自动添加连词符。 | 352| BALANCED | 2 | 保证一个段落的每一行的宽度相同，必要时会添加连词符。| 353 354## WordBreak 355 356断词策略枚举。 357 358**系统能力：** SystemCapability.Graphics.Drawing 359 360| 名称 | 值 | 说明 | 361|-----------------------------| ---- | -------------------------------------------------------------------------------------------------------------------- | 362| NORMAL | 0 | 默认的换行规则。依据各自语言的规则，允许在字间发生换行。 | 363| BREAK_ALL | 1 | 对于Non-CJK（非中文，日文，韩文）文本允许在任意字符内发生换行。该值适合包含一些非亚洲文本的亚洲文本，比如使连续的英文字符断行。| 364| BREAK_WORD | 2 | 对于Non-CJK的文本可在任意2个字符间断行，一行文本中有断行破发点（如空白符）时，优先按破发点换行，保障单词优先完整显示。若整一行文本均无断行破发点时，则在任意2个字符间断行。对于CJK与NORMAL效果一致。| 365| BREAK_HYPHEN<sup>18+</sup> | 3 | 每行末尾单词尝试通过连字符“-”进行断行，若无法添加连字符“-”，则跟`BREAK_WORD`保持一致。<br/>使用此断词策略时，需与[TextStyle](#textstyle)中`locale`属性配合使用，通过locale定义语言环境共同作用影响断词效果。 | 366 367## Decoration 368 369文本装饰线。 370 371**系统能力：** SystemCapability.Graphics.Drawing 372 373| 名称 | 类型 | 只读 | 可选 | 说明 | 374| ------------------------- | --------------------------------------------------- | ---- | ---- | -------------------------------------------- | 375| textDecoration | [TextDecorationType](#textdecorationtype) | 否 | 是 | 装饰线类型，默认为NONE。 | 376| color | [common2D.Color](js-apis-graphics-common2D.md#color)| 否 | 是 | 装饰线颜色，默认为跟随文本颜色。 | 377| decorationStyle | [TextDecorationStyle](#textdecorationstyle) | 否 | 是 | 装饰线样式，默认为SOLID。 | 378| decorationThicknessScale | number | 否 | 是 | 装饰线粗细系数，浮点数，默认为1.0。如果设置的值小于等于0，则不会绘制装饰线。| 379 380## TextDecorationType 381 382装饰线类型枚举。 383 384**系统能力：** SystemCapability.Graphics.Drawing 385 386| 名称 | 值 | 说明 | 387| -------------- | - | ----------- | 388| NONE | 0 | 无装饰线。| 389| UNDERLINE | 1 | 下划线。 | 390| OVERLINE | 2 | 上划线。 | 391| LINE_THROUGH | 4 | 删除线。 | 392 393## TextDecorationStyle 394 395装饰线样式枚举。 396 397**系统能力：** SystemCapability.Graphics.Drawing 398 399| 名称 | 值 | 说明 | 400| ------ | - | ------ | 401| SOLID | 0 | 实线。 | 402| DOUBLE | 1 | 双层线。| 403| DOTTED | 2 | 点状线。| 404| DASHED | 3 | 虚线。 | 405| WAVY | 4 | 波浪线。| 406 407## FontWeight 408 409字重枚举。 410 411**系统能力：** SystemCapability.Graphics.Drawing 412 413| 名称 | 值 | 说明 | 414| ----- | - | ------- | 415| W100 | 0 | 100字重。| 416| W200 | 1 | 200字重。| 417| W300 | 2 | 300字重。| 418| W400 | 3 | 400字重。| 419| W500 | 4 | 500字重。| 420| W600 | 5 | 600字重。| 421| W700 | 6 | 700字重。| 422| W800 | 7 | 800字重。| 423| W900 | 8 | 900字重。| 424 425## FontWidth 426 427字体宽度的枚举。 428 429**系统能力：** SystemCapability.Graphics.Drawing 430 431| 名称 | 值 | 说明 | 432| ---------------- | - | ---------- | 433| ULTRA_CONDENSED | 1 | 超窄字宽。 | 434| EXTRA_CONDENSED | 2 | 特窄字宽。 | 435| CONDENSED | 3 | 窄的字宽。 | 436| SEMI_CONDENSED | 4 | 半窄字宽。 | 437| NORMAL | 5 | 常规字宽。 | 438| SEMI_EXPANDED | 6 | 半宽字宽。 | 439| EXPANDED | 7 | 宽的字宽。 | 440| EXTRA_EXPANDED | 8 | 特宽字宽。 | 441| ULTRA_EXPANDED | 9 | 超宽的字宽。| 442 443## FontStyle 444 445字体样式枚举。 446 447**系统能力：** SystemCapability.Graphics.Drawing 448 449| 名称 | 值 | 说明 | 450| ------- | - | ---------------------------------------------------- | 451| NORMAL | 0 | 常规样式。 | 452| ITALIC | 1 | 斜体。如果当前字体没有可用的斜体版本，会选用倾斜体替代。 | 453| OBLIQUE | 2 | 倾斜体。如果当前字体没有可用的倾斜体版本，会选用斜体替代。| 454 455## TextHeightBehavior 456 457文本高度修饰符模式枚举。 458 459**系统能力：** SystemCapability.Graphics.Drawing 460 461| 名称 | 值 | 说明 | 462| --------------------- | --- | ---------------------------------------------------- | 463| ALL | 0x0 | 高度修饰符设置为段落中第一行上升、最后一行下降。 | 464| DISABLE_FIRST_ASCENT | 0x1 | 高度修饰符设置为禁止段落中第一行上升。 | 465| DISABLE_LAST_ASCENT | 0x2 | 高度修饰符设置为禁止段落中最后一行下降。 | 466| DISABLE_ALL | 0x1 \| 0x2 | 高度修饰符设置为禁止段落中第一行上升、最后一行下降。 | 467 468## TextBaseline 469 470文本基线类型枚举。 471 472**系统能力：** SystemCapability.Graphics.Drawing 473 474| 名称 | 值 | 说明 | 475| ----------- | - | ---- | 476| ALPHABETIC | 0 | 用于拉丁字母的文本基线对齐。| 477| IDEOGRAPHIC | 1 | 用于CJK（中文，日文，韩文）的文本基线对齐。| 478 479## EllipsisMode 480 481省略号类型枚举。 482 483EllipsisMode.START和EllipsisMode.MIDDLE仅在单行超长文本生效。 484 485**系统能力：** SystemCapability.Graphics.Drawing 486 487| 名称 | 值 | 说明 | 488| ------ | - | --------- | 489| START | 0 | 开头省略号，只在[ParagraphStyle](#paragraphstyle)中设置maxLines为1时生效。| 490| MIDDLE | 1 | 中间省略号，只在[ParagraphStyle](#paragraphstyle)中设置maxLines为1时生效。| 491| END | 2 | 末尾省略号。| 492 493## TextShadow 494 495字体阴影。 496 497**系统能力：** SystemCapability.Graphics.Drawing 498 499| 名称 | 类型 | 只读 | 可选 | 说明 | 500| ------------- | ---------------------------------------------------- | -- | --- | --------------------------------- | 501| color | [common2D.Color](js-apis-graphics-common2D.md#color) | 否 | 是 | 字体阴影的颜色，默认为黑色Color(255, 0, 0, 0)。 | 502| point | [common2D.Point](js-apis-graphics-common2D.md#point12) | 否 | 是 | 字体阴影基于当前文本的偏移位置，横、纵坐标要大于等于零。 | 503| blurRadius | number | 否 | 是 | 模糊半径，浮点数，默认为0.0px。 | 504 505## RectStyle 506 507矩形框样式。 508 509**系统能力：** SystemCapability.Graphics.Drawing 510 511| 名称 | 类型 | 只读 | 可选 | 说明 | 512| ----------------- | ---------------------------------------------------- | -- | --- | ---------------------------------------- | 513| color | [common2D.Color](js-apis-graphics-common2D.md#color) | 否 | 否 | 矩形框的颜色。 | 514| leftTopRadius | number | 否 | 否 | 矩形框的左上半径。 | 515| rightTopRadius | number | 否 | 否 | 矩形框的右上半径。 | 516| rightBottomRadius | number | 否 | 否 | 矩形框的右下半径。 | 517| leftBottomRadius | number | 否 | 否 | 矩形框的左下半径。 | 518 519## FontFeature 520 521文本字体特征。 522 523**系统能力：** SystemCapability.Graphics.Drawing 524 525| 名称 | 类型 | 只读 | 可选 | 说明 | 526| --------- | ---------------------------------------------------- | -- | --- | ----------------------------------------- | 527| name | string | 否 | 否 | 字体特征键值对中的关键字标识的字符串。 | 528| value | number | 否 | 否 | 字体特征键值对的值。 | 529 530## FontVariation 531 532可变字体属性。 533 534**系统能力：** SystemCapability.Graphics.Drawing 535 536| 名称 | 类型 | 只读 | 可选 | 说明 | 537| --------- | ---------------------------------------------------- | -- | --- | ----------------------------------------- | 538| axis | string | 否 | 否 | 可变字体属性键值对中的关键字标识的字符串。 | 539| value | number | 否 | 否 | 可变字体属性键值对的值。 | 540 541## TextBadgeType<sup>20+</sup> 542 543文本上下标枚举。 544 545**系统能力：** SystemCapability.Graphics.Drawing 546 547| 名称 | 值 | 说明 | 548| ------ | - | --------- | 549| TEXT_BADGE_NONE | 0 | 不使能上下标。 | 550| TEXT_SUPERSCRIPT | 1 | 使能上标。 | 551| TEXT_SUBSCRIPT | 2 | 使能下标。 | 552 553## TextStyle 554 555文本样式。 556 557**系统能力：** SystemCapability.Graphics.Drawing 558 559| 名称 | 类型 | 只读 | 可选 | 说明 | 560| ------------- | ---------------------------------------------------- | -- | -- | --------------------------------------------------------- | 561| decoration | [Decoration](#decoration) | 否 | 是 | 装饰线设置，默认不使用装饰线。 | 562| color | [common2D.Color](js-apis-graphics-common2D.md#color) | 否 | 是 | 文字颜色，默认为白色。 | 563| fontWeight | [FontWeight](#fontweight) | 否 | 是 | 字重，默认为W400。 目前只有系统默认字体支持字重的调节，其他字体设置字重值小于semi-bold（即W600）时字体粗细无变化，当设置字重值大于等于semi-bold（即W600）时可能会触发伪加粗效果。 | 564| fontStyle | [FontStyle](#fontstyle) | 否 | 是 | 字体样式，默认为常规样式。 | 565| baseline | [TextBaseline](#textbaseline) | 否 | 是 | 文本基线类型，默认为ALPHABETIC。 | 566| fontFamilies | Array\<string> | 否 | 是 | 字体家族名称列表，默认为空，匹配系统字体。 | 567| fontSize | number | 否 | 是 | 字体大小，浮点数，默认为14.0，单位为px。 | 568| letterSpacing | number | 否 | 是 | 字符间距，正数拉开字符距离，若是负数则拉近字符距离，浮点数，默认为0.0，单位为物理像素px。| 569| wordSpacing | number | 否 | 是 | 单词间距，浮点数，默认为0.0，单位为px。 | 570| heightScale | number | 否 | 是 | 行高缩放倍数，浮点数，默认为1.0，heightOnly为true时生效。 | 571| heightOnly | boolean | 否 | 是 | true表示根据字体大小和heightScale设置文本框的高度，false表示根据行高和行距，默认为false。| 572| halfLeading | boolean | 否 | 是 | true表示将行间距平分至行的顶部与底部，false则不平分，默认为false。| 573| ellipsis | string | 否 | 是 | 省略号文本，表示省略号生效后使用该字段值替换省略号部分。 | 574| ellipsisMode | [EllipsisMode](#ellipsismode) | 否 | 是 | 省略号类型，默认为END，行尾省略号。 | 575| locale | string | 否 | 是 | 语言类型，如字段为'en'代表英文，'zh-Hans'代表简体中文，'zh-Hant'代表繁体中文。具体请参照ISO 639-1规范，默认为空字符串。| 576| baselineShift | number | 否 | 是 | 文本下划线的偏移距离，浮点数，默认为0.0px。 | 577| fontFeatures | Array\<[FontFeature](#fontfeature)> | 否 | 是 | 文本字体特征数组。| 578| fontVariations| Array\<[FontVariation](#fontvariation)> | 否 | 是 | 可变字体属性数组。| 579| textShadows | Array\<[TextShadow](#textshadow)> | 否 | 是 | 文本阴影数组。| 580| backgroundRect| [RectStyle](#rectstyle) | 否 | 是 | 文本矩形框样式。| 581| badgeType<sup>20+</sup> | [TextBadgeType](#textbadgetype20) | 否 | 是 | 设置文本排版时是否使能上标或下标。TEXT_SUPERSCRIPT表示使能上标，TEXT_SUBSCRIPT表示使能下标，默认值为TEXT_BADGE_NONE表示不使能。| 582 583## StrutStyle 584 585支柱样式，用于控制绘制文本的行间距、基线对齐方式以及其他与行高相关的属性，默认不开启。 586 587**系统能力：** SystemCapability.Graphics.Drawing 588 589| 名称 | 类型 | 只读 | 可选 | 说明 | 590| ------------- | ---------------------------------------------------- | ---- | -- | --------------------------------------------------------------------- | 591| fontFamilies | Array\<string> | 否 | 是 | 字体家族名称列表，默认为空，匹配系统字体。 | 592| fontStyle | [FontStyle](#fontstyle) | 否 | 是 | 字体样式，默认为常规样式。 | 593| fontWidth | [FontWidth](#fontwidth) | 否 | 是 | 字体宽度，默认为NORMAL。 | 594| fontWeight | [FontWeight](#fontweight) | 否 | 是 | 字重，默认为W400。系统默认字体支持字重调节，其他字体设置字重值小于W600时无变化，大于等于W600时可能触发伪加粗效果。 | 595| fontSize | number | 否 | 是 | 字体大小，浮点数，默认14.0，单位物理像素px。 | 596| height | number | 否 | 是 | 行高缩放倍数，浮点数，默认为1.0。 | 597| leading | number | 否 | 是 | 以自定义行距应用于支柱的行距，浮点数，默认为-1.0。 | 598| forceHeight | boolean | 否 | 是 | 是否所有行都将使用支柱的高度，true表示使用，false表示不使用，默认为false。 | 599| enabled | boolean | 否 | 是 | 是否启用支柱样式，true表示使用，false表示不使用，默认为false。 | 600| heightOverride | boolean | 否 | 是 | 是否覆盖高度，true表示覆盖，false表示不覆盖，默认为false。 | 601| halfLeading | boolean | 否 | 是 | true表示将行间距平分至行的顶部与底部，false则不平分，默认为false。 | 602 603## FontDescriptor<sup>14+</sup> 604 605字体描述符信息。 606 607**系统能力**：SystemCapability.Graphics.Drawing 608 609| 名称 | 类型 | 只读 | 可选 | 说明 | 610| - | - | - | - | - | 611| path | string | 否 | 是 | 字体绝对路径，可取遵循系统限制的任意字符串，默认为空字符串。 | 612| postScriptName | string | 否 | 是 | 字体唯一标识名称，可取任意字符串，默认为空字符串。 | 613| fullName | string | 否 | 是 | 字体名称，可取任意字符串，默认为空字符串。 | 614| fontFamily | string | 否 | 是 | 字体家族，可取任意字符串，默认为空字符串。 | 615| fontSubfamily | string | 否 | 是 | 子字体家族，可取任意字符串，默认为空字符串。 | 616| weight | [FontWeight](#fontweight) | 否 | 是 | 字体字重，默认值为0。 | 617| width | number | 否 | 是 | 字体宽度，取值范围1-9整数，默认值为0。 | 618| italic | number | 否 | 是 | 是否是斜体字体，0表示非斜体，1表示斜体，默认值为0。 | 619| monoSpace | boolean | 否 | 是 | 是否是等宽字体，true表示等宽，false表示非等宽，默认值为false。 | 620| symbolic | boolean | 否 | 是 | 是否支持符号，true表示支持，false表示不支持，默认值为false。 | 621 622## FontCollection 623 624字体集。 625 626### getGlobalInstance 627 628static getGlobalInstance(): FontCollection 629 630获取应用全局FontCollection实例。 631 632**系统能力**：SystemCapability.Graphics.Drawing 633 634**返回值：** 635 636| 类型 | 说明 | 637| ------ | ------------------ | 638| [FontCollection](#fontcollection) | FontCollection对象。| 639 640**示例：** 641 642```ts 643import { text } from '@kit.ArkGraphics2D' 644 645function textFunc() { 646 let fontCollection = text.FontCollection.getGlobalInstance(); 647} 648 649@Entry 650@Component 651struct Index { 652 fun: Function = textFunc; 653 build() { 654 Column() { 655 Button().onClick(() => { 656 this.fun(); 657 }) 658 } 659 } 660} 661``` 662 663### loadFontSync 664 665loadFontSync(name: string, path: string | Resource): void 666 667同步接口，加载自定义字体。其中参数name对应的值需要在[TextStyle](#textstyle)中的fontFamilies属性配置，才能显示自定义字体效果。支持的字体文件格式包含：ttf、otf。 668 669**系统能力**：SystemCapability.Graphics.Drawing 670 671**参数：** 672 673| 参数名 | 类型 | 必填 | 说明 | 674| ----- | ------------------ | ---- | --------------------------------------------------------------------------------- | 675| name | string | 是 | 加载成字体后，调用该字体所使用的名称。 | 676| path | string \| [Resource](../apis-arkui/arkui-ts/ts-types.md#resource) | 是 | 需要导入的字体文件的路径，应为 "file:// + 字体文件绝对路径" 或 "rawfile/目录or文件名"。 | 677 678**示例：** 679 680```ts 681import { text } from '@kit.ArkGraphics2D' 682 683let fontCollection: text.FontCollection = new text.FontCollection(); 684 685@Entry 686@Component 687struct RenderTest { 688 LoadFontSyncTest() { 689 fontCollection.loadFontSync('Clock_01', 'file:///system/fonts/HarmonyClock_01.ttf') 690 let fontFamilies: Array<string> = ["Clock_01"] 691 let myTextStyle: text.TextStyle = { 692 fontFamilies: fontFamilies 693 }; 694 let myParagraphStyle: text.ParagraphStyle = { 695 textStyle: myTextStyle, 696 } 697 let paragraphBuilder: text.ParagraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection); 698 699 let textData = "测试 loadFontSync 加载字体HarmonyClock_01.ttf"; 700 paragraphBuilder.addText(textData); 701 let paragraph: text.Paragraph = paragraphBuilder.build(); 702 paragraph.layoutSync(600); 703 } 704 705 aboutToAppear() { 706 this.LoadFontSyncTest(); 707 } 708 709 build() { 710 } 711} 712``` 713 714### loadFont<sup>18+</sup> 715 716loadFont(name: string, path: string | Resource): Promise\<void> 717 718异步接口，加载自定义字体。其中参数name对应的值需要在[TextStyle](#textstyle)中的fontFamilies属性配置，才能显示自定义字体效果，支持的字体文件格式包含：ttf、otf。 719 720**系统能力**：SystemCapability.Graphics.Drawing 721 722**参数：** 723 724| 参数名 | 类型 | 必填 | 说明 | 725| ----- | ------------------ | ---- | --------------------------------------------------------------------------------- | 726| name | string | 是 | 加载字体后，调用该字体所使用的别名，可填写任意字符串，可使用该别名指定并使用该字体。 | 727| path | string \| [Resource](../apis-arkui/arkui-ts/ts-types.md#resource) | 是 | 需要加载的字体文件的路径，支持两种格式： "file:// + 字体文件绝对路径" 或 "rawfile/目录or文件名"。 | 728 729**返回值：** 730 731| 类型 | 说明 | 732| -------------- | ----------------------------- | 733| Promise\<void> | 无返回结果的Promise对象。 | 734 735**错误码：** 736 737以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 738 739| 错误码ID | 错误信息 | 740| ------- | --------------------------------------------| 741| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.| 742 743**示例：** 744 745```ts 746import { text } from '@kit.ArkGraphics2D' 747 748let fontCollection: text.FontCollection = new text.FontCollection(); 749 750@Entry 751@Component 752struct RenderTest { 753 async loadFontPromise() { 754 fontCollection.loadFont('testName', 'file:///system/fonts/a.ttf').then((data) => { 755 console.info(`Succeeded in doing loadFont ${JSON.stringify(data)} `); 756 }).catch((error: Error) => { 757 console.error(`Failed to do loadFont, error: ${JSON.stringify(error)} message: ${error.message}`); 758 }); 759 } 760 761 aboutToAppear() { 762 this.loadFontPromise(); 763 } 764 765 build() { 766 } 767} 768``` 769 770### unloadFontSync<sup>20+</sup> 771unloadFontSync(name: string): void 772 773卸载指定的自定义字体，此接口为同步接口。 774 775使用此接口卸载字体别名所对应的自定义字体后，对应的自定义字体将不再可用。 776 777所有使用该字体别名的排版对象都应该被销毁重建。 778 779- 卸载不存在的字体别名不会产生任何效果且不会抛出错误。 780- 此操作仅影响后续字体使用。 781- 卸载正在使用的字体可能导致文本渲染异常（如乱码或字形缺失）。 782 783**系统能力**：SystemCapability.Graphics.Drawing 784 785**参数：** 786 787| 参数名 | 类型 | 必填 | 说明 | 788| ----- | ------------------ | ---- | --------------------------------------------------------------------------------- | 789| name | string | 是 | 需要取消注册的字体别名，与加载字体时使用的别名相同。 | 790 791**示例：** 792 793``` ts 794import { text } from '@kit.ArkGraphics2D' 795 796@Entry 797@Component 798struct UnloadFontSyncTest { 799 private fc: text.FontCollection = text.FontCollection.getGlobalInstance(); 800 @State content: string = "默认字体" 801 802 build() { 803 Column({ space: 10 }) { 804 Text(this.content) 805 .fontFamily("custom") 806 Button("load font") 807 .onClick(() => { 808 this.fc.loadFontSync("custom", "file:///system/fonts/NotoSansCJK-Regular.ttc") 809 this.content = "自定义字体" 810 }) 811 Button("unload font") 812 .onClick(() => { 813 this.fc.unloadFontSync("custom") 814 this.content = "默认字体" 815 }) 816 }.width("100%") 817 .height("100%") 818 .justifyContent(FlexAlign.Center) 819 } 820} 821``` 822 823### unloadFont<sup>20+</sup> 824unloadFont(name: string): Promise\<void> 825 826卸载指定的自定义字体。使用Promise异步回调。 827 828使用此接口卸载字体别名所对应的自定义字体后，对应的自定义字体将不再可用。 829 830所有使用该字体别名的排版对象都应该被销毁重建。 831 832- 卸载不存在的字体别名不会产生任何效果且不会抛出错误。 833- 此操作仅影响后续字体使用。 834- 卸载正在使用的字体可能导致文本渲染异常（如乱码或字形缺失）。 835 836**系统能力**：SystemCapability.Graphics.Drawing 837 838**参数：** 839 840| 参数名 | 类型 | 必填 | 说明 | 841| ----- | ------------------ | ---- | --------------------------------- | 842| name | string | 是 | 需要卸载的字体的别名，与加载字体时使用的别名相同。 | 843 844**返回值：** 845 846| 类型 | 说明 | 847| -------------- | ------------------------- | 848| Promise\<void> | 无返回结果的Promise对象。 | 849 850**示例：** 851 852```ts 853import { text } from '@kit.ArkGraphics2D' 854 855@Entry 856@Component 857struct UnloadFontTest { 858 private fc: text.FontCollection = text.FontCollection.getGlobalInstance(); 859 @State content: string = "默认字体" 860 861 build() { 862 Column({ space: 10 }) { 863 Text(this.content) 864 .fontFamily("custom") 865 Button("load font") 866 .onClick(async () => { 867 await this.fc.loadFont("custom", "file:///system/fonts/NotoSansCJK-Regular.ttc") 868 this.content = "自定义字体" 869 }) 870 Button("unload font") 871 .onClick(async () => { 872 await this.fc.unloadFont("custom") 873 this.content = "默认字体" 874 }) 875 }.width("100%") 876 .height("100%") 877 .justifyContent(FlexAlign.Center) 878 } 879} 880``` 881 882### clearCaches 883 884clearCaches(): void 885 886清理字体排版缓存（字体排版缓存本身设有内存上限和清理机制，所占内存有限，如无内存要求，不建议清理）。 887 888**系统能力**：SystemCapability.Graphics.Drawing 889 890**示例：** 891 892```ts 893import { text } from '@kit.ArkGraphics2D' 894 895@Entry 896@Component 897struct Index { 898 build() { 899 Column() { 900 Button().onClick(() => { 901 text.FontCollection.getGlobalInstance().clearCaches(); 902 }) 903 } 904 } 905} 906``` 907 908## ParagraphStyle 909 910段落样式。 911 912**系统能力：** SystemCapability.Graphics.Drawing 913 914| 名称 | 类型 | 只读 | 可选 | 说明 | 915| -------------------- | ------------------------------------------ | ---- | ---- | -------------------------------------------- | 916| textStyle | [TextStyle](#textstyle) | 否 | 是 | 作用于整个段落的文本样式，默认为初始的文本样式。| 917| textDirection | [TextDirection](#textdirection) | 否 | 是 | 文本方向，默认为LTR。 | 918| align | [TextAlign](#textalign) | 否 | 是 | 文本对齐方式，默认为START。若同时配置tab属性，制表符对齐方式将失效。| 919| wordBreak | [WordBreak](#wordbreak) | 否 | 是 | 断词类型，默认为BREAK_WORD。 | 920| maxLines | number | 否 | 是 | 最大行数限制，整数，默认为1e9。 | 921| breakStrategy | [BreakStrategy](#breakstrategy) | 否 | 是 | 断行策略，默认为GREEDY。 | 922| strutStyle | [StrutStyle](#strutstyle) | 否 | 是 | 支柱样式，默认为初始的StrutStyle。 | 923| textHeightBehavior | [TextHeightBehavior](#textheightbehavior) | 否 | 是 | 文本高度修饰符模式，默认为ALL。 | 924| tab<sup>18+</sup> | [TextTab](#texttab18) | 否 | 是 | 表示段落中文本制表符后的文本对齐方式及位置，默认将制表符替换为一个空格。此参数与文本对齐方式（align属性）或省略号样式（[TextStyle](#textstyle)中的ellipsis属性）共同配置时无效。 | 925| trailingSpaceOptimized<sup>20+</sup> | boolean | 否 | 是 | 表示文本排版时行尾空格是否参与对齐计算。true表示行尾空格不参与计算，false表示行尾空格参与计算，默认值为false。| 926| autoSpace<sup>20+</sup> | boolean | 否 | 是 | 设置文本排版时是否使能自动间距。true表示使能自动间距，则会在文本排版时自动调整CJK（中文字符、日文字符、韩文字符）与西文（拉丁字母、西里尔字母、希腊字母）、CJK与数字、CJK与版权符号、版权符号与数字、版权符号与西文之间的间距。false表示不使能自动间距，默认值为false。| 927| verticalAlign<sup>20+</sup> | [TextVerticalAlign](#textverticalalign20) | 否 | 是 | 文本垂直对齐方式，开启行高缩放（即设置[TextStyle](#textstyle)的heightScale）或行内不同字号（即设置[TextStyle](#textstyle)的fontSize）文本混排时生效。若行内有上下标文本（即设置[TextStyle](#textstyle)的badgeType属性文本），上下标文本将与普通文本一样参与垂直对齐。 | 928 929## PlaceholderAlignment 930 931占位符相对于周围文本的纵向对齐方式。 932 933**系统能力：** SystemCapability.Graphics.Drawing 934 935| 名称 | 值 | 说明 | 936| ------------------- | - | ---------------------- | 937| OFFSET_AT_BASELINE | 0 | 基线与文本基线对齐。 | 938| ABOVE_BASELINE | 1 | 底部与文本基线对齐。 | 939| BELOW_BASELINE | 2 | 顶部与文本基线对齐。 | 940| TOP_OF_ROW_BOX | 3 | 顶部与文本顶部对齐。 | 941| BOTTOM_OF_ROW_BOX | 4 | 底部与文本底部对齐。 | 942| CENTER_OF_ROW_BOX | 5 | 居中对齐。| 943| FOLLOW_PARAGRAPH<sup>20+</sup> | 6 | 跟随文本排版对齐。| 944 945 946 947> **说明：** 948> 949> 示意图展示了后三种对齐方式，前三种对齐方式类似，比较位置是文本基线，即绿色线条部分。 950> 951> 952 953## PlaceholderSpan 954 955描述占位符样式。 956 957**系统能力：** SystemCapability.Graphics.Drawing 958 959| 名称 | 类型 | 只读 | 可选 | 说明 | 960| -------------- | --------------------------------------------- | ---- | --- | --------------------------- | 961| width | number | 否 | 否 | 占位符的宽度，浮点数，单位为物理像素px。| 962| height | number | 否 | 否 | 占位符的高度，浮点数，单位为物理像素px。| 963| align | [PlaceholderAlignment](#placeholderalignment) | 否 | 否 | 相对于周围文本的纵向对齐方式。| 964| baseline | [TextBaseline](#textbaseline) | 否 | 否 | 基线类型。 | 965| baselineOffset | number | 否 | 否 | 基线偏移量，浮点数，单位为物理像素px。 | 966 967## Range 968 969描述左闭右开区间。 970 971**系统能力：** SystemCapability.Graphics.Drawing 972 973| 名称 | 类型 | 只读 | 可选 | 说明 | 974| ----- | ------ | ---- | --- | --------------- | 975| start | number | 否 | 否 | 区间左侧端点索引，整数。| 976| end | number | 否 | 否 | 区间右侧端点索引，整数。| 977 978## Paragraph 979 980保存文本内容及样式的载体，支持排版与绘制操作。 981 982下列API示例中都需先使用[ParagraphBuilder](#paragraphbuilder)类的[build()](#build)接口获取到Paragraph对象实例，再通过此实例调用对应方法。 983 984### layoutSync 985 986layoutSync(width: number): void 987 988进行排版并计算所有字形位置。 989 990**系统能力**：SystemCapability.Graphics.Drawing 991 992**参数：** 993 994| 参数名 | 类型 | 必填 | 说明 | 995| ----- | ------ | ---- | -------------- | 996| width | number | 是 | 单行的最大宽度，浮点数，单位为物理像素px。| 997 998**示例：** 999 1000```ts 1001paragraph.layoutSync(100); 1002``` 1003 1004### layout<sup>18+</sup> 1005 1006layout(width: number): Promise\<void> 1007 1008进行排版并计算所有字形位置，使用Promise异步回调。 1009 1010**系统能力**：SystemCapability.Graphics.Drawing 1011 1012**参数：** 1013 1014| 参数名 | 类型 | 必填 | 说明 | 1015| ----- | ------------------ | ---- | --------------------------------------- | 1016| width | number | 是 | 单行的最大宽度，浮点数，单位为物理像素px。 | 1017 1018**返回值：** 1019 1020| 类型 | 说明 | 1021| -------------- | ----------------------------- | 1022| Promise\<void> | 无返回结果的Promise对象。 | 1023 1024**错误码：** 1025 1026以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1027 1028| 错误码ID | 错误信息 | 1029| ------- | --------------------------------------------| 1030| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | 1031 1032**示例：** 1033 1034```ts 1035import { drawing, text } from '@kit.ArkGraphics2D' 1036import { image } from '@kit.ImageKit' 1037 1038let textStyle: text.TextStyle = { 1039 color: { 1040 alpha: 255, 1041 red: 255, 1042 green: 0, 1043 blue: 0 1044 }, 1045 fontSize: 30, 1046}; 1047let paragraphStyle: text.ParagraphStyle = { 1048 textStyle: textStyle, 1049}; 1050let fontCollection: text.FontCollection = new text.FontCollection(); 1051let paragraphBuilder = new text.ParagraphBuilder(paragraphStyle, fontCollection); 1052// 添加文本字符串 1053paragraphBuilder.addText("test"); 1054// 生成排版对象 1055let paragraph = paragraphBuilder.build(); 1056 1057function textFunc(pixelmap: PixelMap) { 1058 // 通过图片对象构造画布 1059 let canvas = new drawing.Canvas(pixelmap); 1060 // 进行绘制文本字符串 1061 paragraph.paint(canvas, 100, 10); 1062} 1063 1064@Entry 1065@Component 1066struct Index { 1067 @State pixelmap?: PixelMap = undefined; 1068 fun: Function = textFunc; 1069 1070 async prepareLayoutPromise() { 1071 // 排版对象进行布局计算 1072 paragraph.layout(200).then((data) => { 1073 console.info(`Succeeded in doing layout, ${JSON.stringify(data)}`); 1074 }).catch((error: Error) => { 1075 console.error(`Failed to do layout, error: ${JSON.stringify(error)} message: ${error.message}`); 1076 }); 1077 } 1078 1079 aboutToAppear() { 1080 this.prepareLayoutPromise(); 1081 } 1082 1083 build() { 1084 Column() { 1085 Image(this.pixelmap).width(200).height(200); 1086 Button("layout") 1087 .width(100) 1088 .height(50) 1089 .onClick(() => { 1090 const color: ArrayBuffer = new ArrayBuffer(160000); 1091 let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 200, width: 200 } } 1092 if (this.pixelmap == undefined) { 1093 // 构造图片对象 1094 this.pixelmap = image.createPixelMapSync(color, opts); 1095 } 1096 // 进行绘制文字 1097 this.fun(this.pixelmap); 1098 }) 1099 } 1100 } 1101} 1102``` 1103 1104>**说明：** 1105> 1106>示意图展示了点击按钮后layout接口示例代码的运行结果。 1107> 1108> 1109 1110### paint 1111 1112paint(canvas: drawing.Canvas, x: number, y: number): void 1113 1114在画布上以 (x, y) 为左上角绘制文本。 1115 1116**系统能力**：SystemCapability.Graphics.Drawing 1117 1118**参数：** 1119 1120| 参数名 | 类型 | 必填 | 说明 | 1121| ------ | ---------------------------------------------------- | ---- | ---------------------- | 1122| canvas | [drawing.Canvas](arkts-apis-graphics-drawing-Canvas.md) | 是 | 绘制的目标画布。 | 1123| x | number | 是 | 绘制的左上角位置的横坐标，浮点数。| 1124| y | number | 是 | 绘制的左上角位置的纵坐标，浮点数。| 1125 1126**示例：** 1127 1128```ts 1129const color: ArrayBuffer = new ArrayBuffer(160000); 1130let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 200, width: 200 } } 1131let pixelMap: image.PixelMap = image.createPixelMapSync(color, opts); 1132let canvas = new drawing.Canvas(pixelMap); 1133paragraph.paint(canvas, 0, 0); 1134``` 1135 1136### paintOnPath 1137 1138paintOnPath(canvas: drawing.Canvas, path: drawing.Path, hOffset: number, vOffset: number): void 1139 1140在画布上沿路径绘制文本。 1141 1142**系统能力**：SystemCapability.Graphics.Drawing 1143 1144**参数：** 1145 1146| 参数名 | 类型 | 必填 | 说明 | 1147| ------ | ---------------------------------------------------- | ---- | ---------------------- | 1148| canvas | [drawing.Canvas](arkts-apis-graphics-drawing-Canvas.md) | 是 | 绘制的目标画布。 | 1149| path | [drawing.Path](arkts-apis-graphics-drawing-Path.md) | 是 | 确认文字位置的路径。 | 1150| hOffset | number | 是 | 沿路径方向偏置，从路径起点向前为正，向后为负。| 1151| vOffset | number | 是 | 沿路径垂直方向偏置，沿路径方向左侧为负，右侧为正。| 1152 1153**示例：** 1154 1155```ts 1156const color: ArrayBuffer = new ArrayBuffer(160000); 1157let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 200, width: 200 } } 1158let pixelMap: image.PixelMap = image.createPixelMapSync(color, opts); 1159let canvas = new drawing.Canvas(pixelMap); 1160let path = new drawing.Path(); 1161path.arcTo(20, 20, 180, 180, 180, 90); 1162paragraph.paintOnPath(canvas, path, 0, 0); 1163``` 1164 1165### getMaxWidth 1166 1167getMaxWidth(): number 1168 1169获取文本最大行宽。 1170 1171**系统能力**：SystemCapability.Graphics.Drawing 1172 1173**返回值：** 1174 1175| 类型 | 说明 | 1176| ------ | --------- | 1177| number | 最大的行宽，浮点数，单位为物理像素px。| 1178 1179**示例：** 1180 1181```ts 1182let maxWidth = paragraph.getMaxWidth(); 1183``` 1184 1185### getHeight 1186 1187getHeight(): number 1188 1189获取文本总高度。 1190 1191**系统能力**：SystemCapability.Graphics.Drawing 1192 1193**返回值：** 1194 1195| 类型 | 说明 | 1196| ------ | ----- | 1197| number | 总高度，浮点数，单位为物理像素px。| 1198 1199**示例：** 1200 1201```ts 1202let height = paragraph.getHeight(); 1203``` 1204 1205### getLongestLine 1206 1207getLongestLine(): number 1208 1209获取文本最长行宽。 1210 1211**系统能力**：SystemCapability.Graphics.Drawing 1212 1213**返回值：** 1214 1215| 类型 | 说明 | 1216| ------ | ------------- | 1217| number | 最长一行的宽度，浮点数，单位为物理像素px。| 1218 1219**示例：** 1220 1221```ts 1222let longestLine = paragraph.getLongestLine(); 1223``` 1224 1225### getLongestLineWithIndent<sup>13+</sup> 1226 1227getLongestLineWithIndent(): number 1228 1229获取文本最长一行的宽度（包含缩进），建议向上取整。文本内容为空时返回0。 1230 1231**系统能力**：SystemCapability.Graphics.Drawing 1232 1233**返回值：** 1234 1235| 类型 | 说明 | 1236| ------ | ------------- | 1237| number | 最长一行的宽度（该宽度包含当前行缩进的宽度），浮点数，单位为物理像素px。| 1238 1239**示例：** 1240 1241```ts 1242let longestLineWithIndent = paragraph.getLongestLineWithIndent(); 1243``` 1244 1245### getMinIntrinsicWidth 1246 1247getMinIntrinsicWidth(): number 1248 1249获取段落最小固有宽度。 1250 1251**系统能力**：SystemCapability.Graphics.Drawing 1252 1253**返回值：** 1254 1255| 类型 | 说明 | 1256| ------ | ----------------------------- | 1257| number | 该段落所占水平空间的最小固有宽度，浮点数，单位为物理像素px。| 1258 1259**示例：** 1260 1261```ts 1262let minIntrinsicWidth = paragraph.getMinIntrinsicWidth(); 1263``` 1264 1265### getMaxIntrinsicWidth 1266 1267getMaxIntrinsicWidth(): number 1268 1269获取段落最大固有宽度。 1270 1271**系统能力**：SystemCapability.Graphics.Drawing 1272 1273**返回值：** 1274 1275| 类型 | 说明 | 1276| ------ | ----------------------------- | 1277| number | 该段落所占水平空间的最大固有宽度，浮点数，单位为物理像素px。| 1278 1279**示例：** 1280 1281```ts 1282let maxIntrinsicWidth = paragraph.getMaxIntrinsicWidth(); 1283``` 1284 1285### getAlphabeticBaseline 1286 1287getAlphabeticBaseline(): number 1288 1289获取拉丁字母基线位置。 1290 1291**系统能力**：SystemCapability.Graphics.Drawing 1292 1293**返回值：** 1294 1295| 类型 | 说明 | 1296| ------ | ------------------ | 1297| number | 拉丁字母下的基线位置，浮点数，单位为物理像素px。| 1298 1299**示例：** 1300 1301```ts 1302let alphabeticBaseline = paragraph.getAlphabeticBaseline(); 1303``` 1304 1305### getIdeographicBaseline 1306 1307getIdeographicBaseline(): number 1308 1309获取表意字（如CJK（中文，日文，韩文））下的基线位置。 1310 1311**系统能力**：SystemCapability.Graphics.Drawing 1312 1313**返回值：** 1314 1315| 类型 | 说明 | 1316| ------ | -------------------- | 1317| number | 获取表意字下的基线位置，浮点数，单位为物理像素px。| 1318 1319**示例：** 1320 1321```ts 1322let ideographicBaseline = paragraph.getIdeographicBaseline(); 1323``` 1324 1325### getRectsForRange 1326 1327getRectsForRange(range: Range, widthStyle: RectWidthStyle, heightStyle: RectHeightStyle): Array\<TextBox> 1328 1329获取给定的矩形区域宽度以及矩形区域高度的规格下，文本中该区间范围内的字符所占的矩形区域。 1330 1331**系统能力**：SystemCapability.Graphics.Drawing 1332 1333**参数：** 1334 1335| 参数名 | 类型 | 必填 | 说明 | 1336| ----------- | ----------------------------------- | ---- | ------------------------ | 1337| range | [Range](#range) | 是 | 需要获取的区域的文本区间。 | 1338| widthStyle | [RectWidthStyle](#rectwidthstyle) | 是 | 返回的矩形区域的宽度的规格。| 1339| heightStyle | [RectHeightStyle](#rectheightstyle) | 是 | 返回的矩形区域的高度的规格。| 1340 1341**返回值：** 1342 1343| 类型 | 说明 | 1344| --------------------------- | ----------- | 1345| Array\<[TextBox](#textbox)> | 矩形区域数组。| 1346 1347**示例：** 1348 1349```ts 1350let range: text.Range = { start: 0, end: 1}; 1351let rects = paragraph.getRectsForRange(range, text.RectWidthStyle.TIGHT, text.RectHeightStyle.TIGHT); 1352``` 1353 1354### getRectsForPlaceholders 1355 1356getRectsForPlaceholders(): Array\<TextBox> 1357 1358获取文本中所有占位符所占的矩形区域。 1359 1360**系统能力**：SystemCapability.Graphics.Drawing 1361 1362**返回值：** 1363 1364| 类型 | 说明 | 1365| --------------------------- | ----------- | 1366| Array\<[TextBox](#textbox)> | 矩形区域数组。| 1367 1368**示例：** 1369 1370```ts 1371let placeholderRects = paragraph.getRectsForPlaceholders(); 1372``` 1373 1374### getGlyphPositionAtCoordinate 1375 1376getGlyphPositionAtCoordinate(x: number, y: number): PositionWithAffinity 1377 1378获取与给定坐标最接近的字形位置信息。 1379 1380**系统能力**：SystemCapability.Graphics.Drawing 1381 1382**参数：** 1383 1384| 参数名 | 类型 | 必填 | 说明 | 1385| ----- | ------ | ---- | ------ | 1386| x | number | 是 | 横坐标，浮点数。| 1387| y | number | 是 | 纵坐标，浮点数。| 1388 1389**返回值：** 1390 1391| 类型 | 说明 | 1392| --------------------------------------------- | ----------- | 1393| [PositionWithAffinity](#positionwithaffinity) | 字形位置信息。| 1394 1395**示例：** 1396 1397```ts 1398let positionWithAffinity = paragraph.getGlyphPositionAtCoordinate(0, 0); 1399``` 1400 1401### getWordBoundary 1402 1403getWordBoundary(offset: number): Range 1404 1405返回给定offset的字形所在单词的索引区间。 1406 1407**系统能力**：SystemCapability.Graphics.Drawing 1408 1409**参数：** 1410 1411| 参数名 | 类型 | 必填 | 说明 | 1412| ------ | ------ | ---- | ----------- | 1413| offset | number | 是 | 字形的偏移量，整数。| 1414 1415**返回值：** 1416 1417| 类型 | 说明 | 1418| --------------- | -------------- | 1419| [Range](#range) | 单词的索引区间。| 1420 1421**示例：** 1422 1423```ts 1424let wordRange = paragraph.getWordBoundary(0); 1425``` 1426 1427### getLineCount 1428 1429getLineCount(): number 1430 1431返回文本行数。 1432 1433**系统能力**：SystemCapability.Graphics.Drawing 1434 1435**返回值：** 1436 1437| 类型 | 说明 | 1438| ------ | --------- | 1439| number | 文本行数量，整数。| 1440 1441**示例：** 1442 1443```ts 1444let lineCount = paragraph.getLineCount(); 1445``` 1446 1447### getLineHeight 1448 1449getLineHeight(line: number): number 1450 1451返回指定行的行高。 1452 1453**系统能力**：SystemCapability.Graphics.Drawing 1454 1455**参数：** 1456 1457| 参数名 | 类型 | 必填 | 说明 | 1458| ----- | ------ | ---- | --------- | 1459| line | number | 是 | 文本行索引，整数，范围为0~getLineCount()-1。| 1460 1461**返回值：** 1462 1463| 类型 | 说明 | 1464| ------ | ---- | 1465| number | 行高。| 1466 1467**示例：** 1468 1469```ts 1470let lineHeight = paragraph.getLineHeight(0); 1471``` 1472 1473### getLineWidth 1474 1475getLineWidth(line: number): number 1476 1477返回指定行的行宽。 1478 1479**系统能力**：SystemCapability.Graphics.Drawing 1480 1481**参数：** 1482 1483| 参数名 | 类型 | 必填 | 说明 | 1484| ----- | ------ | ---- | --------- | 1485| line | number | 是 | 文本行索引，整数，范围为0~getLineCount()-1。| 1486 1487**返回值：** 1488 1489| 类型 | 说明 | 1490| ------ | ---- | 1491| number | 行宽。| 1492 1493**示例：** 1494 1495```ts 1496let lineWidth = paragraph.getLineWidth(0); 1497``` 1498 1499### didExceedMaxLines 1500 1501didExceedMaxLines(): boolean 1502 1503返回段落是否超过最大行数。 1504 1505**系统能力**：SystemCapability.Graphics.Drawing 1506 1507**返回值：** 1508 1509| 类型 | 说明 | 1510| ------- | -------------------------------------------------------- | 1511| boolean | true表示段落超出了最大行限制，false则表示没有超出最大行限制。 | 1512 1513**示例：** 1514 1515```ts 1516let didExceed = paragraph.didExceedMaxLines(); 1517``` 1518 1519### getTextLines 1520 1521getTextLines(): Array\<TextLine> 1522 1523返回所有的文本行。 1524 1525**系统能力**：SystemCapability.Graphics.Drawing 1526 1527**返回值：** 1528 1529| 类型 | 说明 | 1530| ----------------------------- | ------------- | 1531| Array\<[TextLine](#textline)> | 文本行载体数组。| 1532 1533**示例：** 1534 1535```ts 1536let lines = paragraph.getTextLines(); 1537``` 1538 1539### getActualTextRange 1540 1541getActualTextRange(lineNumber: number, includeSpaces: boolean): Range 1542 1543获取指定行的实际可见文本范围，不包括溢出的省略号。 1544 1545**系统能力**：SystemCapability.Graphics.Drawing 1546 1547**参数：** 1548 1549| 参数名 | 类型 | 必填 | 说明 | 1550| ----- | ------ | ---- | --------- | 1551| lineNumber | number | 是 | 要获取文本范围的行索引，行索引从0开始。该接口只能获取已有行的边界，即输入行索引从0开始。最大行索引为文本行数量-1，文本行数量可通过[getLineCount](#getlinecount)接口获取。| 1552| includeSpaces | boolean | 是 | 表示是否应包含空白字符。true表示包含空白字符，false表示不包含空白字符。| 1553 1554**返回值：** 1555 1556| 类型 | 说明 | 1557| ---------------- | ------------------------------------------------ | 1558| [Range](#range) | 返回对应行数的实际文本范围。如果行索引非法，返回的start和end均为0。 | 1559 1560**示例：** 1561 1562```ts 1563let rang = paragraph.getActualTextRange(0, true); 1564``` 1565 1566 1567### getLineMetrics 1568 1569getLineMetrics(): Array\<LineMetrics> 1570 1571获取文本行的行度量数组。 1572 1573**系统能力**：SystemCapability.Graphics.Drawing 1574 1575**返回值：** 1576 1577| 类型 | 说明 | 1578| ----------------------------- | ------------- | 1579| Array\<[LineMetrics](#linemetrics)> | 文本行的行度量数组。| 1580 1581**示例：** 1582 1583```ts 1584let arrLineMetrc = paragraph.getLineMetrics(); 1585``` 1586 1587### getLineMetrics 1588 1589getLineMetrics(lineNumber: number): LineMetrics | undefined 1590 1591获取特定行号的行度量信息。 1592 1593**系统能力**：SystemCapability.Graphics.Drawing 1594 1595**参数：** 1596 1597| 参数名 | 类型 | 必填 | 说明 | 1598| ----- | ------ | ---- | --------- | 1599| lineNumber | number | 是 | 要查询度量信息的行的编号，行号从0开始。| 1600 1601**返回值：** 1602 1603| 类型 | 说明 | 1604| ---------------- | ------------------------------------------------ | 1605| [LineMetrics](#linemetrics) \| undefined | 如果指定的行号有效且度量信息存在，则返回一个包含该行度量数据的LineMetrics对象；如果行号无效或无法获取度量信息，则返回undefined。 | 1606 1607**示例：** 1608 1609```ts 1610let lineMetrics = paragraph.getLineMetrics(0); 1611``` 1612 1613### updateColor<sup>20+</sup> 1614 1615updateColor(color: common2D.Color): void; 1616 1617更新整个文本段落的颜色。如果当前装饰线未设置颜色，使用该接口也会同时更新装饰线的颜色。 1618 1619**系统能力**：SystemCapability.Graphics.Drawing 1620 1621**参数：** 1622 1623| 参数名 | 类型 | 必填 | 说明 | 1624| ------ | ---------------------------------------------------- | ---- | ---------------------- | 1625| color | [common2D.Color](js-apis-graphics-common2D.md#color) | 是 | 更新后的字体色。| 1626 1627**示例：** 1628 1629```ts 1630paragraph.updateColor({ alpha: 255, red: 255, green: 0, blue: 0 }); 1631``` 1632 1633### updateDecoration<sup>20+</sup> 1634 1635updateDecoration(decoration: Decoration): void; 1636 1637更新整个文本段落的装饰线。 1638 1639**系统能力**：SystemCapability.Graphics.Drawing 1640 1641**参数：** 1642 1643| 参数名 | 类型 | 必填 | 说明 | 1644| ------ | ---------------------------------------------------- | ---- | ---------------------- | 1645| decoration | [Decoration](#decoration) | 是 | 更新后的装饰线。| 1646 1647**示例：** 1648 1649```ts 1650paragraph.updateDecoration({ 1651 textDecoration: text.TextDecorationType.OVERLINE, 1652 color: { alpha: 255, red: 255, green: 0, blue: 0 }, 1653 decorationStyle: text.TextDecorationStyle.WAVY, 1654 decorationThicknessScale: 2.0, 1655}); 1656``` 1657 1658## LineTypeset<sup>18+</sup> 1659 1660保存着文本内容以及样式的载体，可以用于计算单行排版信息。 1661 1662下列API示例中都需先使用[ParagraphBuilder](#paragraphbuilder)类的[buildLineTypeset()](#buildlinetypeset18)接口获取到LineTypeset对象实例，再通过此实例调用对应方法。 1663 1664### getLineBreak<sup>18+</sup> 1665 1666getLineBreak(startIndex: number, width: number): number 1667 1668计算在限定宽度下，从指定位置开始可以排版的字符数。 1669 1670**系统能力**：SystemCapability.Graphics.Drawing 1671 1672**参数：** 1673 1674| 参数名 | 类型 | 必填 | 说明 | 1675| ----- | ------ | ---- | -------------- | 1676| startIndex | number | 是 | 开始计算排版的起始位置（包括起始位置）。取值范围需要为[0,文本字符总数）的整数，参数非法时抛出异常。| 1677| width | number | 是 | 可用于排版的宽度，大于0的浮点数，单位为物理像素px。| 1678 1679**返回值：** 1680 1681| 类型 | 说明 | 1682| ------------ | --------------------------- | 1683| number | 返回在限定排版宽度下，从指定位置开始可排版的字符总数，取值为整数。| 1684 1685**错误码：** 1686 1687以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1688 1689| 错误码ID | 错误信息 | 1690| ------- | --------------------------------------------| 1691| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3. Parameter verification failed. | 1692 1693**示例：** 1694 1695```ts 1696let startIndex = 0; 1697let width = 100.0; 1698let count = lineTypeset.getLineBreak(startIndex, width); 1699``` 1700 1701### createLine<sup>18+</sup> 1702 1703createLine(startIndex: number, count: number): TextLine 1704 1705根据指定的排版区间生成文本行对象。 1706 1707**系统能力**：SystemCapability.Graphics.Drawing 1708 1709**参数：** 1710 1711| 参数名 | 类型 | 必填 | 说明 | 1712| ----- | ------ | ---- | -------------- | 1713| startIndex | number | 是 | 开始计算排版的起始位置，整数，取值范围为[0, 文本字符总数)。| 1714| count | number | 是 | 从指定起始位置开始进行排版的字符个数，取值为[0,文本字符总数)的整数，startIndex和count之和不能大于文本字符总数。当count为0时，表示排版区间为[startIndex, 文本结尾]。可以先使用[getLineBreak](#getlinebreak18)获取合理的排版字符总数。| 1715 1716**返回值：** 1717 1718| 类型 | 说明 | 1719| ------------ | --------------------------- | 1720| [TextLine](#textline) | 根据文本区间字符生成的TextLine对象。| 1721 1722**错误码：** 1723 1724以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1725 1726| 错误码ID | 错误信息 | 1727| ------- | --------------------------------------------| 1728| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3. Parameter verification failed. | 1729 1730**示例：** 1731 1732```ts 1733let startIndex = 0; 1734let width = 100.0; 1735let count = lineTypeset.getLineBreak(startIndex, width); 1736let line : text.TextLine = lineTypeset.createLine(startIndex, count); 1737``` 1738 1739## RunMetrics 1740 1741描述文本行中连续文本块的布局信息和度量数据。 1742 1743**系统能力：** SystemCapability.Graphics.Drawing 1744 1745| 名称 | 类型 | 只读 | 可选 | 说明 | 1746| --------- | -------------------------------------------------- | ---- | ---- | ----------- | 1747| textStyle | [TextStyle](#textstyle) | 否 | 否 | 字体的样式信息。| 1748| fontMetrics | [drawing.FontMetrics](arkts-apis-graphics-drawing-i.md#fontmetrics)| 否 | 否 | 字体度量信息。 | 1749 1750## LineMetrics 1751 1752描述文本布局中单行文字的度量信息。 1753 1754**系统能力：** SystemCapability.Graphics.Drawing 1755 1756| 名称 | 类型 | 只读 | 可选 | 说明 | 1757| --------- | -------------------------------------------------- | ---- | ---- | ----------- | 1758| startIndex | number | 否 | 否 | 文本缓冲区中该行开始的索引位置。| 1759| endIndex | number | 否 | 否 | 文本缓冲区中该行结束的索引位置。| 1760| ascent | number | 否 | 否 | 文字上升高度，即从基线到字符顶部的距离。| 1761| descent | number | 否 | 否 | 文字下降高度，即从基线到字符底部的距离。| 1762| height | number | 否 | 否 | 当前行的高度，计算方式为 `Math.round(ascent + descent)`| 1763| width | number | 否 | 否 | 行的宽度。 | 1764| left | number | 否 | 否 | 行的左边缘位置。右边缘可通过 `left+width` 计算得出。| 1765| baseline | number | 否 | 否 | 该行基线相对于段落顶部的 Y 坐标位置。| 1766| lineNumber | number | 否 | 否 | 行号，从0开始计数。| 1767| topHeight | number | 否 | 否 | 从顶部到当前行的高度。| 1768| runMetrics | Map<number, [RunMetrics](#runmetrics)> | 否 | 否 | 文本索引范围与关联的字体度量信息之间的映射。| 1769 1770## TextBox 1771 1772文本矩形区域。 1773 1774**系统能力：** SystemCapability.Graphics.Drawing 1775 1776| 名称 | 类型 | 只读 | 可选 | 说明 | 1777| --------- | -------------------------------------------------- | ---- | ---- | ----------- | 1778| rect | [common2D.Rect](js-apis-graphics-common2D.md#rect) | 否 | 否 | 矩形区域信息。| 1779| direction | [TextDirection](#textdirection) | 否 | 否 | 文本方向。 | 1780 1781## PositionWithAffinity 1782 1783位置和亲和度。 1784 1785**系统能力：** SystemCapability.Graphics.Drawing 1786 1787| 名称 | 类型 | 只读 | 可选 | 说明 | 1788| --------- | --------------------- | ---- | ---- | ------------------------ | 1789| position | number | 否 | 否 | 字形相对于段落的索引，整数。 | 1790| affinity | [Affinity](#affinity) | 否 | 否 | 位置亲和度。 | 1791 1792## RectWidthStyle 1793 1794矩形区域宽度规格枚举。 1795 1796**系统能力：** SystemCapability.Graphics.Drawing 1797 1798| 名称 | 值 | 说明 | 1799| ----- | - | -------------------------------------- | 1800| TIGHT | 0 | 不设置letterSpacing时，与字形紧贴，否则包含letterSpacing的宽度。| 1801| MAX | 1 | 扩展宽度，以匹配所有行上最宽矩形的位置。 | 1802 1803## RectHeightStyle 1804 1805矩形区域高度规格枚举。 1806 1807**系统能力：** SystemCapability.Graphics.Drawing 1808 1809| 名称 | 值 | 说明 | 1810| ------------------------- | - | ---------------------------------------------- | 1811| TIGHT | 0 | 与字形紧贴。 | 1812| MAX | 1 | 扩展高度，以匹配所有行上最高矩形的位置。 | 1813| INCLUDE_LINE_SPACE_MIDDLE | 2 | 每个矩形的顶部和底部将覆盖行上方和行下方的一半空间。| 1814| INCLUDE_LINE_SPACE_TOP | 3 | 行间距将被添加到矩形的顶部。 | 1815| INCLUDE_LINE_SPACE_BOTTOM | 4 | 行间距将被添加到矩形的底部。 | 1816| STRUT | 5 | 高度按照文本的样式设置。 | 1817 1818## Affinity 1819 1820位置亲和度枚举。 1821 1822**系统能力：** SystemCapability.Graphics.Drawing 1823 1824| 名称 | 值 | 说明 | 1825| ---------- | - | ----------------------------- | 1826| UPSTREAM | 0 | 该位置与文本位置的前一位有关联。 | 1827| DOWNSTREAM | 1 | 该位置与文本位置的后一位有关联。 | 1828 1829## ParagraphBuilder 1830 1831段落生成器。 1832 1833### constructor 1834 1835constructor(paragraphStyle: ParagraphStyle, fontCollection: FontCollection) 1836 1837ParagraphBuilder对象的构造函数。 1838 1839**系统能力**：SystemCapability.Graphics.Drawing 1840 1841**参数：** 1842 1843| 参数名 | 类型 | 必填 | 说明 | 1844| -------------- | --------------------------------- | ---- | ----------- | 1845| paragraphStyle | [ParagraphStyle](#paragraphstyle) | 是 | 段落样式。 | 1846| fontCollection | [FontCollection](#fontcollection) | 是 | 字体集。 | 1847 1848**示例：** 1849 1850```ts 1851import { text } from '@kit.ArkGraphics2D' 1852 1853function textFunc() { 1854 let myTextStyle: text.TextStyle = { 1855 color: { alpha: 255, red: 255, green: 0, blue: 0 }, 1856 fontSize: 33, 1857 }; 1858 let myParagraphStyle: text.ParagraphStyle = { 1859 textStyle: myTextStyle, 1860 align: text.TextAlign.END, 1861 }; 1862 let fontCollection = new text.FontCollection(); 1863 let paragraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection); 1864} 1865 1866@Entry 1867@Component 1868struct Index { 1869 fun: Function = textFunc; 1870 build() { 1871 Column() { 1872 Button().onClick(() => { 1873 this.fun(); 1874 }) 1875 } 1876 } 1877} 1878``` 1879 1880### pushStyle 1881 1882 pushStyle(textStyle: TextStyle): void 1883 1884更新当前文本块的样式。 1885 1886> **说明：** 1887> 1888> 更新当前文本块的样式，之后添加文字均采用该样式。 1889 1890**系统能力**：SystemCapability.Graphics.Drawing 1891 1892**参数：** 1893 1894| 参数名 | 类型 | 必填 | 说明 | 1895| --------- | --------- | ---- | ------------------------------------------------------------------------------------------------------ | 1896| textStyle | [TextStyle](#textstyle) | 是 | 包含了对文本的各种视觉属性的定义，如字体、字号、颜色、字重、字间距、行距、装饰（如下划线、删除线）、文本阴影等。 | 1897 1898**示例：** 1899 1900```ts 1901import { drawing } from '@kit.ArkGraphics2D' 1902import { text } from '@kit.ArkGraphics2D' 1903import { common2D } from '@kit.ArkGraphics2D' 1904import { image } from '@kit.ImageKit' 1905 1906function textFunc() { 1907 let myTextStyle: text.TextStyle = { 1908 color: { alpha: 255, red: 255, green: 0, blue: 0 }, 1909 fontSize: 33, 1910 }; 1911 let myParagraphStyle: text.ParagraphStyle = { 1912 textStyle: myTextStyle, 1913 align: text.TextAlign.CENTER, 1914 }; 1915 let fontCollection = new text.FontCollection(); 1916 let paragraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection); 1917 paragraphBuilder.pushStyle(myTextStyle); 1918} 1919 1920@Entry 1921@Component 1922struct Index { 1923 fun: Function = textFunc; 1924 build() { 1925 Column() { 1926 Button().onClick(() => { 1927 this.fun(); 1928 }) 1929 } 1930 } 1931} 1932``` 1933 1934### popStyle 1935 1936popStyle(): void 1937 1938弹出当前文本样式。 1939 1940**系统能力**：SystemCapability.Graphics.Drawing 1941 1942**示例：** 1943 1944```ts 1945import { drawing } from '@kit.ArkGraphics2D' 1946import { text } from '@kit.ArkGraphics2D' 1947import { common2D } from '@kit.ArkGraphics2D' 1948import { image } from '@kit.ImageKit' 1949 1950function textFunc() { 1951 let myTextStyle: text.TextStyle = { 1952 color: { alpha: 255, red: 255, green: 0, blue: 0 }, 1953 fontSize: 33, 1954 }; 1955 let myParagraphStyle: text.ParagraphStyle = { 1956 textStyle: myTextStyle, 1957 align: text.TextAlign.END, 1958 }; 1959 let fontCollection = new text.FontCollection(); 1960 let paragraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection); 1961 paragraphBuilder.pushStyle(myTextStyle); 1962 paragraphBuilder.popStyle(); 1963} 1964 1965@Entry 1966@Component 1967struct Index { 1968 fun: Function = textFunc; 1969 build() { 1970 Column() { 1971 Button().onClick(() => { 1972 this.fun(); 1973 }) 1974 } 1975 } 1976} 1977``` 1978 1979### addText 1980 1981addText(text: string): void 1982 1983向正在构建的文本段落中插入具体的文本字符串。 1984 1985**系统能力**：SystemCapability.Graphics.Drawing 1986 1987**参数：** 1988 1989| 参数名 | 类型 | 必填 | 说明 | 1990| ------- | ------- | ---- | -------------------------- | 1991| text | string | 是 | 段落中插入的具体文本字符串，传入非法Unicode时会显示�。 | 1992 1993**示例：** 1994 1995```ts 1996import { drawing } from '@kit.ArkGraphics2D' 1997import { text } from '@kit.ArkGraphics2D' 1998import { common2D } from '@kit.ArkGraphics2D' 1999import { image } from '@kit.ImageKit' 2000 2001function textFunc() { 2002 let myTextStyle: text.TextStyle = { 2003 color: { alpha: 255, red: 255, green: 0, blue: 0 }, 2004 fontSize: 33, 2005 }; 2006 let myParagraphStyle: text.ParagraphStyle = { 2007 textStyle: myTextStyle, 2008 align: text.TextAlign.END, 2009 }; 2010 let fontCollection = new text.FontCollection(); 2011 let paragraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection); 2012 paragraphBuilder.addText("123666"); 2013} 2014 2015@Entry 2016@Component 2017struct Index { 2018 fun: Function = textFunc; 2019 build() { 2020 Column() { 2021 Button().onClick(() => { 2022 this.fun(); 2023 }) 2024 } 2025 } 2026} 2027``` 2028 2029### addPlaceholder 2030 2031addPlaceholder(placeholderSpan: PlaceholderSpan): void 2032 2033用于构建文本段落时插入占位符。 2034 2035**系统能力**：SystemCapability.Graphics.Drawing 2036 2037**参数：** 2038 2039| 参数名 | 类型 | 必填 | 说明 | 2040| --------------- | ----------------------------------- | ---- | --------------------------------------------------- | 2041| placeholderSpan | [PlaceholderSpan](#placeholderspan) | 是 | 定义了占位符的尺寸、对齐方式、基线类型以及基线偏移量。 | 2042 2043**示例：** 2044 2045```ts 2046import { drawing } from '@kit.ArkGraphics2D' 2047import { text } from '@kit.ArkGraphics2D' 2048import { common2D } from '@kit.ArkGraphics2D' 2049import { image } from '@kit.ImageKit' 2050 2051function textFunc() { 2052 let myParagraphStyle: text.ParagraphStyle = { 2053 align: text.TextAlign.END, 2054 }; 2055 let myPlaceholderSpan: text.PlaceholderSpan = { 2056 width: 100, 2057 height: 100, 2058 align: text.PlaceholderAlignment.ABOVE_BASELINE, 2059 baseline: text.TextBaseline.ALPHABETIC, 2060 baselineOffset: 100 2061 }; 2062 let fontCollection = new text.FontCollection(); 2063 let paragraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection); 2064 paragraphBuilder.addPlaceholder(myPlaceholderSpan); 2065} 2066 2067@Entry 2068@Component 2069struct Index { 2070 fun: Function = textFunc; 2071 build() { 2072 Column() { 2073 Button().onClick(() => { 2074 this.fun(); 2075 }) 2076 } 2077 } 2078} 2079``` 2080 2081### build 2082 2083build(): Paragraph 2084 2085用于构建段落，生成可用于后续排版渲染的段落对象。 2086 2087**系统能力**：SystemCapability.Graphics.Drawing 2088 2089**返回值：** 2090 2091| 类型 | 说明 | 2092| ------------------------ | ------------------------------ | 2093| [Paragraph](#paragraph) | 可用于后续渲染的 Paragraph 对象。| 2094 2095**示例：** 2096 2097```ts 2098import { drawing, text, common2D } from '@kit.ArkGraphics2D' 2099import { image } from '@kit.ImageKit' 2100 2101function textFunc() { 2102 let myTextStyle: text.TextStyle = { 2103 color : {alpha: 255, red: 255, green: 0, blue: 0}, 2104 fontSize : 20, 2105 }; 2106 let myParagraphStyle: text.ParagraphStyle = { 2107 textStyle : myTextStyle, 2108 }; 2109 let fontCollection = new text.FontCollection(); 2110 let paragraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection); 2111 paragraphBuilder.addText("123456789"); 2112 let paragraph = paragraphBuilder.build(); 2113 paragraph.layoutSync(200); 2114} 2115 2116@Entry 2117@Component 2118struct Index { 2119 fun: Function = textFunc; 2120 build() { 2121 Column() { 2122 Button().onClick(() => { 2123 this.fun(); 2124 }) 2125 } 2126 } 2127} 2128``` 2129 2130### buildLineTypeset<sup>18+</sup> 2131 2132buildLineTypeset(): LineTypeset 2133 2134构建行排版器。 2135 2136**系统能力**：SystemCapability.Graphics.Drawing 2137 2138**返回值：** 2139 2140| 类型 | 说明 | 2141| ------------------------ | ------------------------------ | 2142| [LineTypeset](#linetypeset18) | 可用于后续渲染的LineTypeset对象。| 2143 2144**示例：** 2145 2146```ts 2147import { text } from '@kit.ArkGraphics2D' 2148 2149function test() { 2150 let myParagraphStyle: text.ParagraphStyle = { 2151 align: text.TextAlign.JUSTIFY, 2152 }; 2153 let fontCollection = new text.FontCollection(); 2154 let paragraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection); 2155 paragraphBuilder.addText("123456789"); 2156 let lineTypeset = paragraphBuilder.buildLineTypeset(); 2157} 2158 2159@Entry 2160@Component 2161struct Index { 2162 fun: Function = test; 2163 build() { 2164 Column() { 2165 Button().onClick(() => { 2166 this.fun(); 2167 }) 2168 } 2169 } 2170} 2171``` 2172 2173### addSymbol 2174 2175addSymbol(symbolId: number): void 2176 2177向正在构建的文本段落中插入具体符号。 2178 2179**系统能力**：SystemCapability.Graphics.Drawing 2180 2181**参数：** 2182 2183| 参数名 | 类型 | 必填 | 说明 | 2184| -------- | ------- | ---- | ----------------------------------------------------------- | 2185| symbolId | number | 是 | 要设置的symbol码位，十六进制，当前支持的取值范围为：0xF0000-0xF0C97。可设置的symbol码位（即列表视图下的unicode值）请见[主题图标库](https://developer.huawei.com/consumer/cn/design/harmonyos-symbol/)。| 2186 2187**示例：** 2188 2189```ts 2190import { text } from '@kit.ArkGraphics2D' 2191 2192function textFunc() { 2193 let myTextStyle: text.TextStyle = { 2194 color: { alpha: 255, red: 255, green: 0, blue: 0 }, 2195 fontSize: 33, 2196 }; 2197 let myParagraphStyle: text.ParagraphStyle = { 2198 textStyle: myTextStyle, 2199 align: text.TextAlign.END, 2200 }; 2201 let fontCollection = new text.FontCollection(); 2202 let paragraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection); 2203 paragraphBuilder.addSymbol(0xF0000); 2204 let paragraph = paragraphBuilder.build(); 2205} 2206 2207@Entry 2208@Component 2209struct Index { 2210 fun: Function = textFunc; 2211 build() { 2212 Column() { 2213 Button().onClick(() => { 2214 this.fun(); 2215 }) 2216 } 2217 } 2218} 2219``` 2220 2221## TypographicBounds<sup>18+</sup> 2222 2223文本行的排版边界。文本行排版边界与排版字体、排版字号有关，与字符本身无关，例如字符串为" a b "，'a'字符前面有1个空格，'b'字符后面有1个空格，排版边界就包括行首和末尾空格的边界。例如字符串为"j"或"E"，排版边界相同，即与字符本身无关。 2224 2225**系统能力：** SystemCapability.Graphics.Drawing 2226 2227| 名称 | 类型 | 只读 | 可选 | 说明 | 2228| - | - | - | - | - | 2229| ascent | number | 否 | 否 | 文本行的上升高度，浮点数。 | 2230| descent | number | 否 | 否 | 文本行的下降高度，浮点数。 | 2231| leading | number | 否 | 否 | 文本行的行间距，浮点数。 | 2232| width | number | 否 | 否 | 排版边界的总宽度，浮点数。 | 2233 2234>**说明：** 2235> 2236>示意图展示了ascent、descent、leading、top、baseline、bottom、next line top的含义。width为文本行排版包括左右空格的宽度。ascent为文本行上升高度最高点，descent为文本行下降高度最低点，leading为文本行间距，top为文本行的最高点，baseline为字符基线，bottom为文本行的最低点，next line top为下一个文本行的最高点。 2237> 2238> 2239> 2240>示意图展示了字符串为" a b "的排版边界。 2241> 2242> 2243> 2244>示意图展示了字符串为"j"或"E"的排版边界。 2245> 2246> 2247 2248## CaretOffsetsCallback<sup>18+</sup> 2249 2250type CaretOffsetsCallback = (offset: number, index: number, leadingEdge: boolean) => boolean 2251 2252将文本行中每个字符的偏移量和索引值作为参数的回调方法。 2253 2254**系统能力：** SystemCapability.Graphics.Drawing 2255 2256**参数：** 2257| 参数名 | 类型 | 必填 | 说明 | 2258| - | - | - | - | 2259| offset | number | 是 | 文本行中每个字符的偏移量，浮点数。 | 2260| index | number | 是 | 文本行中每个字符的索引值，整数。 | 2261| leadingEdge | boolean | 是 | 光标是否位于字符的前缘，true表示位于字符前缘，即偏移量不包含该字符宽度，false表示位于字符后缘，即偏移量包含该字符宽度。 | 2262 2263**返回值：** 2264 2265| 类型 | 说明 | 2266| - | - | 2267| boolean | 表示是否停止调用该回调函数，true表示停止调用该回调函数，false表示继续调用该回调函数。 | 2268 2269## TextLine 2270 2271描述段落基础文本行结构的载体。 2272 2273下列API示例中都需先使用[Paragraph](#paragraph)类的[getTextLines()](#gettextlines)接口或者[LineTypeset](#linetypeset18)类的[createLine()](#createline18)接口获取到TextLine对象实例，再通过此实例调用对应方法。 2274### getGlyphCount 2275 2276getGlyphCount(): number 2277 2278获取文本行中字形的数量。 2279 2280**系统能力**：SystemCapability.Graphics.Drawing 2281 2282**返回值：** 2283 2284| 类型 | 说明 | 2285| ------- | ------------------ | 2286| number | 该文本行中字形数量，整数。 | 2287 2288**示例：** 2289 2290```ts 2291let glyphCount = lines[0].getGlyphCount(); 2292``` 2293 2294### getTextRange 2295 2296getTextRange(): Range 2297 2298获取该行文本在整个段落文本中的索引区间。 2299 2300**系统能力**：SystemCapability.Graphics.Drawing 2301 2302**返回值：** 2303 2304| 类型 | 说明 | 2305| ---------------- | ------------------------------------------------ | 2306| [Range](#range) | 该行文本在整个段落文本中的索引区间。| 2307 2308**示例：** 2309 2310```ts 2311let textRange = lines[0].getTextRange(); 2312``` 2313 2314### getGlyphRuns 2315 2316getGlyphRuns(): Array\<Run> 2317 2318获取文本行的排版单元数组。 2319 2320**系统能力**：SystemCapability.Graphics.Drawing 2321 2322**返回值：** 2323 2324| 类型 | 说明 | 2325| ------------ | --------------------------- | 2326| Array\<[Run](#run)> | 该文本行中的文本排版单元数组。| 2327 2328**示例：** 2329 2330```ts 2331let runs = lines[0].getGlyphRuns(); 2332``` 2333 2334### paint 2335 2336paint(canvas: drawing.Canvas, x: number, y: number): void 2337 2338在画布上以坐标点(x, y)为左上角位置绘制该文本行。 2339 2340**系统能力**：SystemCapability.Graphics.Drawing 2341 2342**参数：** 2343 2344| 参数名 | 类型 | 必填 | 说明 | 2345| ------ | ---------------------------------------------------- | ---- | ---------------------- | 2346| canvas | [drawing.Canvas](arkts-apis-graphics-drawing-Canvas.md) | 是 | 绘制的目标canvas。 | 2347| x | number | 是 | 绘制的左上角位置的横坐标，浮点数。| 2348| y | number | 是 | 绘制的左上角位置的纵坐标，浮点数。| 2349 2350**示例：** 2351 2352<!--code_no_check--> 2353```ts 2354import { drawing } from '@kit.ArkGraphics2D' 2355import { text } from '@kit.ArkGraphics2D' 2356import { common2D } from '@kit.ArkGraphics2D' 2357import { image } from '@kit.ImageKit' 2358 2359function textFunc(pixelmap: PixelMap) { 2360 let canvas = new drawing.Canvas(pixelmap); 2361 lines[0].paint(canvas, 0, 0); 2362} 2363 2364@Entry 2365@Component 2366struct Index { 2367 @State pixelmap?: PixelMap = undefined; 2368 fun: Function = textFunc; 2369 build() { 2370 Column() { 2371 Image(this.pixelmap).width(200).height(200); 2372 Button().onClick(() => { 2373 if (this.pixelmap == undefined) { 2374 const color: ArrayBuffer = new ArrayBuffer(160000); 2375 let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 200, width: 200 } } 2376 this.pixelmap = image.createPixelMapSync(color, opts); 2377 } 2378 this.fun(this.pixelmap); 2379 }) 2380 } 2381 } 2382} 2383``` 2384 2385### createTruncatedLine<sup>18+</sup> 2386 2387createTruncatedLine(width: number, ellipsisMode: EllipsisMode, ellipsis: string): TextLine 2388 2389创建一个截断的文本行对象。 2390 2391**系统能力**：SystemCapability.Graphics.Drawing 2392 2393**参数：** 2394 2395| 参数名 | 类型 | 必填 | 说明 | 2396| -| - | - |-------------------------------| 2397| width | number | 是 | 截断后的行宽度，浮点数。 | 2398| ellipsisMode | [EllipsisMode](#ellipsismode) | 是 | 截断的类型，当前仅支持头部截断START和尾部截断END。 | 2399| ellipsis | string | 是 | 截断的标记字符串。 | 2400 2401**返回值：** 2402 2403| 类型 | 说明 | 2404| ------------ | --------------------------- | 2405| [TextLine](#textline) | 截断的文本行对象。| 2406 2407**示例：** 2408 2409<!--code_no_check--> 2410```ts 2411import { drawing, text, common2D } from '@kit.ArkGraphics2D' 2412import { image } from '@kit.ImageKit' 2413 2414function textFunc(pixelmap: PixelMap) { 2415 let canvas = new drawing.Canvas(pixelmap); 2416 let truncatedTextLine = lines[0].createTruncatedLine(100, text.EllipsisMode.START, "..."); 2417 truncatedTextLine.paint(canvas, 0, 100); 2418} 2419 2420@Entry 2421@Component 2422struct Index { 2423 @State pixelmap?: PixelMap = undefined; 2424 fun: Function = textFunc; 2425 build() { 2426 Column() { 2427 Image(this.pixelmap).width(200).height(200); 2428 Button().onClick(() => { 2429 if (this.pixelmap == undefined) { 2430 const color: ArrayBuffer = new ArrayBuffer(160000); 2431 let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 200, width: 200 } } 2432 this.pixelmap = image.createPixelMapSync(color, opts); 2433 } 2434 this.fun(this.pixelmap); 2435 }) 2436 } 2437 } 2438} 2439``` 2440 2441### getTypographicBounds<sup>18+</sup> 2442 2443getTypographicBounds(): TypographicBounds 2444 2445获取文本行的排版边界。文本行排版边界与排版字体、排版字号有关，与字符本身无关。例如字符串为" a b "，'a'字符前面有1个空格，'b'字符后面有1个空格，排版边界就包括行首和末尾空格的边界。例如字符串为"j"或"E"，排版边界相同，即与字符本身无关。 2446 2447>**说明：** 2448> 2449>示意图展示了字符串为" a b "的排版边界。 2450> 2451> 2452> 2453>示意图展示了字符串为"j"或"E"的排版边界。 2454> 2455> 2456 2457**系统能力**：SystemCapability.Graphics.Drawing 2458 2459**返回值：** 2460 2461| 类型 | 说明 | 2462| -| - | 2463| [TypographicBounds](#typographicbounds18) | 文本行的排版边界。| 2464 2465**示例：** 2466 2467```ts 2468let bounds = lines[0].getTypographicBounds(); 2469console.info('textLine ascent:' + bounds.ascent + ', descent:' + bounds.descent + ', leading:' + bounds.leading + ', width:' + bounds.width); 2470``` 2471 2472### getImageBounds<sup>18+</sup> 2473 2474getImageBounds(): common2D.Rect 2475 2476获取文本行的图像边界。文本行图像边界与排版字体、排版字号、字符本身都有关，相当于视觉边界。例如字符串为" a b "，'a'字符前面有1个空格，'b'字符后面有1个空格，用户在界面上只能看到"a b"，图像边界即为不包括带行首和末尾空格的边界。例如字符串为"j"或"E"，视觉边界不同，即与字符本身有关，"j"字符串的视觉边界宽度小于"E"字符串的视觉边界宽度，"j"字符串的视觉边界高度大于"E"字符串的视觉边界高度。 2477 2478>**说明：** 2479> 2480>示意图展示了字符串为" a b "的图像边界。 2481> 2482> 2483> 2484>示意图展示了字符串为"j"或"E"的图像边界。 2485> 2486> 2487 2488 2489**系统能力**：SystemCapability.Graphics.Drawing 2490 2491**返回值：** 2492 2493| 类型 | 说明 | 2494| ------------ | --------------------------- | 2495| [common2D.Rect](js-apis-graphics-common2D.md#rect) | 文本行的图像边界。| 2496 2497**示例：** 2498 2499```ts 2500let imageBounds = lines[0].getImageBounds(); 2501``` 2502 2503### getTrailingSpaceWidth<sup>18+</sup> 2504 2505getTrailingSpaceWidth(): number 2506 2507获取文本行尾部空白字符的宽度。 2508 2509**系统能力**：SystemCapability.Graphics.Drawing 2510 2511**返回值：** 2512 2513| 类型 | 说明 | 2514| ------------ | --------------------------- | 2515| number | 文本行尾部空白字符的宽度，浮点数。| 2516 2517**示例：** 2518 2519```ts 2520let trailingSpaceWidth = lines[0].getTrailingSpaceWidth(); 2521``` 2522 2523### getStringIndexForPosition<sup>18+</sup> 2524 2525getStringIndexForPosition(point: common2D.Point): number 2526 2527获取给定位置在原始字符串中的字符索引。 2528 2529**系统能力**：SystemCapability.Graphics.Drawing 2530 2531**参数：** 2532 2533| 参数名 | 类型 | 必填 | 说明 | 2534| -| - | - | - | 2535| point | [common2D.Point](js-apis-graphics-common2D.md#point12) | 是 | 要查找索引的位置。| 2536 2537**返回值：** 2538 2539| 类型 | 说明 | 2540| ------------ | --------------------------- | 2541| number | 给定位置在文本行中对应的字符串索引，整数。| 2542 2543**示例：** 2544 2545```ts 2546let point : common2D.Point = { x: 15.0, y: 2.0 }; 2547let index = lines[0].getStringIndexForPosition(point); 2548``` 2549 2550### getOffsetForStringIndex<sup>18+</sup> 2551 2552getOffsetForStringIndex(index: number): number 2553 2554获取文本行中给定字符串索引处的偏移量。 2555 2556**系统能力**：SystemCapability.Graphics.Drawing 2557 2558**参数：** 2559 2560| 参数名 | 类型 | 必填 | 说明 | 2561| -| - | - | - | 2562| index | number | 是 | 要获取偏移量的字符串索引，整数。| 2563 2564**返回值：** 2565 2566| 类型 | 说明 | 2567| ------------ | --------------------------- | 2568| number | 给定字符串索引处的偏移量，浮点数。| 2569 2570**示例：** 2571 2572```ts 2573let offset = lines[0].getOffsetForStringIndex(3); 2574``` 2575 2576### enumerateCaretOffsets<sup>18+</sup> 2577 2578enumerateCaretOffsets(callback: CaretOffsetsCallback): void 2579 2580枚举文本行中每个字符的偏移量和索引值。 2581 2582**系统能力**：SystemCapability.Graphics.Drawing 2583 2584**参数：** 2585 2586| 参数名 | 类型 | 必填 | 说明 | 2587| -| - | - | - | 2588| callback | [CaretOffsetsCallback](#caretoffsetscallback18) | 是 | 用户自定义函数。回调方法参数包括文本行中每个字符的偏移量和索引值。 | 2589 2590**示例：** 2591 2592```ts 2593function callback(offset: number, index: number, leadingEdge: boolean): boolean { 2594 console.info('textLine: offset: ' + offset + ', index: ' + index + ', leadingEdge: ' + leadingEdge); 2595 return index > 50; 2596} 2597lines[0].enumerateCaretOffsets(callback); 2598``` 2599 2600### getAlignmentOffset<sup>18+</sup> 2601 2602getAlignmentOffset(alignmentFactor: number, alignmentWidth: number): number 2603 2604获取文本行根据对齐因子和对齐宽度计算的对齐所需偏移量。 2605 2606**系统能力**：SystemCapability.Graphics.Drawing 2607 2608**参数：** 2609 2610| 参数名 | 类型 | 必填 | 说明 | 2611| -| - | - | - | 2612| alignmentFactor | number | 是 | 对齐因子，即对齐的程度，浮点数。小于等于0.0表示左对齐，大于0.0小于0.5表示偏左对齐，0.5表示居中对齐，大于0.5小于1.0表示偏右对齐，大于等于1.0表示右对齐。| 2613| alignmentWidth | number | 是 | 对齐宽度，即文本行的宽度，浮点数。小于文本行的实际宽度时，返回0。| 2614 2615**返回值：** 2616 2617| 类型 | 说明 | 2618| ------------ | --------------------------- | 2619| number | 计算得到的对齐所需偏移量，浮点数。| 2620 2621**示例：** 2622 2623```ts 2624let alignmentOffset = lines[0].getAlignmentOffset(0.5, 500); 2625``` 2626 2627## Run 2628 2629文本排版单元。 2630 2631下列API示例中都需先使用[TextLine](#textline)类的[getGlyphRuns()](#getglyphruns)接口获取Run对象实例，再通过此实例调用对应方法。 2632 2633### getGlyphCount 2634 2635getGlyphCount(): number 2636 2637获取该排版单元中字形的数量。 2638 2639**系统能力**：SystemCapability.Graphics.Drawing 2640 2641**返回值：** 2642 2643| 类型 | 说明 | 2644| ------- | -------------------- | 2645| number | 该排版单元中字形数量，整数。 | 2646 2647**示例：** 2648 2649```ts 2650let glyphs = runs[0].getGlyphCount(); 2651``` 2652 2653### getGlyphs 2654 2655getGlyphs(): Array\<number> 2656 2657获取该排版单元中每个字符的字形序号。 2658 2659**系统能力**：SystemCapability.Graphics.Drawing 2660 2661**返回值：** 2662 2663| 类型 | 说明 | 2664| --------------- | -------------------------------- | 2665| Array\<number> | 该排版单元中每个字符对应的字形序号。| 2666 2667**示例：** 2668 2669```ts 2670let glyph = runs[0].getGlyphs(); 2671``` 2672 2673### getGlyphs<sup>18+</sup> 2674 2675getGlyphs(range: Range): Array\<number> 2676 2677获取该排版单元指定范围内每个字符的字形序号。 2678 2679**系统能力**：SystemCapability.Graphics.Drawing 2680 2681**参数：** 2682 2683| 参数名 | 类型 | 必填 | 说明 | 2684| -------- | ------- | ---- | -------------------------- | 2685| range | [Range](#range) | 是 | 要获取的字形序号范围，range.start表示范围开始的位置，range.end表示范围的长度，如果长度是0表示从范围range.start开始获取到渲染块结束。当range.end、range.start为负数，或者传入null、undefined时，该方法将返回undefined。| 2686 2687**返回值：** 2688 2689| 类型 | 说明 | 2690| --------------- | -------------------------------- | 2691| Array\<number> | 该排版单元中每个字符对应的字形序号。| 2692 2693**示例：** 2694 2695<!--code_no_check--> 2696```ts 2697import { text } from '@kit.ArkGraphics2D' 2698 2699function textFunc() { 2700 let glyphs = runs[0].getGlyphs(); // 获取渲染块全部字形序号 2701 let glyphsRange = runs[0].getGlyphs({start:1, end:2}); // 获取渲染块从起始位置1开始, 长度为2范围内的字形序号 2702 glyphsRange = runs[0].getGlyphs({start:-1, end:2}); // -1是非法参数，将返回undefined 2703 glyphsRange = runs[0].getGlyphs({start:0, end:-10}); // -10是非法参数，将返回undefined 2704 let glyphsNull = runs[0].getGlyphs(null); // null是非法参数，将返回undefined 2705 let glyphsUndefined = runs[0].getGlyphs(undefined); // undefined是非法参数，将返回undefined 2706} 2707 2708@Entry 2709@Component 2710struct Index { 2711 fun: Function = textFunc; 2712 build() { 2713 Column() { 2714 Button().onClick(() => { 2715 this.fun(); 2716 }) 2717 } 2718 } 2719} 2720``` 2721 2722### getPositions 2723 2724getPositions(): Array<common2D.Point> 2725 2726获取该排版单元中每个字形相对于每行的字形位置。 2727 2728**系统能力**：SystemCapability.Graphics.Drawing 2729 2730**返回值：** 2731 2732| 类型 | 说明 | 2733| ---------------------- | ------------------------------------- | 2734| Array<[common2D.Point](js-apis-graphics-common2D.md#point12)> | 该排版单元中每个字形相对于每行的字形位置。 | 2735 2736**示例：** 2737 2738```ts 2739let positions = runs[0].getPositions(); 2740``` 2741### getPositions<sup>18+</sup> 2742 2743getPositions(range: Range): Array<common2D.Point> 2744 2745获取该排版单元指定范围内每个字形相对于每行的字形位置数组。 2746 2747**系统能力**：SystemCapability.Graphics.Drawing 2748 2749**参数：** 2750 2751| 参数名 | 类型 | 必填 | 说明 | 2752| -------- | ------- | ---- | -------------------------- | 2753| range | [Range](#range) | 是 | 要获取的字形位置范围，range.start表示范围开始的位置，range.end表示范围的长度，如果长度是0表示从范围range.start开始获取到渲染块结束。当range.end、range.start为负数，或者传入null、undefined时，该方法将返回undefined。| 2754 2755**返回值：** 2756 2757| 类型 | 说明 | 2758| ---------------------- | ------------------------------------- | 2759| Array<[common2D.Point](js-apis-graphics-common2D.md#point12)> | 该排版单元中每个字形相对于每行的字形位置。 | 2760 2761**示例：** 2762 2763<!--code_no_check--> 2764```ts 2765import { text } from '@kit.ArkGraphics2D' 2766 2767function textFunc() { 2768 let positions = runs[0].getPositions(); // 获取渲染块全部字形位置 2769 let positionsRange = runs[0].getPositions({start:1, end:2}); // 获取渲染块从起始位置1开始, 长度为2范围内的字形位置 2770 positionsRange = runs[0].getPositions({start:-1, end:2}); // -1是非法参数，将返回undefined 2771 positionsRange = runs[0].getPositions({start:0, end:-10}); // -10是非法参数，将返回undefined 2772 let positionsNull = runs[0].getPositions(null); // null是非法参数，将返回undefined 2773 let positionsUndefined = runs[0].getPositions(undefined); // undefined是非法参数，将返回undefined 2774} 2775 2776@Entry 2777@Component 2778struct Index { 2779 fun: Function = textFunc; 2780 build() { 2781 Column() { 2782 Button().onClick(() => { 2783 this.fun(); 2784 }) 2785 } 2786 } 2787} 2788``` 2789 2790### getOffsets 2791 2792getOffsets(): Array<common2D.Point> 2793 2794获取该排版单元中每个字形的索引偏移量。 2795 2796**系统能力**：SystemCapability.Graphics.Drawing 2797 2798**返回值：** 2799 2800| 类型 | 说明 | 2801| ---------------------- | -------------- | 2802| Array<[common2D.Point](js-apis-graphics-common2D.md#point12)> | 该排版单元中每个字形相对于其索引的偏移量。| 2803 2804**示例：** 2805 2806```ts 2807let offsets = runs[0].getOffsets(); 2808``` 2809 2810### getFont 2811 2812getFont(): drawing.Font 2813 2814获取排版单元的字体属性对象。 2815 2816**系统能力**：SystemCapability.Graphics.Drawing 2817 2818**返回值：** 2819 2820| 类型 | 说明 | 2821| ------------------------------------------------- | -------------------------- | 2822| [drawing.Font](arkts-apis-graphics-drawing-Font.md) | 该排版单元的字体属性对象实例。| 2823 2824**示例：** 2825 2826```ts 2827let font = runs[0].getFont(); 2828``` 2829 2830### paint 2831 2832paint(canvas: drawing.Canvas, x: number, y: number): void 2833 2834在画布上以(x, y)为左上角位置绘制排版单元。 2835 2836**系统能力**：SystemCapability.Graphics.Drawing 2837 2838**参数：** 2839 2840| 参数名 | 类型 | 必填 | 说明 | 2841| ------ | ---------------------------------------------------- | ---- | ---------------------- | 2842| canvas | [drawing.Canvas](arkts-apis-graphics-drawing-Canvas.md) | 是 | 绘制的目标 canvas。 | 2843| x | number | 是 | 绘制的左上角位置的横坐标，浮点数。| 2844| y | number | 是 | 绘制的左上角位置的纵坐标。浮点数。| 2845 2846**示例：** 2847 2848<!--code_no_check--> 2849```ts 2850import { drawing } from '@kit.ArkGraphics2D' 2851import { text } from '@kit.ArkGraphics2D' 2852import { common2D } from '@kit.ArkGraphics2D' 2853import { image } from '@kit.ImageKit' 2854 2855function textFunc(pixelmap: PixelMap) { 2856 let canvas = new drawing.Canvas(pixelmap); 2857 runs[0].paint(canvas, 0, 0); 2858} 2859 2860@Entry 2861@Component 2862struct Index { 2863 @State pixelmap?: PixelMap = undefined; 2864 fun: Function = textFunc; 2865 build() { 2866 Column() { 2867 Image(this.pixelmap).width(200).height(200); 2868 Button().onClick(() => { 2869 if (this.pixelmap == undefined) { 2870 const color: ArrayBuffer = new ArrayBuffer(160000); 2871 let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 200, width: 200 } } 2872 this.pixelmap = image.createPixelMapSync(color, opts); 2873 } 2874 this.fun(this.pixelmap); 2875 }) 2876 } 2877 } 2878} 2879``` 2880 2881### getStringRange<sup>18+</sup> 2882 2883getStringRange(): Range 2884 2885获取排版单元生成字形的字符范围。 2886 2887**系统能力**：SystemCapability.Graphics.Drawing 2888 2889**返回值：** 2890 2891| 类型 | 说明 | 2892| ---------------------- | -------------- | 2893| [Range](#range) | 排版单元生成字形的字符范围，Range类型中的start表示字符范围的开始位置，该位置是相对于整个段落的索引，Range类型中的end表示字符范围的长度。| 2894 2895 2896**示例：** 2897 2898```ts 2899let runStringRange = runs[0].getStringRange(); 2900let location = runStringRange.start; 2901let length = runStringRange.end; 2902``` 2903 2904### getStringIndices<sup>18+</sup> 2905 2906getStringIndices(range?: Range): Array\<number> 2907 2908获取排版单元指定范围内字形的字符索引，该索引是相对于整个段落的偏移。 2909 2910**系统能力**：SystemCapability.Graphics.Drawing 2911 2912**参数：** 2913 2914| 参数名 | 类型 | 必填 | 说明 | 2915| -------- | ------- | ---- | -------------------------- | 2916| range | [Range](#range) | 否 | 要获取的字符索引范围，range.start表示范围开始的位置，range.end表示范围的长度，如果长度是0表示从范围range.start开始获取到渲染块结束。当range.end、range.start为负数，或者传入null、undefined时，该方法将返回undefined。不传该参数时，默认获取整个渲染块。| 2917 2918**返回值：** 2919 2920| 类型 | 说明 | 2921| ---------------------- | -------------- | 2922| Array\<number> | 返回每个字符的索引。| 2923 2924**示例：** 2925 2926<!--code_no_check--> 2927```ts 2928import { text } from '@kit.ArkGraphics2D' 2929 2930function textFunc() { 2931 let indices = runs[0].getStringIndices(); // 获取渲染块全部字符索引 2932 let indicesRange = runs[0].getStringIndices({start:1, end:2}); // 获取渲染块从起始位置1开始, 长度为2范围内的字符索引 2933 indicesRange = runs[0].getStringIndices({start:-1, end:2}); // -1是非法参数，将返回undefined 2934 indicesRange = runs[0].getStringIndices({start:0, end:-10}); // -10是非法参数，将返回undefined 2935 let indicesNull = runs[0].getStringIndices(null); // null是非法参数，将返回undefined 2936 let indicesUndefined = runs[0].getStringIndices(undefined); // undefined是非法参数，将返回undefined 2937} 2938 2939@Entry 2940@Component 2941struct Index { 2942 fun: Function = textFunc; 2943 build() { 2944 Column() { 2945 Button().onClick(() => { 2946 this.fun(); 2947 }) 2948 } 2949 } 2950} 2951``` 2952 2953### getImageBounds<sup>18+</sup> 2954 2955getImageBounds(): common2D.Rect 2956 2957获取该排版单元的图像边界，图像边界与排版字体、排版字号、字符本身都有关，相当于视觉边界，例如字符串为" a b "，'a'字符前面有1个空格，'b'字符后面有1个空格，用户在界面上只能看到"a b"，图像边界即为不包括带行首和末尾空格的边界。 2958 2959>**说明：** 2960> 2961>示意图展示了字符串为" a b "的图像边界。 2962> 2963> 2964> 2965>示意图展示了字符串为"j"或"E"的图像边界。 2966> 2967> 2968 2969**系统能力**：SystemCapability.Graphics.Drawing 2970 2971**返回值：** 2972 2973| 类型 | 说明 | 2974| ---------------------- | -------------- | 2975| [common2D.Rect](js-apis-graphics-common2D.md#rect) | 该排版单元的图像边界。| 2976 2977**示例：** 2978 2979```ts 2980let bounds = runs[0].getImageBounds(); 2981``` 2982 2983### getTypographicBounds<sup>18+</sup> 2984 2985getTypographicBounds(): TypographicBounds 2986 2987获取该排版单元的排版边界，排版边界与排版字体、排版字号有关，与字符本身无关，例如字符串为" a b "，'a'字符前面有1个空格，'b'字符后面有1个空格，排版边界就包括行首和末尾空格的边界。 2988 2989>**说明：** 2990> 2991>示意图展示了字符串为" a b "的排版边界。 2992> 2993> 2994> 2995>示意图展示了字符串为"j"或"E"的排版边界。 2996> 2997> 2998 2999**系统能力**：SystemCapability.Graphics.Drawing 3000 3001**返回值：** 3002 3003| 类型 | 说明 | 3004| ---------------------- | -------------- | 3005| [TypographicBounds](#typographicbounds18) | 该排版单元的排版边界。| 3006 3007**示例：** 3008 3009```ts 3010let typographicBounds = runs[0].getTypographicBounds(); 3011``` 3012 3013### getTextDirection<sup>20+</sup> 3014 3015getTextDirection(): TextDirection 3016 3017获取该排版单元的文本方向。 3018 3019**系统能力**：SystemCapability.Graphics.Drawing 3020 3021**返回值：** 3022 3023| 类型 | 说明 | 3024| ---------------------- | -------------- | 3025| [TextDirection](#textdirection) | 返回该排版单元的文本方向。| 3026 3027**示例：** 3028 3029```ts 3030let textDirection = runs[0].getTextDirection(); 3031``` 3032 3033### getAdvances<sup>20+</sup> 3034 3035getAdvances(range: Range): Array<common2D.Point> 3036 3037获取该排版单元指定范围内每个字形的字形宽度数组。 3038 3039**系统能力**：SystemCapability.Graphics.Drawing 3040 3041**参数：** 3042 3043| 参数名 | 类型 | 必填 | 说明 | 3044| -------- | ------- | ---- | -------------------------- | 3045| range | [Range](#range) | 是 | 要获取的字形位置范围。range.start表示范围开始的位置，range.end表示范围的长度。如果长度是0表示从range.start开始获取到渲染块结束。当range.end、range.start为负数，或者传入null、undefined时，该方法将返回undefined。| 3046 3047**返回值：** 3048 3049| 类型 | 说明 | 3050| ---------------------- | ------------------------------------- | 3051| Array<[common2D.Point](js-apis-graphics-common2D.md#point12)> | 返回该排版单元中每个字形相对于水平方向的字形宽度数组。其中，[common2D.Point](js-apis-graphics-common2D.md#point12)中的x值代表每个字形相对于水平方向的字形宽度，y值为保留字段，默认返回0。 | 3052 3053**示例：** 3054 3055```ts 3056let advancesRange = runs[0].getAdvances({start:1, end:2}); // 获取渲染块从起始位置1开始, 长度为2范围内的字形宽度 3057advancesRange = runs[0].getAdvances({start:-1, end:2}); // -1是非法参数，将返回undefined 3058advancesRange = runs[0].getAdvances({start:0, end:-10}); // -10是非法参数，将返回undefined 3059let advancesNull = runs[0].getAdvances(null); // null是非法参数，将返回undefined 3060``` 3061 3062## TextTab<sup>18+</sup> 3063 3064段落风格的文本制表符，储存了对齐方式和位置。 3065 3066**系统能力：** SystemCapability.Graphics.Drawing 3067 3068| 名称 | 类型 | 只读 | 可选 | 说明 | 3069| ----------------- | ----------------------- | ---- | --- | -------------------------------------------------- | 3070| alignment | [TextAlign](#textalign) | 否 | 否 | 段落中制表符之后的文本对齐方式，支持设置[TextAlign](#textalign)的LEFT左对齐、RIGHT右对齐和CENTER居中对齐方式，其他枚举值为左对齐，默认为左对齐。 | 3071| location | number | 否 | 否 | 制表符之后的文本对齐位置，浮点数，单位为物理像素px，最小值为1.0，当该值小于1.0时，该制表符会被替换为一个空格。 | 3072 3073**示例：** 3074 3075alignment为CENTER，location为200，文本为"12/t345"： 3076 3077 3078 3079alignment为LEFT，location为100，文本为"abccccccccc/tdef"： 3080 3081 3082 3083alignment为RIGHT，location为100，文本为"aabcdef/tg hi/tjkl/tmno/tp qr"： 3084 3085 3086 3087## SystemFontType<sup>14+</sup> 3088 3089字体类型枚举，通过位或运算可实现组合类型。 3090 3091**系统能力：** SystemCapability.Graphics.Drawing 3092 3093| 名称 | 值 | 说明 | 3094| - | - | - | 3095| ALL | 1 << 0 | 所有字体类型，包括系统字体类型、风格字体类型和用户已安装字体类型。 | 3096| GENERIC | 1 << 1 | 系统字体类型。 | 3097| STYLISH | 1 << 2 | 风格字体类型。风格字体类型是专为2in1设备设计的字体类型。 | 3098| INSTALLED | 1 << 3 | 用户已安装的字体类型。 | 3099| CUSTOMIZED<sup>18+</sup> | 1 << 4 | 自定义字体类型。 | 3100
