画布操作及状态处理（ArkTS）
================

#### 场景介绍

创建或获取Canvas画布之后，可以基于画布进一步地进行图形操作和状态处理。画布操作属于可选操作，开发者可以根据场景需要进行。需要先进行画布操作，再进行后续绘制，只有这样画布操作才有效果。

常见的画布操作如下：

*   裁剪。
    
*   矩阵变换，如平移、缩放、旋转等。
    
*   状态保存与恢复。
    

更多画布操作和具体接口参数使用，请见[drawing.Canvas](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-graphics-drawing-canvas)。

#### 裁剪操作

裁剪是图形处理中的常见操作，裁剪针对的是画布本身，可以用于限制绘图区域，只在指定的区域进行绘制。需要先进行裁剪操作，再进行绘制，才会有对应效果。

当前支持的裁剪操作主要如下：

*   裁剪矩形。
    
*   裁剪圆角矩形。
    
*   裁剪自定义路径。
    
*   裁剪一个区域。
    

#### \[h2\]接口说明

裁剪操作常用接口如下表所示，详细的使用和参数说明请见[drawing.Canvas](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-graphics-drawing-canvas)。

| 接口 | 描述 |
| :-- | :-- |
| clipRect(rect: common2D.Rect, clipOp?: ClipOp, doAntiAlias?: boolean): void | 用于裁剪一个矩形。 |
| clipRoundRect(roundRect: RoundRect, clipOp?: ClipOp, doAntiAlias?: boolean): void | 用于裁剪一个圆角矩形。 |
| clipPath(path: Path, clipOp?: ClipOp, doAntiAlias?: boolean): void | 用于裁剪一个自定义路径。 |
| clipRegion(region: Region, clipOp?: ClipOp): void | 用于裁剪一个区域。 |

#### \[h2\]开发示例

此处以在画布上裁剪矩形为例给出示例和效果图，其他裁剪操作的逻辑基本相同，注意调用对应的接口并确保要裁剪的数据类型对应准确即可，此处不再一一展开。详细的使用和参数说明请见[drawing.Canvas](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-graphics-drawing-canvas)。

使用clipRect()接口裁剪矩形。有以下3个入参：

*   rect是要裁剪的矩形区域。
    
*   clipOp是裁剪方式，包括交集（INTERSECT）和差集（DIFFERENCE），具体可见[ClipOp](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-graphics-drawing-e#clipop12)。
    
*   doAntiAlias表示是否需要抗锯齿处理，如果为true则启用抗锯齿功能，在绘制图形时会对图形的边缘像素进行半透明的模糊处理，如果为false则不开启。
    

// 创建画刷
let brush = new drawing.Brush();
// 设置颜色为蓝色
brush.setColor(0xFF, 0x00,  0x00, 0xFF);
// 设置画刷填充效果
canvas.attachBrush(brush);
// 创建矩形对象
let rect: common2D.Rect = { left: VALUE\_200, top: VALUE\_200, right: VALUE\_600, bottom: VALUE\_600 };
// 裁剪矩形区域
canvas.clipRect(rect);
// 绘制圆形
canvas.drawCircle(VALUE\_300, VALUE\_300, VALUE\_300);
// 去除填充效果
canvas.detachBrush();

| 原始图 | 裁剪后的图 |
| :-- | :-- |
| ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/1d/v3/d461WmujSiaYkHvtt-oVYw/zh-cn_image_0000002664328569.jpg?HW-CC-KV=V1&HW-CC-Date=20260709T132544Z&HW-CC-Expire=86400&HW-CC-Sign=5E9359C48D8C6BB3764F0C7FB51731ACA009F668186B14F10D008DE85BED4F99) | ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/80/v3/hwHzHjrzTYOmpB2kfyj4GQ/zh-cn_image_0000002633849458.jpg?HW-CC-KV=V1&HW-CC-Date=20260709T132544Z&HW-CC-Expire=86400&HW-CC-Sign=CDA58E0D5908DD0FCF4C30AFC7A508A9E7E12B52CB1C2649B6B7D6BB1EF36B91) |

