1# 字块绘制（ArkTS） 2 3<!--Kit: ArkGraphics 2D--> 4<!--Subsystem: Graphics--> 5<!--Owner: @hangmengxin--> 6<!--Designer: @wangyanglan--> 7<!--Tester: @nobuggers--> 8<!--Adviser: @ge-yafang--> 9 10## 场景介绍 11 12字块（TextBlob）是指文本的集合。无论是单个的文字还是大块的文本，都可以通过字块来绘制。 13 14除了基本的字块绘制之外，还可以给文字添加各种绘制效果。常见的字块绘制场景包括[文字描边](#文字描边)、[文字渐变](#文字渐变)等，更多效果请见[绘制效果](drawing-effect-overview.md)。 15 16本节不涉及文本测量和布局排版相关内容，如需在开发中处理此类文本绘制需求，可参考[文本开发概述](text-overview.md)，该文档系统讲解了排版策略与相关使用指导。 17 18## 基本字块绘制 19 20Canvas通过drawTextBlob()来绘制字块。函数接受三个参数：TextBlob字块对象，以及文字基线左端点的x坐标和y坐标。 21 22画布Canvas对象具体可见[画布的获取与绘制结果的显示（ArkTS）](canvas-get-result-draw-arkts.md)。 23 24字块对象可以通过多种方式创建得到，详细的字块创建方式和接口使用请参考[TextBlob](../reference/apis-arkgraphics2d/arkts-apis-graphics-drawing-TextBlob.md)。 25 26此处以使用makeFromString()接口创建字块为例，接口接受3个参数，分别为： 27 28- 需要显示的字符串text。 29 30- font字型对象。其中font用于设置和获取字体的各种属性，如字体大小、文本样式、字体对齐方式、字体渲染方式、字体描边方式等，详细的API介绍请参考[Font](../reference/apis-arkgraphics2d/arkts-apis-graphics-drawing-Font.md)。 31 32- 文本编码方式。当前支持的文本编码方式如下： 33 - TEXT_ENCODING_UTF8：使用1个字节表示UTF-8或ASCII； 34 - TEXT_ENCODING_UTF16：使用2个字节表示大部分unicode； 35 - TEXT_ENCODING_UTF32：使用4个字节表示全部unicode； 36 - TEXT_ENCODING_GLYPH_ID：使用2个字节表示glyph index。 37 38基本效果的示例代码和效果图如下： 39 40```ts 41// 创建字型对象 42const font = new drawing.Font(); 43// 设置字体大小 44font.setSize(100); 45// 创建字块对象 46const textBlob = drawing.TextBlob.makeFromString('Hello world', font, drawing.TextEncoding.TEXT_ENCODING_UTF8); 47// 绘制字块 48canvas.drawTextBlob(textBlob, 200, 300); 49``` 50 51 52 53## 文字描边 54 55基于基本的字块绘制，还可以通过画笔实现文字描边效果，描边效果的更多介绍请参考[描边效果](basic-drawing-effect-arkts.md#描边效果)。 56 57文字描边的简要示例和示意图如下： 58 59```ts 60// 创建画笔 61let pen = new drawing.Pen(); 62// 设置抗锯齿 63pen.setAntiAlias(true); 64// 设置描边线宽 65pen.setStrokeWidth(3.0); 66// 设置描边颜色 67pen.setColor(0xFF, 0xFF, 0x00, 0x00); 68// 创建字型对象 69const font = new drawing.Font(); 70// 设置字体大小 71font.setSize(100); 72// 添加画笔描边效果 73canvas.attachPen(pen); 74// 创建字块对象 75const textBlob = drawing.TextBlob.makeFromString('Hello world', font, drawing.TextEncoding.TEXT_ENCODING_UTF8); 76// 绘制字块 77canvas.drawTextBlob(textBlob, 200, 300); 78// 去除描边效果 79canvas.detachPen(); 80``` 81 82 83 84## 文字渐变 85 86基于基本字块绘制，还可以通过着色器实现文字渐变的效果，着色器的更多介绍请参考[着色器效果](complex-drawing-effect-arkts.md#着色器效果)。 87 88以下为文字添加了线性渐变着色器效果的简要示例和示意图： 89 90```ts 91let startPt: common2D.Point = { x: 100, y: 100 }; 92let endPt: common2D.Point = { x: 900, y: 900 }; 93let colors = [0xFFFFFF00, 0xFFFF0000, 0xFF0000FF]; 94// 创建线性渐变着色器 95let shaderEffect = drawing.ShaderEffect.createLinearGradient(startPt, endPt, colors, drawing.TileMode.CLAMP); 96// 创建画刷 97let brush = new drawing.Brush(); 98// 设置着色器 99brush.setShaderEffect(shaderEffect); 100// 添加画刷填充效果 101canvas.attachBrush(brush); 102// 创建字型 103const font = new drawing.Font(); 104// 设置字体大小 105font.setSize(200); 106// 创建字块 107const textBlob = drawing.TextBlob.makeFromString('Hello world', font, drawing.TextEncoding.TEXT_ENCODING_UTF8); 108// 绘制字块 109canvas.drawTextBlob(textBlob, 100, 300); 110// 去除填充效果 111canvas.detachBrush(); 112``` 113 114 115 116## 主题字体 117 118主题字体，特指系统**主题应用**中能使用的字体，属于一种特殊的自定义字体。如需涉及文本测量和布局排版相关内容，可参考[使用主题字体（ArkTS）](theme-font-arkts.md)。 119 120设置跟随主题字体的示例代码和效果图如下： 121 122```ts 123// 创建字型对象 124const font = new drawing.Font(); 125// 设置文字大小 126font.setSize(100); 127// 设置跟随主题字体 128font.setThemeFontFollowed(true); 129// 创建字块对象 130const textBlob = drawing.TextBlob.makeFromString('Hello World', font, drawing.TextEncoding.TEXT_ENCODING_UTF8); 131// 绘制字块 132canvas.drawTextBlob(textBlob, 200, 300); 133``` 134 135| 未跟随主题字体的效果图 | 跟随主题字体的效果图（不同主题字体显示效果不同，此处仅示意） | 136| -------- | -------- | 137|  |  | 138 139> **说明** 140> 141> 需要在应用入口文件（默认工程中为EntryAbility.ets）中复写onConfigurationUpdate函数，以响应切换主题字体的操作，确保切换后页面能够及时刷新并生效。具体实现可参考[使用主题字体（ArkTS）](theme-font-arkts.md)。 142 143## 单字绘制 144 145单字绘制是图形渲染中针对文本渲染的一种精细化控制技术。相比字块绘制，其核心优势在于能够利用字体退化机制，在当前字体无法显示某字符时，自动退化到使用系统字体绘制字符，提升对特殊字符的兼容性，避免字符缺失。同时，单字绘制支持逐字符配置字体特征（如连字、替代字形），满足复杂排版需求，增强用户体验。详细API说明请见[drawing.Canvas](../reference/apis-arkgraphics2d/arkts-apis-graphics-drawing-Canvas.md#drawsinglecharacter12)。 146 147基础场景：绘制无字体特征的字符 148对于无需字体特征的常规文本渲染场景，可以使用drawSingleCharacter绘制单个字符，使用measureSingleCharacter测量单个字符的宽度，示例代码和效果图如下： 149 150```ts 151// 创建字型对象 152const font = new drawing.Font(); 153// 设置文字大小 154font.setSize(100); 155let startX = 100; 156let startY = 100; 157let text = ['H', 'e', 'l', 'l', 'o']; 158for (let s of text) { 159 // 单字绘制 160 canvas.drawSingleCharacter(s, font, startX, startY); 161 // 测量单个字符的宽度 162 let textWidth = font.measureSingleCharacter(s); 163 startX += textWidth; 164} 165``` 166 167 168 169进阶场景：绘制带字体特征的字符 170对于需要字体特征的文本渲染场景，可以使用drawSingleCharacterWithFeatures绘制单个字符，使用measureSingleCharacterWithFeatures测量单个字符的宽度，示例代码和效果图如下： 171```ts 172// 创建字型对象 173const font = new drawing.Font(); 174// 设置文字大小 175font.setSize(100); 176let startX = 100; 177let startY = 100; 178let text = ['a', '2', '+', 'b', '2']; 179// 创建字体特征对象数组 180let fontFeatures : Array<drawing.FontFeature> = [{name: 'frac', value: 1}]; 181for (let s of text) { 182 // 单字绘制 183 canvas.drawSingleCharacterWithFeatures(s, font, startX, startY, fontFeatures); 184 // 测量单个字符的宽度 185 let textWidth = font.measureSingleCharacterWithFeatures(s, fontFeatures); 186 startX += textWidth; 187} 188``` 189 190 191 192> **说明** 193> 194> 如果 `drawSingleCharacterWithFeatures` 与 `measureSingleCharacter` 混合使用，或者 `drawSingleCharacter` 与 `measureSingleCharacterWithFeatures` 混合使用，字体绘制可能会重叠。 195 196<!--RP1--> 197## 相关实例 198 199针对Drawing(ArkTS)的开发，有以下相关实例可供参考： 200 201- [ArkTSGraphicsDraw (API14)](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/DocsSample/Drawing/ArkTSGraphicsDraw) 202<!--RP1End-->
