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- [ParagraphBuilder](#paragraphbuilder)：段落生成器，控制生成不同的段落对象。 12- [TextLine](#textline)：以行为单位的段落文本的载体，由段落类调用[getTextLines()](#gettextlines)接口获取。 13- [Run](#run)：文本排版的渲染单元，由行文本类调用[getGlyphRuns()](#getglyphruns)接口获取。 14 15> **说明：** 16> 17> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 18 19## 导入模块 20 21```ts 22import { text } from '@kit.ArkGraphics2D'; 23``` 24 25## TextAlign 26 27文本对齐方式枚举。 28 29**系统能力：** SystemCapability.Graphics.Drawing 30 31| 名称 | 值 | 说明 | 32| --------- | ---- | ---------------------------------------------- | 33| LEFT | 0 | 文本靠左对齐。 | 34| RIGHT | 1 | 文本靠右对齐。 | 35| CENTER | 2 | 文本居中对齐。 | 36| JUSTIFY | 3 | 文本两侧对齐，对最后一行无效。 | 37| START | 4 | 基于文本的方向[TextDirection](#textdirection)，文本靠开头方向对齐。 | 38| END | 5 | 基于文本的方向[TextDirection](#textdirection)，文本以结束方向对齐。 | 39 40## TextDirection 41 42文本排版方向枚举。 43 44**系统能力：** SystemCapability.Graphics.Drawing 45 46| 名称 | 值 | 说明 | 47| -------- | ---- | ---------------- | 48| RTL | 0 | 文本从右到左排版。 | 49| LTR | 1 | 文本从左到右排版。 | 50 51## BreakStrategy 52 53断行策略枚举。 54 55**系统能力：** SystemCapability.Graphics.Drawing 56 57| 名称 | 值 | 说明 | 58| ------------- | ---- | ---------------------------------------------- | 59| GREEDY | 0 | 尽可能将当前行填满，不会自动添加连词符。 | 60| HIGH_QUALITY | 1 | 布局优化，必要时会自动添加连词符。 | 61| BALANCED | 2 | 保证一个段落的每一行的宽度相同，必要时会添加连词符。| 62 63## WordBreak 64 65断词策略枚举。 66 67**系统能力：** SystemCapability.Graphics.Drawing 68 69| 名称 | 值 | 说明 | 70| ----------- | ---- | -------------------------------------------------------------------------------------------------------------------- | 71| NORMAL | 0 | 默认的换行规则。依据各自语言的规则，允许在字间发生换行。 | 72| BREAK_ALL | 1 | 对于 Non-CJK（非中文，日文，韩文）文本允许在任意字符内发生换行。该值适合包含一些非亚洲文本的亚洲文本，比如使连续的英文字符断行。| 73| BREAK_WORD | 2 | 与`BREAK_ALL`基本相同，不同的地方在于它要求一个没有断行破发点的词必须保持为一个整体单位。 | 74 75## Decoration 76 77文本装饰线。 78 79**系统能力：** SystemCapability.Graphics.Drawing 80 81| 名称 | 类型 | 只读 | 可选 | 说明 | 82| ------------------------- | --------------------------------------------------- | ---- | ---- | -------------------------------------------- | 83| textDecoration | [TextDecorationType](#textdecorationtype) | 是 | 是 | 装饰线类型，默认为NONE。 | 84| color | [common2D.Color](js-apis-graphics-common2D.md#color)| 是 | 是 | 装饰线颜色，默认为透明。 | 85| decorationStyle | [TextDecorationStyle](#textdecorationstyle) | 是 | 是 | 装饰线样式，默认为SOLID。 | 86| decorationThicknessScale | number | 是 | 是 | 装饰线粗细相对于默认值的比例，浮点数，默认为1.0。| 87 88## TextDecorationType 89 90装饰线类型枚举。 91 92**系统能力：** SystemCapability.Graphics.Drawing 93 94| 名称 | 值 | 说明 | 95| -------------- | - | ----------- | 96| NONE | 0 | 装饰线不生效。| 97| UNDERLINE | 1 | 下划线。 | 98| OVERLINE | 2 | 上划线。 | 99| LINE_THROUGH | 3 | 删除线。 | 100 101## TextDecorationStyle 102 103装饰线样式枚举。 104 105**系统能力：** SystemCapability.Graphics.Drawing 106 107| 名称 | 值 | 说明 | 108| ------ | - | ------ | 109| SOLID | 0 | 实线。 | 110| DOUBLE | 1 | 双层线。| 111| DOTTED | 2 | 点状线。| 112| DASHED | 3 | 虚线。 | 113| WAVY | 4 | 波浪线。| 114 115## FontWeight 116 117字重枚举。 118 119**系统能力：** SystemCapability.Graphics.Drawing 120 121| 名称 | 值 | 说明 | 122| ----- | - | ------- | 123| W100 | 0 | 100字重。| 124| W200 | 1 | 200字重。| 125| W300 | 2 | 300字重。| 126| W400 | 3 | 400字重。| 127| W500 | 4 | 500字重。| 128| W600 | 5 | 600字重。| 129| W700 | 6 | 700字重。| 130| W800 | 7 | 800字重。| 131| W900 | 8 | 900字重。| 132 133## FontWidth 134 135字体宽度的枚举。 136 137**系统能力：** SystemCapability.Graphics.Drawing 138 139| 名称 | 值 | 说明 | 140| ---------------- | - | ---------- | 141| ULTRA_CONDENSED | 1 | 超窄字宽。 | 142| EXTRA_CONDENSED | 2 | 特窄字宽。 | 143| CONDENSED | 3 | 窄的字宽。 | 144| SEMI_CONDENSED | 4 | 半窄字宽。 | 145| NORMAL | 5 | 常规字宽。 | 146| SEMI_EXPANDED | 6 | 半宽字宽。 | 147| EXPANDED | 7 | 宽的字宽。 | 148| EXTRA_EXPANDED | 8 | 特宽字宽。 | 149| ULTRA_EXPANDED | 9 | 超宽的字宽。| 150 151## FontStyle 152 153字体样式枚举。 154 155**系统能力：** SystemCapability.Graphics.Drawing 156 157| 名称 | 值 | 说明 | 158| ------- | - | ---------------------------------------------------- | 159| NORMAL | 0 | 常规样式。 | 160| ITALIC | 1 | 斜体，如果当前字体没有可用的斜体版本，会选用倾斜体替代。 | 161| OBLIQUE | 2 | 倾斜体，如果当前字体没有可用的倾斜体版本，会选用斜体替代。| 162 163## TextHeightBehavior 164 165文本高度修饰符模式枚举。 166 167**系统能力：** SystemCapability.Graphics.Drawing 168 169| 名称 | 值 | 说明 | 170| --------------------- | --- | ---------------------------------------------------- | 171| ALL | 0x0 | 高度修饰符设置为段落中第一行和最后一行都上升。 | 172| DISABLE_FIRST_ASCENT | 0x1 | 高度修饰符设置为禁止段落中第一行上升。 | 173| DISABLE_LAST_ASCENT | 0x2 | 高度修饰符设置为禁止段落中最后一行上升。 | 174| DISABLE_ALL | 0x3 | 高度修饰符设置为段落中第一行和最后一行都不上升。 | 175 176## TextBaseline 177 178文本基线类型枚举。 179 180**系统能力：** SystemCapability.Graphics.Drawing 181 182| 名称 | 值 | 说明 | 183| ----------- | - | ---- | 184| ALPHABETIC | 0 | 通常用于拉丁字母的文本基线对齐。| 185| IDEOGRAPHIC | 1 | 通常用于CJK（中文，日文，韩文）的文本基线对齐。| 186 187## EllipsisMode 188 189省略号类型枚举。 190 191EllipsisMode.START和EllipsisMode.MIDDLE仅在单行超长文本生效。 192 193**系统能力：** SystemCapability.Graphics.Drawing 194 195| 名称 | 值 | 说明 | 196| ------ | - | --------- | 197| START | 0 | 开头省略号。| 198| MIDDLE | 1 | 中间省略号。| 199| END | 2 | 末尾省略号。| 200 201## TextShadow 202 203字体阴影。 204 205**系统能力：** SystemCapability.Graphics.Drawing 206 207| 名称 | 类型 | 只读 | 可选 | 说明 | 208| ------------- | ---------------------------------------------------- | -- | --- | --------------------------------- | 209| color | [common2D.Color](js-apis-graphics-common2D.md#color) | 是 | 是 | 字体阴影的颜色，默认为黑色Color(255, 0, 0, 0)。 | 210| point | [common2D.Point](js-apis-graphics-common2D.md#point12) | 是 | 是 | 字体阴影基于当前文本的偏移位置，横、纵坐标要大于等于零。 | 211| blurRadius | number | 是 | 是 | 模糊半径，浮点数，默认为0.0px。 | 212 213## RectStyle 214 215矩形框样式。 216 217**系统能力：** SystemCapability.Graphics.Drawing 218 219| 名称 | 类型 | 只读 | 可选 | 说明 | 220| ----------------- | ---------------------------------------------------- | -- | --- | ---------------------------------------- | 221| color | [common2D.Color](js-apis-graphics-common2D.md#color) | 是 | 否 | 矩形框的颜色。 | 222| leftTopRadius | number | 是 | 否 | 矩形框的左上半径。 | 223| rightTopRadius | number | 是 | 否 | 矩形框的右上半径。 | 224| rightBottomRadius | number | 是 | 否 | 矩形框的右下半径。 | 225| leftBottomRadius | number | 是 | 否 | 矩形框的左下半径。 | 226 227## FontFeature 228 229文本字体特征。 230 231**系统能力：** SystemCapability.Graphics.Drawing 232 233| 名称 | 类型 | 只读 | 可选 | 说明 | 234| --------- | ---------------------------------------------------- | -- | --- | ----------------------------------------- | 235| name | string | 是 | 否 | 字体特征键值对中关键字所标识的字符串。 | 236| value | number | 是 | 否 | 字体特征键值对的值。 | 237 238## FontVariation 239 240可变字体属性。 241 242**系统能力：** SystemCapability.Graphics.Drawing 243 244| 名称 | 类型 | 只读 | 可选 | 说明 | 245| --------- | ---------------------------------------------------- | -- | --- | ----------------------------------------- | 246| axis | string | 是 | 否 | 可变字体属性键值对中关键字所标识的字符串。 | 247| value | number | 是 | 否 | 可变字体属性键值对的值。 | 248 249## TextStyle 250 251文本样式。 252 253**系统能力：** SystemCapability.Graphics.Drawing 254 255| 名称 | 类型 | 只读 | 可选 | 说明 | 256| ------------- | ---------------------------------------------------- | -- | -- | --------------------------------------------------------- | 257| decoration | [Decoration](#decoration) | 是 | 是 | 装饰线置，默认初始的Decoration。 | 258| color | [common2D.Color](js-apis-graphics-common2D.md#color) | 是 | 是 | 字体色，默认为白色。 | 259| fontWeight | [FontWeight](#fontweight) | 是 | 是 | 字重，默认为W400。 | 260| fontStyle | [FontStyle](#fontstyle) | 是 | 是 | 字体样式，默认为常规样式。 | 261| baseline | [TextBaseline](#textbaseline) | 是 | 是 | 文本基线型，默认为ALPHABETIC。 | 262| fontFamilies | Array\<string> | 是 | 是 | 字体族名称列表，默认为系统字体。 | 263| fontSize | number | 是 | 是 | 字体大小，浮点数，默认为14.0，单位为px。 | 264| letterSpacing | number | 是 | 是 | 字符间距，正数拉开字符距离，若是负数则拉近字符距离，浮点数，默认为0.0，单位为物理像素px。| 265| wordSpacing | number | 是 | 是 | 单词间距，浮点数，默认为0.0，单位为px。 | 266| heightScale | number | 是 | 是 | 行高缩放倍数，浮点数，默认为1.0，heightOnly为true时生效。 | 267| heightOnly | boolean | 是 | 是 | true表示根据字体大小和heightScale设置文本框的高度，false表示根据行高和行距，默认为false。| 268| halfLeading | boolean | 是 | 是 | true表示将行间距平分至行的顶部与底部，false则不平分，默认为false。| 269| ellipsis | string | 是 | 是 | 省略号样式，表示省略号生效后使用该字段值替换省略号部分。 | 270| ellipsisMode | [EllipsisMode](#ellipsismode) | 是 | 是 | 省略号类型，默认为END，行尾省略号。 | 271| locale | string | 是 | 是 | 语言类型，如字段为'en'代表英文，'zh-Hans'代表简体中文，'zh-Hant'代表繁体中文。具体请参照ISO 639-1规范，默认为空字符串。| 272| baselineShift | number | 是 | 是 | 文本下划线的偏移距离，浮点数，默认为0.0px。 | 273| fontFeatures | Array\<[FontFeature](#fontfeature)> | 是 | 是 | 文本字体特征数组。| 274| fontVariations| Array\<[FontVariation](#fontvariation)> | 是 | 是 | 可变字体属性数组。| 275| textShadows | Array\<[TextShadow](#textshadow)> | 是 | 是 | 文本字体阴影数组。| 276| backgroundRect| [RectStyle](#rectstyle) | 是 | 是 | 文本矩形框样式。| 277 278## StrutStyle 279 280支柱样式，用于控制绘制文本的行间距、基线对齐方式以及其他与行高相关的属性，默认不开启。 281 282**系统能力：** SystemCapability.Graphics.Drawing 283 284| 名称 | 类型 | 只读 | 可选 | 说明 | 285| ------------- | ---------------------------------------------------- | ---- | -- | --------------------------------------------------------------------- | 286| fontFamilies | Array\<string> | 是 | 是 | 字体类型，默认为系统字体。 | 287| fontStyle | [FontStyle](#fontstyle) | 是 | 是 | 字体样式，默认为常规样式。 | 288| fontWidth | [FontWidth](#fontwidth) | 是 | 是 | 字体宽度，默认为NORMAL。 | 289| fontWeight | [FontWeight](#fontweight) | 是 | 是 | 字重，默认为W400。 | 290| fontSize | number | 是 | 是 | 字体大小，浮点数，默认为14.0，单位为物理像素px。 | 291| height | number | 是 | 是 | 行高缩放倍数，浮点数，默认为1.0。 | 292| leading | number | 是 | 是 | 以自定义行距应用于支柱的行距，浮点数，默认为-1.0。 | 293| forceHeight | boolean | 是 | 是 | 是否所有行都将使用支柱的高度，true表示使用，false表示不使用，默认为false。 | 294| enabled | boolean | 是 | 是 | 是否启用支柱样式，true表示使用，false表示不使用，默认为false。 | 295| heightOverride | boolean | 是 | 是 | 是否覆盖高度，true表示覆盖，false表示不覆盖，默认为false。 | 296| halfLeading | boolean | 是 | 是 | true表示将行间距平分至行的顶部与底部，false则不平分，默认为false。 | 297 298## FontCollection 299 300字体管理器。 301 302### getGlobalInstance 303 304static getGlobalInstance(): FontCollection 305 306获取应用全局FontCollection的实例。 307 308**系统能力**：SystemCapability.Graphics.Drawing 309 310**返回值：** 311 312| 类型 | 说明 | 313| ------ | ------------------ | 314| [FontCollection](#fontcollection) | FontCollection对象。| 315 316**示例：** 317 318```ts 319import { text } from "@kit.ArkGraphics2D" 320 321function textFunc() { 322 let fontCollection = text.FontCollection.getGlobalInstance(); 323} 324 325@Entry 326@Component 327struct Index { 328 fun: Function = textFunc; 329 build() { 330 Column() { 331 Button().onClick(() => { 332 this.fun(); 333 }) 334 } 335 } 336} 337``` 338 339### loadFontSync 340 341loadFontSync(name: string, path: string | Resource): void 342 343同步接口，将路径对应的文件，以name作为使用的别名，加载成自定义字体。其中参数name对应的值需要在[TextStyle](#textstyle)中的fontFamilies属性配置，才能显示自定义的字体效果。支持的字体文件格式包含：ttf、otf。 344 345**系统能力**：SystemCapability.Graphics.Drawing 346 347**参数：** 348 349| 参数名 | 类型 | 必填 | 说明 | 350| ----- | ------------------ | ---- | --------------------------------------------------------------------------------- | 351| name | string | 是 | 加载成字体后，调用该字体所使用的命名。 | 352| path | string \| [Resource](../apis-arkui/arkui-ts/ts-types.md#resource) | 是 | 需要导入的字体文件的路径，应为 "file:// + 字体文件绝对路径" 或 "rawfile/目录or文件名"。 | 353 354**示例：** 355 356```ts 357import { text } from "@kit.ArkGraphics2D" 358 359let fontCollection: text.FontCollection = new text.FontCollection(); 360 361@Entry 362@Component 363struct RenderTest { 364 LoadFontSyncTest() { 365 fontCollection.loadFontSync('Clock_01', 'file:///system/fonts/HarmonyClock_01.ttf') 366 let fontFamilies: Array<string> = ["Clock_01"] 367 let myTextStyle: text.TextStyle = { 368 fontFamilies: fontFamilies 369 }; 370 let myParagraphStyle: text.ParagraphStyle = { 371 textStyle: myTextStyle, 372 } 373 let paragraphBuilder: text.ParagraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection); 374 375 let textData = "测试 loadFontSync 加载字体HarmonyClock_01.ttf"; 376 paragraphBuilder.addText(textData); 377 let paragraph: text.Paragraph = paragraphBuilder.build(); 378 paragraph.layoutSync(600); 379 } 380 381 aboutToAppear() { 382 this.LoadFontSyncTest(); 383 } 384 385 build() { 386 } 387} 388``` 389 390### clearCaches 391 392clearCaches(): void 393 394清理字体排版缓存（字体排版缓存本身设有内存上限和清理机制，所占内存有限，如无内存要求，不建议清理）。 395 396**系统能力**：SystemCapability.Graphics.Drawing 397 398**示例：** 399 400```ts 401import { text } from "@kit.ArkGraphics2D" 402 403@Entry 404@Component 405struct Index { 406 build() { 407 Column() { 408 Button().onClick(() => { 409 text.FontCollection.getGlobalInstance().clearCaches(); 410 }) 411 } 412 } 413} 414``` 415 416## ParagraphStyle 417 418段落样式。 419 420**系统能力：** SystemCapability.Graphics.Drawing 421 422| 名称 | 类型 | 只读 | 可选 | 说明 | 423| -------------------- | ------------------------------------------ | ---- | ---- | -------------------------------------------- | 424| textStyle | [TextStyle](#textstyle) | 是 | 是 | 作用于整个段落的文本样式，默认为初始的TextStyle。| 425| textDirection | [TextDirection](#textdirection) | 是 | 是 | 文本方向，默认为LTR。 | 426| align | [TextAlign](#textalign) | 是 | 是 | 文本对齐方式，默认为START。 | 427| wordBreak | [WordBreak](#wordbreak) | 是 | 是 | 断词类型，默认为BREAK_WORD。 | 428| maxLines | number | 是 | 是 | 最大行数限制，整数，默认为1e9。 | 429| breakStrategy | [BreakStrategy](#breakstrategy) | 是 | 是 | 断行策略，默认为GREEDY。 | 430| strutStyle | [StrutStyle](#strutstyle) | 是 | 是 | 支柱样式，默认为初始的StrutStyle。 | 431| textHeightBehavior | [TextHeightBehavior](#textheightbehavior) | 是 | 是 | 文本高度修饰符模式，默认为ALL。 | 432 433 434## PlaceholderAlignment 435 436占位符相对于周围文本的纵向的对齐方式。 437 438**系统能力：** SystemCapability.Graphics.Drawing 439 440| 名称 | 值 | 说明 | 441| ------------------- | - | ---------------------- | 442| OFFSET_AT_BASELINE | 0 | 基线与文本基线对齐。 | 443| ABOVE_BASELINE | 1 | 将底部与文本基线对齐。 | 444| BELOW_BASELINE | 2 | 将顶部与文本基线对齐。 | 445| TOP_OF_ROW_BOX | 3 | 将顶部与文本顶部对齐。 | 446| BOTTOM_OF_ROW_BOX | 4 | 将底部与文本底部对齐。 | 447| CENTER_OF_ROW_BOX | 5 | 中线与文本的中线位置对齐。| 448 449 450 451> **说明：** 452> 453> 示意图只展示了后三种，前三种与其类似，只不过比较位置变成了文本基线位置，即绿色线条部分。 454> 455> 456 457## PlaceholderSpan 458 459描述占位符样式的载体。 460 461**系统能力：** SystemCapability.Graphics.Drawing 462 463| 名称 | 类型 | 只读 | 可选 | 说明 | 464| -------------- | --------------------------------------------- | ---- | --- | --------------------------- | 465| width | number | 是 | 否 | 占位符的宽度，浮点数，单位为物理像素px。| 466| height | number | 是 | 否 | 占位符的高度，浮点数，单位为物理像素px。| 467| align | [PlaceholderAlignment](#placeholderalignment) | 是 | 否 | 相对于周围文本的纵向的对齐方式。| 468| baseline | [TextBaseline](#textbaseline) | 是 | 否 | 基线类型。 | 469| baselineOffset | number | 是 | 否 | 基线偏移量，浮点数，单位为物理像素px。 | 470 471## Range 472 473描述一个左闭右开的区间。 474 475**系统能力：** SystemCapability.Graphics.Drawing 476 477| 名称 | 类型 | 只读 | 可选 | 说明 | 478| ----- | ------ | ---- | --- | --------------- | 479| start | number | 是 | 否 | 区间左侧端点索引，整数。| 480| end | number | 是 | 否 | 区间右侧端点索引，整数。| 481 482## Paragraph 483 484保存着文本内容以及样式的载体，可以进行排版绘制等操作。 485 486下列API示例中都需先使用[ParagraphBuilder](#paragraphbuilder)类的[build()](#build)接口获取到Paragraph对象实例，再通过此实例调用对应方法。 487 488### layoutSync 489 490layoutSync(width: number): void 491 492进行排版，计算所有字形的位置。 493 494**系统能力**：SystemCapability.Graphics.Drawing 495 496**参数：** 497 498| 参数名 | 类型 | 必填 | 说明 | 499| ----- | ------ | ---- | -------------- | 500| width | number | 是 | 单行的最大宽度，浮点数，单位为物理像素px。| 501 502**示例：** 503 504```ts 505paragraph.layoutSync(100); 506``` 507 508### paint 509 510paint(canvas: drawing.Canvas, x: number, y: number): void 511 512在画布上以坐标点 (x, y) 为左上角位置绘制文本。 513 514**系统能力**：SystemCapability.Graphics.Drawing 515 516**参数：** 517 518| 参数名 | 类型 | 必填 | 说明 | 519| ------ | ---------------------------------------------------- | ---- | ---------------------- | 520| canvas | [drawing.Canvas](js-apis-graphics-drawing.md#canvas) | 是 | 绘制的目标画布。 | 521| x | number | 是 | 绘制的左上角位置的横坐标，浮点数。| 522| y | number | 是 | 绘制的左上角位置的纵坐标，浮点数。| 523 524**示例：** 525 526```ts 527const color: ArrayBuffer = new ArrayBuffer(160000); 528let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 200, width: 200 } } 529let pixelMap: image.PixelMap = image.createPixelMapSync(color, opts); 530let canvas = new drawing.Canvas(pixelMap); 531paragraph.paint(canvas, 0, 0); 532``` 533 534### paintOnPath 535 536paintOnPath(canvas: drawing.Canvas, path: drawing.Path, hOffset: number, vOffset: number): void 537 538在画布上沿路径绘制文本。 539 540**系统能力**：SystemCapability.Graphics.Drawing 541 542**参数：** 543 544| 参数名 | 类型 | 必填 | 说明 | 545| ------ | ---------------------------------------------------- | ---- | ---------------------- | 546| canvas | [drawing.Canvas](js-apis-graphics-drawing.md#canvas) | 是 | 绘制的目标画布。 | 547| path | [drawing.Path](js-apis-graphics-drawing.md#path) | 是 | 确认文字位置的路径。 | 548| hOffset | number | 是 | 沿路径方向偏置，从路径起点向前为正，向后为负。| 549| vOffset | number | 是 | 沿路径垂直方向偏置，沿路径方向左侧为负，右侧为正。| 550 551**示例：** 552 553```ts 554const color: ArrayBuffer = new ArrayBuffer(160000); 555let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 200, width: 200 } } 556let pixelMap: image.PixelMap = image.createPixelMapSync(color, opts); 557let canvas = new drawing.Canvas(pixelMap); 558let path = new drawing.Path(); 559path.arcTo(20, 20, 180, 180, 180, 90); 560paragraph.paintOnPath(canvas, path, 0, 0); 561``` 562 563### getMaxWidth 564 565getMaxWidth(): number 566 567获取文本最大的行宽。 568 569**系统能力**：SystemCapability.Graphics.Drawing 570 571**返回值：** 572 573| 类型 | 说明 | 574| ------ | --------- | 575| number | 最大的行宽，浮点数，单位为物理像素px。| 576 577**示例：** 578 579```ts 580let maxWidth = paragraph.getMaxWidth(); 581``` 582 583### getHeight 584 585getHeight(): number 586 587获取文本总高度。 588 589**系统能力**：SystemCapability.Graphics.Drawing 590 591**返回值：** 592 593| 类型 | 说明 | 594| ------ | ----- | 595| number | 总高度，浮点数，单位为物理像素px。| 596 597**示例：** 598 599```ts 600let height = paragraph.getHeight(); 601``` 602 603### getLongestLine 604 605getLongestLine(): number 606 607获取文本最长一行的宽度。 608 609**系统能力**：SystemCapability.Graphics.Drawing 610 611**返回值：** 612 613| 类型 | 说明 | 614| ------ | ------------- | 615| number | 最长一行的宽度，浮点数，单位为物理像素px。| 616 617**示例：** 618 619```ts 620let longestLine = paragraph.getLongestLine(); 621``` 622 623### getLongestLineWithIndent<sup>13+</sup> 624 625getLongestLineWithIndent(): number 626 627获取文本最长一行的宽度（该宽度包含当前行缩进的宽度），建议实际使用时将返回值向上取整。当文本内容为空时，返回0。 628 629**系统能力**：SystemCapability.Graphics.Drawing 630 631**返回值：** 632 633| 类型 | 说明 | 634| ------ | ------------- | 635| number | 最长一行的宽度（该宽度包含当前行缩进的宽度），浮点数，单位为物理像素px。| 636 637**示例：** 638 639```ts 640let longestLineWithIndent = paragraph.getLongestLineWithIndent(); 641``` 642 643### getMinIntrinsicWidth 644 645getMinIntrinsicWidth(): number 646 647获取该段落所占水平空间的最小固有宽度。 648 649**系统能力**：SystemCapability.Graphics.Drawing 650 651**返回值：** 652 653| 类型 | 说明 | 654| ------ | ----------------------------- | 655| number | 该段落所占水平空间的最小固有宽度，浮点数，单位为物理像素px。| 656 657**示例：** 658 659```ts 660let minIntrinsicWidth = paragraph.getMinIntrinsicWidth(); 661``` 662 663### getMaxIntrinsicWidth 664 665getMaxIntrinsicWidth(): number 666 667获取该段落所占水平空间的最大固有宽度。 668 669**系统能力**：SystemCapability.Graphics.Drawing 670 671**返回值：** 672 673| 类型 | 说明 | 674| ------ | ----------------------------- | 675| number | 该段落所占水平空间的最大固有宽度，浮点数，单位为物理像素px。| 676 677**示例：** 678 679```ts 680let maxIntrinsicWidth = paragraph.getMaxIntrinsicWidth(); 681``` 682 683### getAlphabeticBaseline 684 685getAlphabeticBaseline(): number 686 687获取拉丁字母下的基线位置。 688 689**系统能力**：SystemCapability.Graphics.Drawing 690 691**返回值：** 692 693| 类型 | 说明 | 694| ------ | ------------------ | 695| number | 拉丁字母下的基线位置，浮点数，单位为物理像素px。| 696 697**示例：** 698 699```ts 700let alphabeticBaseline = paragraph.getAlphabeticBaseline(); 701``` 702 703### getIdeographicBaseline 704 705getIdeographicBaseline(): number 706 707获取表意字（如CJK（中文，日文，韩文））下的基线位置。 708 709**系统能力**：SystemCapability.Graphics.Drawing 710 711**返回值：** 712 713| 类型 | 说明 | 714| ------ | -------------------- | 715| number | 获取表意字下的基线位置，浮点数，单位为物理像素px。| 716 717**示例：** 718 719```ts 720let ideographicBaseline = paragraph.getIdeographicBaseline(); 721``` 722 723### getRectsForRange 724 725getRectsForRange(range: Range, widthStyle: RectWidthStyle, heightStyle: RectHeightStyle): Array\<TextBox> 726 727获取给定的矩形区域宽度以及矩形区域高度的规格下，文本中该区间范围内的字符的所占的矩形区域。 728 729**系统能力**：SystemCapability.Graphics.Drawing 730 731**参数：** 732 733| 参数名 | 类型 | 必填 | 说明 | 734| ----------- | ----------------------------------- | ---- | ------------------------ | 735| range | [Range](#range) | 是 | 需要获取的区域的文本区间。 | 736| widthStyle | [RectWidthStyle](#rectwidthstyle) | 是 | 返回的矩形区域的宽度的规格。| 737| heightStyle | [RectHeightStyle](#rectheightstyle) | 是 | 返回的矩形区域的高度的规格。| 738 739**返回值：** 740 741| 类型 | 说明 | 742| --------------------------- | ----------- | 743| Array\<[TextBox](#textbox)> | 矩形区域数组。| 744 745**示例：** 746 747```ts 748let range: text.Range = { start: 0, end: 1}; 749let rects = paragraph.getRectsForRange(range, text.RectWidthStyle.TIGHT, text.RectHeightStyle.TIGHT); 750``` 751 752### getRectsForPlaceholders 753 754getRectsForPlaceholders(): Array\<TextBox> 755 756获取文本中所有占位符所占的矩形区域。 757 758**系统能力**：SystemCapability.Graphics.Drawing 759 760**返回值：** 761 762| 类型 | 说明 | 763| --------------------------- | ----------- | 764| Array\<[TextBox](#textbox)> | 矩形区域数组。| 765 766**示例：** 767 768```ts 769let placeholderRects = paragraph.getRectsForPlaceholders(); 770``` 771 772### getGlyphPositionAtCoordinate 773 774getGlyphPositionAtCoordinate(x: number, y: number): PositionWithAffinity 775 776获取较为接近给定坐标的字形的位置信息。 777 778**系统能力**：SystemCapability.Graphics.Drawing 779 780**参数：** 781 782| 参数名 | 类型 | 必填 | 说明 | 783| ----- | ------ | ---- | ------ | 784| x | number | 是 | 横坐标，浮点数。| 785| y | number | 是 | 纵坐标，浮点数。| 786 787**返回值：** 788 789| 类型 | 说明 | 790| --------------------------------------------- | ----------- | 791| [PositionWithAffinity](#positionwithaffinity) | 字形位置信息。| 792 793**示例：** 794 795```ts 796let positionWithAffinity = paragraph.getGlyphPositionAtCoordinate(0, 0); 797``` 798 799### getWordBoundary 800 801getWordBoundary(offset: number): Range 802 803返回给定的 offset 的字形所处的单词的索引区间。 804 805**系统能力**：SystemCapability.Graphics.Drawing 806 807**参数：** 808 809| 参数名 | 类型 | 必填 | 说明 | 810| ------ | ------ | ---- | ----------- | 811| offset | number | 是 | 字形的偏移量，整数。| 812 813**返回值：** 814 815| 类型 | 说明 | 816| --------------- | -------------- | 817| [Range](#range) | 单词的索引区间。| 818 819**示例：** 820 821```ts 822let wordRange = paragraph.getWordBoundary(0); 823``` 824 825### getLineCount 826 827getLineCount(): number 828 829返回文本行数量。 830 831**系统能力**：SystemCapability.Graphics.Drawing 832 833**返回值：** 834 835| 类型 | 说明 | 836| ------ | --------- | 837| number | 文本行数量，整数。| 838 839**示例：** 840 841```ts 842let lineCount = paragraph.getLineCount(); 843``` 844 845### getLineHeight 846 847getLineHeight(line: number): number 848 849返回指定行索引的行高。 850 851**系统能力**：SystemCapability.Graphics.Drawing 852 853**参数：** 854 855| 参数名 | 类型 | 必填 | 说明 | 856| ----- | ------ | ---- | --------- | 857| line | number | 是 | 文本行索引，整数。| 858 859**返回值：** 860 861| 类型 | 说明 | 862| ------ | ---- | 863| number | 行高。| 864 865**示例：** 866 867```ts 868let lineHeight = paragraph.getLineHeight(0); 869``` 870 871### getLineWidth 872 873getLineWidth(line: number): number 874 875返回指定行索引的行宽。 876 877**系统能力**：SystemCapability.Graphics.Drawing 878 879**参数：** 880 881| 参数名 | 类型 | 必填 | 说明 | 882| ----- | ------ | ---- | --------- | 883| line | number | 是 | 文本行索引，整数。| 884 885**返回值：** 886 887| 类型 | 说明 | 888| ------ | ---- | 889| number | 行宽。| 890 891**示例：** 892 893```ts 894let lineWidth = paragraph.getLineWidth(0); 895``` 896 897### didExceedMaxLines 898 899didExceedMaxLines(): boolean 900 901返回段落是否超过最大行限制。 902 903**系统能力**：SystemCapability.Graphics.Drawing 904 905**返回值：** 906 907| 类型 | 说明 | 908| ------- | -------------------------------------------------------- | 909| boolean | true表示段落超出了最大行限制，false则表示没有超出最大行限制。 | 910 911**示例：** 912 913```ts 914let didExceed = paragraph.didExceedMaxLines(); 915``` 916 917### getTextLines 918 919getTextLines(): Array\<TextLine> 920 921返回所有的文本行载体。 922 923**系统能力**：SystemCapability.Graphics.Drawing 924 925**返回值：** 926 927| 类型 | 说明 | 928| ----------------------------- | ------------- | 929| Array\<[TextLine](#textline)> | 文本行载体数组。| 930 931**示例：** 932 933```ts 934let lines = paragraph.getTextLines(); 935``` 936 937### getActualTextRange 938 939getActualTextRange(lineNumber: number, includeSpaces: boolean): Range 940 941获取指定行号上的实际可见文本范围，这不包括由于文本溢出而显示的省略号。 942 943**系统能力**：SystemCapability.Graphics.Drawing 944 945**参数：** 946 947| 参数名 | 类型 | 必填 | 说明 | 948| ----- | ------ | ---- | --------- | 949| lineNumber | number | 是 | 要获取文本范围的行号，行号从0开始。| 950| includeSpaces | boolean | 是 | 指示是否应包含空白字符。true表示包含空白字符，false表示不包含空白字符。| 951 952**返回值：** 953 954| 类型 | 说明 | 955| ---------------- | ------------------------------------------------ | 956| [Range](#range) | 表明了对应行数的实际文本范围。 | 957 958**示例：** 959 960```ts 961let rang = paragraph.getActualTextRange(0, true); 962``` 963 964 965### getLineMetrics 966 967getLineMetrics(): Array\<LineMetrics> 968 969获取文本行的行度量数组。 970 971**系统能力**：SystemCapability.Graphics.Drawing 972 973**返回值：** 974 975| 类型 | 说明 | 976| ----------------------------- | ------------- | 977| Array\<[LineMetrics](#linemetrics)> | 文本行的行度量数组。| 978 979**示例：** 980 981```ts 982let arrLineMetrc = paragraph.getLineMetrics(); 983``` 984 985### getLineMetrics 986 987getLineMetrics(lineNumber: number): LineMetrics | undefined 988 989获取特定行号的行度量信息。 990 991**系统能力**：SystemCapability.Graphics.Drawing 992 993**参数：** 994 995| 参数名 | 类型 | 必填 | 说明 | 996| ----- | ------ | ---- | --------- | 997| lineNumber | number | 是 | 要查询度量信息的行的编号, 行号从0开始。| 998 999**返回值：** 1000 1001| 类型 | 说明 | 1002| ---------------- | ------------------------------------------------ | 1003| [LineMetrics](#linemetrics) | 如果指定的行号有效且度量信息存在，则返回一个包含该行度量数据的LineMetrics对象；如果行号无效或无法获取度量信息，则返回undefined。 | 1004 1005**示例：** 1006 1007```ts 1008let lineMetrics = paragraph.getLineMetrics(0); 1009``` 1010 1011## RunMetrics 1012 1013描述文本行中连续文本块的布局信息和度量数据。 1014 1015**系统能力：** SystemCapability.Graphics.Drawing 1016 1017| 名称 | 类型 | 只读 | 可选 | 说明 | 1018| --------- | -------------------------------------------------- | ---- | ---- | ----------- | 1019| textStyle | [TextStyle](#textstyle) | 是 | 否 | 字体的样式信息。| 1020| fontMetrics | [drawing.FontMetrics](js-apis-graphics-drawing.md#fontmetrics)| 是 | 否 | 字体度量信息。 | 1021 1022## LineMetrics 1023 1024用于描述文本布局中单行文字的度量信息。 1025 1026**系统能力：** SystemCapability.Graphics.Drawing 1027 1028| 名称 | 类型 | 只读 | 可选 | 说明 | 1029| --------- | -------------------------------------------------- | ---- | ---- | ----------- | 1030| startIndex | number | 是 | 否 | 文本缓冲区中该行开始的索引位置。| 1031| endIndex | number | 是 | 否 | 文本缓冲区中该行结束的索引位置。| 1032| ascent | number | 是 | 否 | 文字上升高度，即从基线到字符顶部的距离。| 1033| descent | number | 是 | 否 | 文字下降高度，即从基线到字符底部的距离。| 1034| height | number | 是 | 否 | 当前行的高度，计算方式为 `Math.round(ascent + descent)`| 1035| width | number | 是 | 否 | 行的宽度。 | 1036| left | number | 是 | 否 | 行的左边缘位置。右边缘可通过 `left+width` 计算得出。| 1037| baseline | number | 是 | 否 | 该行基线相对于段落顶部的 Y 坐标位置。| 1038| lineNumber | number | 是 | 否 | 行号，从0开始计数。| 1039| topHeight | number | 是 | 否 | 从顶部到当前行的高度。| 1040| runMetrics | Map<number, [RunMetrics](#runmetrics)> | 是 | 否 | 文本索引范围与关联的字体度量信息之间的映射。| 1041 1042## TextBox 1043 1044文本矩形区域。 1045 1046**系统能力：** SystemCapability.Graphics.Drawing 1047 1048| 名称 | 类型 | 只读 | 可选 | 说明 | 1049| --------- | -------------------------------------------------- | ---- | ---- | ----------- | 1050| rect | [common2D.Rect](js-apis-graphics-common2D.md#rect) | 是 | 否 | 矩形区域信息。| 1051| direction | [TextDirection](#textdirection) | 是 | 否 | 文本方向。 | 1052 1053## PositionWithAffinity 1054 1055位置以及亲和度。 1056 1057**系统能力：** SystemCapability.Graphics.Drawing 1058 1059| 名称 | 类型 | 只读 | 可选 | 说明 | 1060| --------- | --------------------- | ---- | ---- | ------------------------ | 1061| position | number | 是 | 否 | 字形相对于段落的索引，整数。 | 1062| affinity | [Affinity](#affinity) | 是 | 否 | 位置亲和度。 | 1063 1064## RectWidthStyle 1065 1066矩形区域宽度规格枚举。 1067 1068**系统能力：** SystemCapability.Graphics.Drawing 1069 1070| 名称 | 值 | 说明 | 1071| ----- | - | -------------------------------------- | 1072| TIGHT | 0 | 不设置letterSpacing时，与字形紧贴，否则包含letterSpacing。 | 1073| MAX | 1 | 扩展宽度，以匹配所有行上最宽矩形的位置。 | 1074 1075## RectHeightStyle 1076 1077矩形区域高度规格枚举。 1078 1079**系统能力：** SystemCapability.Graphics.Drawing 1080 1081| 名称 | 值 | 说明 | 1082| ------------------------- | - | ---------------------------------------------- | 1083| TIGHT | 0 | 与字形紧贴。 | 1084| MAX | 1 | 扩展高度，以匹配所有行上最高矩形的位置。 | 1085| INCLUDE_LINE_SPACE_MIDDLE | 2 | 每个矩形的顶部和底部将覆盖行上方和行下方的一半空间。| 1086| INCLUDE_LINE_SPACE_TOP | 3 | 行间距将被添加到矩形的顶部。 | 1087| INCLUDE_LINE_SPACE_BOTTOM | 4 | 行间距将被添加到矩形的底部。 | 1088| STRUT | 5 | 高度按照文本的样式设置。 | 1089 1090## Affinity 1091 1092位置亲和度枚举。 1093 1094**系统能力：** SystemCapability.Graphics.Drawing 1095 1096| 名称 | 值 | 说明 | 1097| ---------- | - | ----------------------------- | 1098| UPSTREAM | 0 | 该位置与文本位置的前一位有关联。 | 1099| DOWNSTREAM | 1 | 该位置与文本位置的后一位有关联。 | 1100 1101## ParagraphBuilder 1102 1103段落生成器。 1104 1105### constructor 1106 1107constructor(paragraphStyle: ParagraphStyle, fontCollection: FontCollection) 1108 1109ParagraphBuilder对象的构造函数。 1110 1111**系统能力**：SystemCapability.Graphics.Drawing 1112 1113**参数：** 1114 1115| 参数名 | 类型 | 必填 | 说明 | 1116| -------------- | --------------------------------- | ---- | ----------- | 1117| paragraphStyle | [ParagraphStyle](#paragraphstyle) | 是 | 段落样式。 | 1118| fontCollection | [FontCollection](#fontcollection) | 是 | 字体管理器。 | 1119 1120**示例：** 1121 1122```ts 1123import { text } from "@kit.ArkGraphics2D"; 1124 1125function textFunc() { 1126 let myTextStyle: text.TextStyle = { 1127 color: { alpha: 255, red: 255, green: 0, blue: 0 }, 1128 fontSize: 33, 1129 }; 1130 let myParagraphStyle: text.ParagraphStyle = { 1131 textStyle: myTextStyle, 1132 align: text.TextAlign.END, 1133 }; 1134 let fontCollection = new text.FontCollection(); 1135 let ParagraphGraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection); 1136} 1137 1138@Entry 1139@Component 1140struct Index { 1141 fun: Function = textFunc; 1142 build() { 1143 Column() { 1144 Button().onClick(() => { 1145 this.fun(); 1146 }) 1147 } 1148 } 1149} 1150``` 1151 1152### pushStyle 1153 1154 pushStyle(textStyle: TextStyle): void 1155 1156更新文本样式。 1157 1158> **说明：** 1159> 1160> 更新当前文本块的样式 ，直到对应的 [popStyle](#popstyle) 操作被执行，会还原到上一个文本样式。 1161 1162**系统能力**：SystemCapability.Graphics.Drawing 1163 1164**参数：** 1165 1166| 参数名 | 类型 | 必填 | 说明 | 1167| --------- | --------- | ---- | ------------------------------------------------------------------------------------------------------ | 1168| textStyle | [TextStyle](#textstyle) | 是 | 包含了对文本的各种视觉属性的定义，如字体、字号、颜色、字重、字间距、行距、装饰（如下划线、删除线）、文本阴影等。 | 1169 1170**示例：** 1171 1172```ts 1173import { drawing } from '@kit.ArkGraphics2D' 1174import { text } from "@kit.ArkGraphics2D" 1175import { common2D } from "@kit.ArkGraphics2D" 1176import { image } from '@kit.ImageKit'; 1177 1178function textFunc() { 1179 let myTextStyle: text.TextStyle = { 1180 color: { alpha: 255, red: 255, green: 0, blue: 0 }, 1181 fontSize: 33, 1182 }; 1183 let myParagraphStyle: text.ParagraphStyle = { 1184 textStyle: myTextStyle, 1185 align: text.TextAlign.CENTER, 1186 }; 1187 let fontCollection = new text.FontCollection(); 1188 let ParagraphGraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection); 1189 ParagraphGraphBuilder.pushStyle(myTextStyle); 1190} 1191 1192@Entry 1193@Component 1194struct Index { 1195 fun: Function = textFunc; 1196 build() { 1197 Column() { 1198 Button().onClick(() => { 1199 this.fun(); 1200 }) 1201 } 1202 } 1203} 1204``` 1205 1206### popStyle 1207 1208popStyle(): void 1209 1210还原至上一个文本样式。 1211 1212**系统能力**：SystemCapability.Graphics.Drawing 1213 1214**示例：** 1215 1216```ts 1217import { drawing } from '@kit.ArkGraphics2D' 1218import { text } from "@kit.ArkGraphics2D" 1219import { common2D } from "@kit.ArkGraphics2D" 1220import { image } from '@kit.ImageKit'; 1221 1222function textFunc() { 1223 let myTextStyle: text.TextStyle = { 1224 color: { alpha: 255, red: 255, green: 0, blue: 0 }, 1225 fontSize: 33, 1226 }; 1227 let myParagraphStyle: text.ParagraphStyle = { 1228 textStyle: myTextStyle, 1229 align: text.TextAlign.END, 1230 }; 1231 let fontCollection = new text.FontCollection(); 1232 let ParagraphGraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection); 1233 ParagraphGraphBuilder.pushStyle(myTextStyle); 1234 ParagraphGraphBuilder.popStyle(); 1235} 1236 1237@Entry 1238@Component 1239struct Index { 1240 fun: Function = textFunc; 1241 build() { 1242 Column() { 1243 Button().onClick(() => { 1244 this.fun(); 1245 }) 1246 } 1247 } 1248} 1249``` 1250 1251### addText 1252 1253addText(text: string): void 1254 1255用于向正在构建的文本段落中插入具体的文本字符串。 1256 1257**系统能力**：SystemCapability.Graphics.Drawing 1258 1259**参数：** 1260 1261| 参数名 | 类型 | 必填 | 说明 | 1262| ------- | ------- | ---- | -------------------------- | 1263| text | string | 是 | 段落中插入的具体文本字符串。 | 1264 1265**示例：** 1266 1267```ts 1268import { drawing } from '@kit.ArkGraphics2D' 1269import { text } from "@kit.ArkGraphics2D" 1270import { common2D } from "@kit.ArkGraphics2D" 1271import { image } from '@kit.ImageKit'; 1272 1273function textFunc() { 1274 let myTextStyle: text.TextStyle = { 1275 color: { alpha: 255, red: 255, green: 0, blue: 0 }, 1276 fontSize: 33, 1277 }; 1278 let myParagraphStyle: text.ParagraphStyle = { 1279 textStyle: myTextStyle, 1280 align: text.TextAlign.END, 1281 }; 1282 let fontCollection = new text.FontCollection(); 1283 let ParagraphGraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection); 1284 ParagraphGraphBuilder.addText("123666"); 1285} 1286 1287@Entry 1288@Component 1289struct Index { 1290 fun: Function = textFunc; 1291 build() { 1292 Column() { 1293 Button().onClick(() => { 1294 this.fun(); 1295 }) 1296 } 1297 } 1298} 1299``` 1300 1301### addPlaceholder 1302 1303addPlaceholder(placeholderSpan: PlaceholderSpan): void 1304 1305用于在构建文本段落时插入占位符。 1306 1307**系统能力**：SystemCapability.Graphics.Drawing 1308 1309**参数：** 1310 1311| 参数名 | 类型 | 必填 | 说明 | 1312| --------------- | ----------------------------------- | ---- | --------------------------------------------------- | 1313| placeholderSpan | [PlaceholderSpan](#placeholderspan) | 是 | 定义了占位符的尺寸、对齐方式、基线类型以及基线偏移量。 | 1314 1315**示例：** 1316 1317```ts 1318import { drawing } from '@kit.ArkGraphics2D' 1319import { text } from "@kit.ArkGraphics2D" 1320import { common2D } from "@kit.ArkGraphics2D" 1321import { image } from '@kit.ImageKit'; 1322 1323function textFunc() { 1324 let myParagraphStyle: text.ParagraphStyle = { 1325 align: text.TextAlign.END, 1326 }; 1327 let myPlaceholderSpan: text.PlaceholderSpan = { 1328 width: 10000, 1329 height: 10000000, 1330 align: text.PlaceholderAlignment.ABOVE_BASELINE, 1331 baseline: text.TextBaseline.ALPHABETIC, 1332 baselineOffset: 100000 1333 }; 1334 let fontCollection = new text.FontCollection(); 1335 let ParagraphGraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection); 1336 ParagraphGraphBuilder.addPlaceholder(myPlaceholderSpan); 1337} 1338 1339@Entry 1340@Component 1341struct Index { 1342 fun: Function = textFunc; 1343 build() { 1344 Column() { 1345 Button().onClick(() => { 1346 this.fun(); 1347 }) 1348 } 1349 } 1350} 1351``` 1352 1353### build 1354 1355build(): Paragraph 1356 1357用于完成段落的构建过程，生成一个可用于后续排版渲染的段落对象。 1358 1359**系统能力**：SystemCapability.Graphics.Drawing 1360 1361**返回值：** 1362 1363| 类型 | 说明 | 1364| ------------------------ | ------------------------------ | 1365| [Paragraph](#paragraph) | 可用于后续渲染的 Paragraph 对象。| 1366 1367**示例：** 1368 1369```ts 1370import { drawing, text, common2D } from '@kit.ArkGraphics2D' 1371import { image } from '@kit.ImageKit'; 1372 1373function textFunc() { 1374 let myParagraphStyle: text.ParagraphStyle = { 1375 align: text.TextAlign.END, 1376 }; 1377 let fontCollection = new text.FontCollection(); 1378 let ParagraphGraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection); 1379 let paragraph = ParagraphGraphBuilder.build(); 1380} 1381 1382@Entry 1383@Component 1384struct Index { 1385 fun: Function = textFunc; 1386 build() { 1387 Column() { 1388 Button().onClick(() => { 1389 this.fun(); 1390 }) 1391 } 1392 } 1393} 1394``` 1395 1396### addSymbol 1397 1398addSymbol(symbolId: number): void 1399 1400用于向正在构建的文本段落中插入具体的符号。 1401 1402**系统能力**：SystemCapability.Graphics.Drawing 1403 1404**参数：** 1405 1406| 参数名 | 类型 | 必填 | 说明 | 1407| -------- | ------- | ---- | ----------------------------------------------------------- | 1408| symbolId | number | 是 | 要设置的symbol码位，十六进制，当前支持的取值范围为：0xF0000-0xF0C97。可设置的symbol码位及其对应的symbol名称请参阅以下链接中 JSON 文件的 value 字段和 name 字段： [https://gitee.com/openharmony/global_system_resources/blob/master/systemres/main/resources/base/element/symbol.json](https://gitee.com/openharmony/global_system_resources/blob/master/systemres/main/resources/base/element/symbol.json)| 1409 1410**示例：** 1411 1412```ts 1413import { text } from "@kit.ArkGraphics2D"; 1414 1415function textFunc() { 1416 let myTextStyle: text.TextStyle = { 1417 color: { alpha: 255, red: 255, green: 0, blue: 0 }, 1418 fontSize: 33, 1419 }; 1420 let myParagraphStyle: text.ParagraphStyle = { 1421 textStyle: myTextStyle, 1422 align: text.TextAlign.END, 1423 }; 1424 let fontCollection = new text.FontCollection(); 1425 let ParagraphGraphBuilder = new text.ParagraphBuilder(myParagraphStyle, fontCollection); 1426 ParagraphGraphBuilder.addSymbol(0xF0000); 1427 let paragraph = ParagraphGraphBuilder.build(); 1428} 1429 1430@Entry 1431@Component 1432struct Index { 1433 fun: Function = textFunc; 1434 build() { 1435 Column() { 1436 Button().onClick(() => { 1437 this.fun(); 1438 }) 1439 } 1440 } 1441} 1442``` 1443 1444## TextLine 1445 1446描述段落基础文本行结构的载体。 1447 1448下列API示例中都需先使用[Paragraph](#paragraph)类的[getTextLines()](#gettextlines)接口获取到TextLine对象实例，再通过此实例调用对应方法。 1449 1450### getGlyphCount 1451 1452getGlyphCount(): number 1453 1454获取该文本行中字形的数量。 1455 1456**系统能力**：SystemCapability.Graphics.Drawing 1457 1458**返回值：** 1459 1460| 类型 | 说明 | 1461| ------- | ------------------ | 1462| number | 该文本行中字形数量，整数。 | 1463 1464**示例：** 1465 1466```ts 1467import { text } from "@kit.ArkGraphics2D" 1468 1469function textFunc() { 1470 let GlyphCount = lines[0].getGlyphCount(); 1471} 1472 1473@Entry 1474@Component 1475struct Index { 1476 fun: Function = textFunc; 1477 build() { 1478 Column() { 1479 Button().onClick(() => { 1480 this.fun(); 1481 }) 1482 } 1483 } 1484} 1485``` 1486 1487### getTextRange 1488 1489getTextRange(): Range 1490 1491获取该文本行中的文本在整个段落文本中的索引区间。 1492 1493**系统能力**：SystemCapability.Graphics.Drawing 1494 1495**返回值：** 1496 1497| 类型 | 说明 | 1498| ---------------- | ------------------------------------------------ | 1499| [Range](#range) | 该文本行中的文本在整个段落文本中的索引区间。| 1500 1501**示例：** 1502 1503```ts 1504import { text } from "@kit.ArkGraphics2D" 1505 1506function textFunc() { 1507 let textRange = lines[0].getTextRange(); 1508} 1509 1510@Entry 1511@Component 1512struct Index { 1513 fun: Function = textFunc; 1514 build() { 1515 Column() { 1516 Button().onClick(() => { 1517 this.fun(); 1518 }) 1519 } 1520 } 1521} 1522``` 1523 1524### getGlyphRuns 1525 1526getGlyphRuns(): Array\<Run> 1527 1528获取该文本行中的文本渲染单位数组。 1529 1530**系统能力**：SystemCapability.Graphics.Drawing 1531 1532**返回值：** 1533 1534| 类型 | 说明 | 1535| ------------ | --------------------------- | 1536| Array\<[Run](#run)> | 该文本行中的文本渲染单位数组。| 1537 1538**示例：** 1539 1540```ts 1541import { text } from "@kit.ArkGraphics2D" 1542 1543function textFunc() { 1544 let runs = lines[0].getGlyphRuns(); 1545} 1546 1547@Entry 1548@Component 1549struct Index { 1550 fun: Function = textFunc; 1551 build() { 1552 Column() { 1553 Button().onClick(() => { 1554 this.fun(); 1555 }) 1556 } 1557 } 1558} 1559``` 1560 1561### paint 1562 1563paint(canvas: drawing.Canvas, x: number, y: number): void 1564 1565在画布上以坐标点 (x, y) 为左上角位置绘制该文本行。 1566 1567**系统能力**：SystemCapability.Graphics.Drawing 1568 1569**参数：** 1570 1571| 参数名 | 类型 | 必填 | 说明 | 1572| ------ | ---------------------------------------------------- | ---- | ---------------------- | 1573| canvas | [drawing.Canvas](js-apis-graphics-drawing.md#canvas) | 是 | 绘制的目标 canvas。 | 1574| x | number | 是 | 绘制的左上角位置的横坐标，浮点数。| 1575| y | number | 是 | 绘制的左上角位置的纵坐标，浮点数。| 1576 1577**示例：** 1578 1579```ts 1580import { drawing } from '@kit.ArkGraphics2D' 1581import { text } from "@kit.ArkGraphics2D" 1582import { common2D } from "@kit.ArkGraphics2D" 1583import { image } from '@kit.ImageKit'; 1584 1585function textFunc() { 1586 const color: ArrayBuffer = new ArrayBuffer(160000); 1587 let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 200, width: 200 } } 1588 let pixelMap: image.PixelMap = image.createPixelMapSync(color, opts); 1589 let canvas = new drawing.Canvas(pixelMap); 1590 lines[0].paint(canvas, 0, 0); 1591} 1592 1593@Entry 1594@Component 1595struct Index { 1596 fun: Function = textFunc; 1597 build() { 1598 Column() { 1599 Button().onClick(() => { 1600 this.fun(); 1601 }) 1602 } 1603 } 1604} 1605``` 1606 1607## Run 1608 1609文本排版的渲染单元。 1610 1611下列API示例中都需先使用[TextLine](#textline)类的[getGlyphRuns()](#getglyphruns)接口获取到Run对象实例，再通过此实例调用对应方法。 1612 1613### getGlyphCount 1614 1615getGlyphCount(): number 1616 1617获取该渲染单元中字形的数量。 1618 1619**系统能力**：SystemCapability.Graphics.Drawing 1620 1621**返回值：** 1622 1623| 类型 | 说明 | 1624| ------- | -------------------- | 1625| number | 该渲染单元中字形数量，整数。 | 1626 1627**示例：** 1628 1629```ts 1630import { text } from "@kit.ArkGraphics2D" 1631 1632function textFunc() { 1633 let glyphs = runs[0].getGlyphCount(); 1634} 1635 1636@Entry 1637@Component 1638struct Index { 1639 fun: Function = textFunc; 1640 build() { 1641 Column() { 1642 Button().onClick(() => { 1643 this.fun(); 1644 }) 1645 } 1646 } 1647} 1648``` 1649 1650### getGlyphs 1651 1652getGlyphs(): Array\<number> 1653 1654获取该渲染单元中每个字符对应的字形序号。 1655 1656**系统能力**：SystemCapability.Graphics.Drawing 1657 1658**返回值：** 1659 1660| 类型 | 说明 | 1661| --------------- | -------------------------------- | 1662| Array\<number> | 该渲染单元中每个字符对应的字形序号。| 1663 1664**示例：** 1665 1666```ts 1667import { text } from "@kit.ArkGraphics2D" 1668 1669function textFunc() { 1670 let glyph = runs[0].getGlyphs(); 1671} 1672 1673@Entry 1674@Component 1675struct Index { 1676 fun: Function = textFunc; 1677 build() { 1678 Column() { 1679 Button().onClick(() => { 1680 this.fun(); 1681 }) 1682 } 1683 } 1684} 1685``` 1686 1687### getPositions 1688 1689getPositions(): Array<common2D.Point> 1690 1691获取该渲染单元中每个字形相对于每行的索引。 1692 1693**系统能力**：SystemCapability.Graphics.Drawing 1694 1695**返回值：** 1696 1697| 类型 | 说明 | 1698| ---------------------- | ------------------------------------- | 1699| Array<[common2D.Point](js-apis-graphics-common2D.md#point12)> | 该渲染单元中每个字形相对于每行的索引。 | 1700 1701**示例：** 1702 1703```ts 1704import { text } from "@kit.ArkGraphics2D"; 1705 1706function textFunc() { 1707 let positions = runs[0].getPositions(); 1708} 1709 1710@Entry 1711@Component 1712struct Index { 1713 fun: Function = textFunc; 1714 build() { 1715 Column() { 1716 Button().onClick(() => { 1717 this.fun(); 1718 }) 1719 } 1720 } 1721} 1722``` 1723 1724### getOffsets 1725 1726getOffsets(): Array<common2D.Point> 1727 1728获取该渲染单元中每个字形相对于其索引的偏移量。 1729 1730**系统能力**：SystemCapability.Graphics.Drawing 1731 1732**返回值：** 1733 1734| 类型 | 说明 | 1735| ---------------------- | -------------- | 1736| Array<[common2D.Point](js-apis-graphics-common2D.md#point12)> | 该渲染单元中每个字形相对于其索引的偏移量。| 1737 1738**示例：** 1739 1740```ts 1741import { text } from "@kit.ArkGraphics2D"; 1742 1743function textFunc() { 1744 let offsets = runs[0].getOffsets(); 1745} 1746 1747@Entry 1748@Component 1749struct Index { 1750 fun: Function = textFunc; 1751 build() { 1752 Column() { 1753 Button().onClick(() => { 1754 this.fun(); 1755 }) 1756 } 1757 } 1758} 1759``` 1760 1761### getFont 1762 1763getFont(): drawing.Font 1764 1765获取该渲染单元的字体属性对象实例。 1766 1767**系统能力**：SystemCapability.Graphics.Drawing 1768 1769**返回值：** 1770 1771| 类型 | 说明 | 1772| ------------------------------------------------- | -------------------------- | 1773| [drawing.Font](js-apis-graphics-drawing.md#font) | 该渲染单元的字体属性对象实例。| 1774 1775**示例：** 1776 1777```ts 1778import { drawing } from '@kit.ArkGraphics2D' 1779import { text } from "@kit.ArkGraphics2D"; 1780 1781function textFunc() { 1782 let font = runs[0].getFont(); 1783} 1784 1785@Entry 1786@Component 1787struct Index { 1788 fun: Function = textFunc; 1789 build() { 1790 Column() { 1791 Button().onClick(() => { 1792 this.fun(); 1793 }) 1794 } 1795 } 1796} 1797``` 1798 1799### paint 1800 1801paint(canvas: drawing.Canvas, x: number, y: number): void 1802 1803在画布上以坐标点 (x, y) 为左上角位置绘制该渲染单元。 1804 1805**系统能力**：SystemCapability.Graphics.Drawing 1806 1807**参数：** 1808 1809| 参数名 | 类型 | 必填 | 说明 | 1810| ------ | ---------------------------------------------------- | ---- | ---------------------- | 1811| canvas | [drawing.Canvas](js-apis-graphics-drawing.md#canvas) | 是 | 绘制的目标 canvas。 | 1812| x | number | 是 | 绘制的左上角位置的横坐标，浮点数。| 1813| y | number | 是 | 绘制的左上角位置的纵坐标。浮点数。| 1814 1815**示例：** 1816 1817```ts 1818import { drawing } from '@kit.ArkGraphics2D' 1819import { text } from "@kit.ArkGraphics2D" 1820import { common2D } from "@kit.ArkGraphics2D" 1821import { image } from '@kit.ImageKit'; 1822 1823function textFunc() { 1824 const color: ArrayBuffer = new ArrayBuffer(160000); 1825 let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 200, width: 200 } } 1826 let pixelMap: image.PixelMap = image.createPixelMapSync(color, opts); 1827 let canvas = new drawing.Canvas(pixelMap); 1828 runs[0].paint(canvas, 0, 0); 1829} 1830 1831@Entry 1832@Component 1833struct Index { 1834 fun: Function = textFunc; 1835 build() { 1836 Column() { 1837 Button().onClick(() => { 1838 this.fun(); 1839 }) 1840 } 1841 } 1842} 1843``` 1844