#### 矩阵变换操作

矩阵变换也是常见的画布操作，是一种坐标系的转换，用于进行图形的变化。

当前支持的矩阵变换主要如下：

*   平移
    
*   缩放
    
*   旋转
    

#### \[h2\]接口说明

矩阵变换操作常用接口如下表所示，详细的使用和参数说明请见[drawing.Canvas](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-graphics-drawing-canvas)。

| 接口 | 描述 |
| :-- | :-- |
| translate(dx: number, dy: number): void | 用于平移画布一段距离。 |
| scale(sx: number, sy: number): void | 用于画布缩放。 |
| rotate(degrees: number, sx: number, sy: number): void | 用于画布旋转一定的角度，正数表示顺时针旋转，负数反之。 |
| skew(sx: number, sy: number) : void | 用于画布倾斜变换，包括水平轴和垂直轴上的偏移。 |

#### \[h2\]平移

使用translate()接口实现画布平移。接口接受2个参数，分别为水平方向和垂直方向的平移量，单位为px。

简单示例和示意图如下所示：

// 创建画刷
let brush = new drawing.Brush();
// 设置颜色为红色
brush.setColor(0xFF, 0xFF, 0x00, 0x00);
// 设置画刷填充效果
canvas.attachBrush(brush);
// 执行平移操作
canvas.translate(VALUE\_300, VALUE\_300);
// 绘制矩形
canvas.drawRect({ left: VALUE\_200, top: VALUE\_200, right: VALUE\_600, bottom: VALUE\_600 });
// 去除填充效果
canvas.detachBrush();

| 原始图 | 平移后的效果图 |
| :-- | :-- |
| ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/78/v3/QGHNz4xTSNGfQo9huv8Fgw/zh-cn_image_0000002634009362.jpg?HW-CC-KV=V1&HW-CC-Date=20260709T132544Z&HW-CC-Expire=86400&HW-CC-Sign=136C132BD96DDA5C9DCC2F4DAD03C341A1DA628E4DB7D9BB157A205825F65DF7) | ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/23/v3/iQZioJPnQmegB5rGOCjnrg/zh-cn_image_0000002664208511.jpg?HW-CC-KV=V1&HW-CC-Date=20260709T132544Z&HW-CC-Expire=86400&HW-CC-Sign=465F4BCAD8EAD5696F8556F47E3D50B445569C901B1993058C0A601A1D6C3CB0) |

#### \[h2\]旋转

使用rotate()接口实现画布旋转，接口接受3个参数，分别为：旋转角度、旋转中心的x坐标和y坐标。

简单示例和示意图如下所示：

// 创建画刷
let brush = new drawing.Brush();
// 设置颜色为红色
brush.setColor(0xFF, 0xFF, 0x00, 0x00);
// 设置画刷填充效果
canvas.attachBrush(brush);
// 顺时针旋转45度
canvas.rotate(45, VALUE\_200, VALUE\_200);
// 绘制矩形
canvas.drawRect({ left: VALUE\_200, top: VALUE\_200, right: VALUE\_600, bottom: VALUE\_600 });
// 去除填充效果
canvas.detachBrush();

| 原始图 | 旋转后的效果图 |
| :-- | :-- |
| ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/48/v3/BrstMnOIQ6C4vv7QOHs_ZA/zh-cn_image_0000002634009362.jpg?HW-CC-KV=V1&HW-CC-Date=20260709T132544Z&HW-CC-Expire=86400&HW-CC-Sign=DD5EB796DB64A737DE1423B0B6543E7B16185A7FA31E135A967A584BE533B09E) | ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/75/v3/jYlTNmFQTmyjLS0q7EjORA/zh-cn_image_0000002664328571.jpg?HW-CC-KV=V1&HW-CC-Date=20260709T132544Z&HW-CC-Expire=86400&HW-CC-Sign=BFBF7E1944A0687705835FFE2A49A617B61B69887B6191A620C1EE0ED57D0EDE) |

