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创建或获取得到Canvas画布之后，可以基于画布进一步地进行图形操作和状态处理。画布操作属于可选操作，开发者可以根据场景需要进行。需要先进行画布操作，再进行后续绘制，只有这样画布操作才有效果。 13 14常见的画布操作如下： 15 16- 裁剪。 17 18- 矩阵变换，如平移、缩放、旋转等。 19 20- 状态保存与恢复。 21 22更多画布操作和具体接口参数使用，请见[drawing.Canvas](../reference/apis-arkgraphics2d/arkts-apis-graphics-drawing-Canvas.md)。 23 24 25## 裁剪操作 26 27裁剪是图形处理中的常见操作，裁剪针对的是画布本身，可以用于限制绘图区域，只在指定的区域内容进行绘制。需要先进行裁剪操作，再进行绘制，才会有对应效果。 28 29当前支持的裁剪操作主要如下： 30 31- 裁剪矩形。 32 33- 裁剪圆角矩形。 34 35- 裁剪自定义路径。 36 37- 裁剪一个区域。 38 39 40### 接口说明 41 42裁剪操作常用接口如下表所示，详细的使用和参数说明请见[drawing.Canvas](../reference/apis-arkgraphics2d/arkts-apis-graphics-drawing-Canvas.md)。 43 44 45| 接口 | 描述 | 46| -------- | -------- | 47| clipRect(rect: common2D.Rect, clipOp?: ClipOp, doAntiAlias?: boolean): void | 用于裁剪一个矩形。 | 48| clipRoundRect(roundRect: RoundRect, clipOp?: ClipOp, doAntiAlias?: boolean): void | 用于裁剪一个圆角矩形。 | 49| clipPath(path: Path, clipOp?: ClipOp, doAntiAlias?: boolean): void | 用于裁剪一个自定义路径。 | 50| clipRegion(region: Region, clipOp?: ClipOp): void | 用于裁剪一个区域。 | 51 52 53### 开发示例 54 55此处以在画布上裁剪矩形为例给出示例和效果图，其他裁剪操作的逻辑基本相同，注意调用对应的接口并确保要裁剪的数据类型对应准确即可，此处不再一一展开。具体详细的使用和参数说明请见[drawing.Canvas](../reference/apis-arkgraphics2d/arkts-apis-graphics-drawing-Canvas.md)。 56 57使用clipRect()接口裁剪矩形。有以下3个入参： 58 59 60- rect是要裁剪的矩形区域。 61 62- clipOp是裁剪方式，包括交集（INTERSECT）和差集（DIFFERENCE），具体可见[ClipOp](../reference/apis-arkgraphics2d/arkts-apis-graphics-drawing-e.md#clipop12)。 63 64- doAntiAlias表示是否需要抗锯齿处理，如果为true则启用抗锯齿功能，在绘制图形时会对图形的边缘像素进行半透明的模糊处理，如果为false则不开启。 65 66 67```ts 68// 创建画刷 69let brush = new drawing.Brush(); 70// 设置颜色为蓝色 71brush.setColor(0xFF, 0x00, 0x00, 0xFF); 72// 设置画刷填充效果 73canvas.attachBrush(brush); 74// 创建矩形对象 75let rect: common2D.Rect = { left: 200, top: 200, right: 600, bottom: 600 }; 76// 裁剪矩形区域 77canvas.clipRect(rect); 78// 绘制圆形 79canvas.drawCircle(300, 300, 300); 80// 去除填充效果 81canvas.detachBrush(); 82``` 83 84 85| 原始图 | 裁剪后的图 | 86| -------- | -------- | 87|  |  | 88 89 90## 矩阵变换操作 91 92矩阵变换也是常见的画布操作，是一种坐标系的转换，用于进行图形的变化。 93 94当前支持的矩阵变换主要如下： 95 96- 平移 97 98- 缩放 99 100- 旋转 101 102 103### 接口说明 104 105矩阵变换操作常用接口如下表所示，详细的使用和参数说明请见[drawing.Canvas](../reference/apis-arkgraphics2d/arkts-apis-graphics-drawing-Canvas.md)。 106 107| 接口 | 描述 | 108| -------- | -------- | 109| translate(dx: number, dy: number): void | 用于平移画布一段距离。 | 110| scale(sx: number, sy: number): void | 用于画布缩放。 | 111| rotate(degrees: number, sx: number, sy: number): void | 用于画布旋转一定的角度，正数表示顺时针旋转，负数反之。 | 112| skew(sx: number, sy: number) : void | 用于画布倾斜变换，包括水平轴和垂直轴上的偏移。 | 113 114 115### 平移 116 117使用translate()接口实现画布平移。接口接受2个参数，分别为水平方向和垂直方向的平移量，单位为px。 118 119简单示例和示意图如下所示： 120 121 122```ts 123// 创建画刷 124let brush = new drawing.Brush(); 125// 设置颜色为红色 126brush.setColor(0xFF, 0xFF, 0x00, 0x00); 127// 设置画刷填充效果 128canvas.attachBrush(brush); 129// 执行平移操作 130canvas.translate(300, 300); 131// 绘制矩形 132canvas.drawRect({ left: 200, top: 200, right: 600, bottom: 600 }); 133// 去除填充效果 134canvas.detachBrush(); 135``` 136 137 138| 原始图 | 平移后的效果图 | 139| -------- | -------- | 140|  |  | 141 142 143### 旋转 144 145使用rotate()接口实现画布旋转，接口接受3个参数，分别为：旋转角度、旋转中心的x坐标和y坐标。 146 147 148简单示例和示意图如下所示： 149 150 151```ts 152// 创建画刷 153let brush = new drawing.Brush(); 154// 设置颜色为红色 155brush.setColor(0xFF, 0xFF, 0x00, 0x00); 156// 设置画刷填充效果 157canvas.attachBrush(brush); 158// 顺时针旋转45度 159canvas.rotate(45, 200, 200); 160// 绘制矩形 161canvas.drawRect({ left: 200, top: 200, right: 600, bottom: 600 }); 162// 去除填充效果 163canvas.detachBrush(); 164``` 165 166 167| 原始图 | 旋转后的效果图 | 168| -------- | -------- | 169|  |  | 170 171 172### 缩放 173 174使用scale()接口进行画布缩放，接口接受2个参数，分别为沿x轴和y轴的缩放因子。 175 176 177简单示例和示意图如下所示： 178 179 180```ts 181// 创建画刷 182let brush = new drawing.Brush(); 183// 设置颜色为红色 184brush.setColor({ alpha: 0xFF, red: 0xFF, green: 0x00, blue: 0x00 }); 185// 设置画刷填充效果 186canvas.attachBrush(brush); 187// 执行放大操作 188canvas.scale(2, 2); 189// 绘制矩形 190canvas.drawRect({ left: 200, top: 200, right: 600, bottom: 600 }); 191// 去除填充效果 192canvas.detachBrush(); 193``` 194 195 196| 原始图 | 缩放后的效果图 | 197| -------- | -------- | 198|  |  | 199 200 201## 画布状态保存与恢复 202 203 204保存操作用于保存当前画布的状态到一个栈顶，恢复操作用于恢复保存在栈顶的画布状态，恢复操作一旦执行，保存和恢复操作中间一系列平移、缩放、剪裁等操作都会被清除。 205 206 207### 接口说明 208 209画布状态保存与恢复使用的接口如下表所示，详细的使用和参数说明请见[canvas](../reference/apis-arkgraphics2d/arkts-apis-graphics-drawing-Canvas.md)。 210 211| 接口 | 描述 | 212| -------- | -------- | 213| save(): void | 用于保存当前画布的状态（画布矩阵）到一个栈顶。 | 214| restore(): void | 用于恢复保存在栈顶的画布状态（画布矩阵）。 | 215| restoreToCount(count: number): void | 用于恢复到指定数量的画布状态（画布矩阵）。 | 216 217简单示例和示意图如下所示： 218 219 220```ts 221// 创建画笔 222let pen = new drawing.Pen(); 223// 设置颜色为红色 224pen.setColor({ alpha: 0xFF, red: 0xFF, green: 0x00, blue: 0x00 }); 225// 设置描边宽度为20px 226pen.setStrokeWidth(20); 227// 设置画笔描边效果 228canvas.attachPen(pen); 229// 保存操作，当前是不存在放大等操作的，这个原始状态会被保存下来 230canvas.save(); 231// x轴和y轴方向分别放大2倍 232canvas.scale(2, 2); 233// 绘制圆形，因为执行过放大操作，所以此时绘制的是大圆 234canvas.drawCircle(300, 300, 200); 235// 恢复操作，恢复到没有放大的原始状态 236canvas.restore(); 237// 绘制圆形，因为已经恢复到没有放大的原始状态，所以此时绘制的是小圆 238canvas.drawCircle(300, 300, 200); 239// 去除描边效果 240canvas.detachPen(); 241``` 242 243 244 245 246<!--RP1--> 247## 相关实例 248 249针对Drawing(ArkTS)的开发，有以下相关实例可供参考： 250 251- [ArkTSGraphicsDraw (API14)](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/DocsSample/Drawing/ArkTSGraphicsDraw) 252<!--RP1End-->
