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