#### \[h2\]缩放

使用scale()接口进行画布缩放，接口接受2个参数，分别为沿x轴和y轴的缩放因子。

简单示例和示意图如下所示：

// 创建画刷
let brush = new drawing.Brush();
// 设置颜色为红色
brush.setColor({ alpha: 0xFF, red: 0xFF, green: 0x00, blue: 0x00 });
// 设置画刷填充效果
canvas.attachBrush(brush);
// 执行放大操作
canvas.scale(2, 2);
// 绘制矩形
canvas.drawRect({ left: VALUE\_200, top: VALUE\_200, right: VALUE\_600, bottom: VALUE\_600 });
// 去除填充效果
canvas.detachBrush();

| 原始图 | 缩放后的效果图 |
| :-- | :-- |
| ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/20/v3/OcoH1OjnRyGbgLYG6oLBtA/zh-cn_image_0000002634009362.jpg?HW-CC-KV=V1&HW-CC-Date=20260709T132544Z&HW-CC-Expire=86400&HW-CC-Sign=2FF02632138D6EA655C5654A91333FDB1826BE40A756317A5C5FBC5E08D5E805) | ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/3d/v3/YjyoP-XaSJmDV01OwmnFeA/zh-cn_image_0000002633849460.jpg?HW-CC-KV=V1&HW-CC-Date=20260709T132544Z&HW-CC-Expire=86400&HW-CC-Sign=188E50180489A23B1E1C10AF03EC0D42BE077E9677F9D097188159BC4109D442) |

#### 画布状态保存与恢复

保存操作用于保存当前画布的状态到一个栈顶，恢复操作用于恢复保存在栈顶的画布状态，恢复操作一旦执行，保存和恢复操作中间一系列平移、缩放、裁剪等操作都会被清除。

#### \[h2\]接口说明

画布状态保存与恢复使用的接口如下表所示，详细的使用和参数说明请见[drawing.Canvas](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-graphics-drawing-canvas)。

| 接口 | 描述 |
| :-- | :-- |
| save(): void | 用于保存当前画布的状态（画布矩阵）到一个栈顶。 |
| restore(): void | 用于恢复保存在栈顶的画布状态（画布矩阵）。 |
| restoreToCount(count: number): void | 用于恢复到指定数量的画布状态（画布矩阵）。 |

简单示例和示意图如下所示：

// 创建画笔
let pen = new drawing.Pen();
// 设置颜色为红色
pen.setColor({ alpha: 0xFF, red: 0xFF, green: 0x00, blue: 0x00 });
// 设置描边宽度为20px
pen.setStrokeWidth(20);
// 设置画笔描边效果
canvas.attachPen(pen);
// 保存操作，当前是不存在放大等操作的，这个原始状态会被保存下来
canvas.save();
// x轴和y轴方向分别放大2倍
canvas.scale(2, 2);
// 绘制圆形，因为执行过放大操作，所以此时绘制的是大圆
canvas.drawCircle(VALUE\_300, VALUE\_300, VALUE\_200);
// 恢复操作，恢复到没有放大的原始状态
canvas.restore();
// 绘制圆形，因为已经恢复到没有放大的原始状态，所以此时绘制的是小圆
canvas.drawCircle(VALUE\_300, VALUE\_300, VALUE\_200);
// 去除描边效果
canvas.detachPen();

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/e1/v3/vpn_2BSsTb6d1b24u8ExFg/zh-cn_image_0000002634009364.jpg?HW-CC-KV=V1&HW-CC-Date=20260709T132544Z&HW-CC-Expire=86400&HW-CC-Sign=5BC9EAF6AC71E30929D0CE573CB03034E04A242F08F3474CDC25A9F86CE141EE)

#### 示例代码

*   [图形绘制（ArkTS）](https://gitcode.com/HarmonyOS_Samples/guide-snippets/tree/master/ArkGraphics2D/Drawing/ArkTSGraphicsDraw)