dc6e0b6b创建于 2025年7月4日历史提交

Class (Canvas)

说明：

本模块首批接口从API version 20开始支持跨平台。后续版本的新增接口，采用上角标单独标记接口的起始版本。

本模块使用屏幕物理像素单位px。

本模块为单线程模型策略，需要调用方自行管理线程安全和上下文状态的切换。

导入模块

import { drawing } from '@kit.ArkGraphics2D';

Canvas

承载绘制内容与绘制状态的载体。

说明：

画布自带一个默认画刷，该画刷为黑色，开启反走样，不具备其他任何样式效果。当画布中没有主动设置画刷和画笔时，该默认画刷生效。

constructor

constructor(pixelmap: image.PixelMap)

创建一个以PixelMap作为绘制目标的Canvas对象。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
pixelmap	image.PixelMap	是	构造函数入参。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { drawing } from '@kit.ArkGraphics2D';
import { image } from '@kit.ImageKit';

const color = new ArrayBuffer(96);
let opts : image.InitializationOptions = {
  editable: true,
  pixelFormat: 3,
  size: {
    height: 4,
    width: 6
  }
}
image.createPixelMap(color, opts).then((pixelMap) => {
  const canvas = new drawing.Canvas(pixelMap);
})

drawRect

drawRect(rect: common2D.Rect): void

绘制一个矩形，默认使用黑色填充。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
rect	common2D.Rect	是	绘制的矩形区域。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setStrokeWidth(5);
    pen.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    canvas.attachPen(pen);
    canvas.drawRect({ left : 0, right : 10, top : 0, bottom : 10 });
    canvas.detachPen();
  }
}

drawRect²⁰⁺

drawRect(left: number, top: number, right: number, bottom: number): void

绘制一个矩形，默认使用黑色填充。性能优于drawRect接口，推荐使用本接口。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
left	number	是	矩形的左上角x轴坐标，该参数为浮点数。
top	number	是	矩形的左上角y轴坐标，该参数为浮点数。
right	number	是	矩形的右下角x轴坐标，该参数为浮点数。
bottom	number	是	矩形的右下角y轴坐标，该参数为浮点数。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {

  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setStrokeWidth(5);
    pen.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    canvas.attachPen(pen);
    canvas.drawRect(0, 0, 10, 10);
    canvas.detachPen();
  }
}

drawRoundRect²⁰⁺

drawRoundRect(roundRect: RoundRect): void

画一个圆角矩形。

系统能力： SystemCapability.Graphics.Drawing

参数

参数名	类型	必填	说明
roundRect	RoundRect	是	圆角矩形对象。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let rect: common2D.Rect = { left : 100, top : 100, right : 400, bottom : 500 };
    let roundRect = new drawing.RoundRect(rect, 10, 10);
    canvas.drawRoundRect(roundRect);
  }
}

drawNestedRoundRect²⁰⁺

drawNestedRoundRect(outer: RoundRect, inner: RoundRect): void

绘制两个嵌套的圆角矩形，外部矩形边界必须包含内部矩形边界，否则无绘制效果。

系统能力： SystemCapability.Graphics.Drawing

参数

参数名	类型	必填	说明
outer	RoundRect	是	圆角矩形对象，表示外部圆角矩形边界。
inner	RoundRect	是	圆角矩形对象，表示内部圆角矩形边界。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let inRect: common2D.Rect = { left : 200, top : 200, right : 400, bottom : 500 };
    let outRect: common2D.Rect = { left : 100, top : 100, right : 400, bottom : 500 };
    let outRoundRect = new drawing.RoundRect(outRect, 10, 10);
    let inRoundRect = new drawing.RoundRect(inRect, 10, 10);
    canvas.drawNestedRoundRect(outRoundRect, inRoundRect);
    canvas.drawRoundRect(outRoundRect);
  }
}

drawBackground²⁰⁺

drawBackground(brush: Brush): void

使用画刷填充画布的可绘制区域。

系统能力： SystemCapability.Graphics.Drawing

参数

参数名	类型	必填	说明
brush	Brush	是	画刷对象。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const brush = new drawing.Brush();
    const color : common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 };
    brush.setColor(color);
    canvas.drawBackground(brush);
  }
}

drawShadow²⁰⁺

drawShadow(path: Path, planeParams: common2D.Point3d, devLightPos: common2D.Point3d, lightRadius: number, ambientColor: common2D.Color, spotColor: common2D.Color, flag: ShadowFlag) : void

绘制射灯类型阴影，使用路径描述环境光阴影的轮廓。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
path	Path	是	路径对象，可生成阴影。
planeParams	common2D.Point3d	是	表示一个三维向量，用于计算遮挡物相对于画布在z轴上的偏移量，其值取决于x与y坐标。
devLightPos	common2D.Point3d	是	光线相对于画布的位置。
lightRadius	number	是	圆形灯半径，该参数为浮点数。
ambientColor	common2D.Color	是	环境阴影颜色。
spotColor	common2D.Color	是	点阴影颜色。
flag	ShadowFlag	是	阴影标志枚举。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const path = new drawing.Path();
    path.addCircle(100, 200, 100, drawing.PathDirection.CLOCKWISE);
    let pen = new drawing.Pen();
    pen.setAntiAlias(true);
    let pen_color : common2D.Color = { alpha: 0xFF, red: 0xFF, green: 0x00, blue: 0x00 };
    pen.setColor(pen_color);
    pen.setStrokeWidth(10.0);
    canvas.attachPen(pen);
    let brush = new drawing.Brush();
    let brush_color : common2D.Color = { alpha: 0xFF, red: 0x00, green: 0xFF, blue: 0x00 };
    brush.setColor(brush_color);
    canvas.attachBrush(brush);
    let point1 : common2D.Point3d = {x: 100, y: 80, z:80};
    let point2 : common2D.Point3d = {x: 200, y: 10, z:40};
    let color1 : common2D.Color = {alpha: 0xFF, red:0, green:0, blue:0xFF};
    let color2 : common2D.Color = {alpha: 0xFF, red:0xFF, green:0, blue:0};
    let shadowFlag : drawing.ShadowFlag = drawing.ShadowFlag.ALL;
    canvas.drawShadow(path, point1, point2, 30, color1, color2, shadowFlag);
  }
}

drawShadow²⁰⁺

drawShadow(path: Path, planeParams: common2D.Point3d, devLightPos: common2D.Point3d, lightRadius: number, ambientColor: common2D.Color | number, spotColor: common2D.Color | number, flag: ShadowFlag) : void

绘制射灯类型阴影，使用路径描述环境光阴影的轮廓。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
path	Path	是	路径对象，可生成阴影。
planeParams	common2D.Point3d	是	表示一个三维向量，用于计算z轴方向的偏移量。
devLightPos	common2D.Point3d	是	光线相对于画布的位置。
lightRadius	number	是	圆形灯半径，该参数为浮点数。
ambientColor	common2D.Color \| number	是	环境阴影颜色，可以用16进制ARGB格式的32位无符号整数表示。
spotColor	common2D.Color \| number	是	点阴影颜色，可以用16进制ARGB格式的32位无符号整数表示。
flag	ShadowFlag	是	阴影标志枚举。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const path = new drawing.Path();
    path.addCircle(300, 600, 100, drawing.PathDirection.CLOCKWISE);
    let point1 : common2D.Point3d = {x: 100, y: 80, z:80};
    let point2 : common2D.Point3d = {x: 200, y: 10, z:40};
    let shadowFlag : drawing.ShadowFlag = drawing.ShadowFlag.ALL;
    canvas.drawShadow(path, point1, point2, 30, 0xFF0000FF, 0xFFFF0000, shadowFlag);
  }
}

getLocalClipBounds²⁰⁺

getLocalClipBounds(): common2D.Rect

获取画布裁剪区域的边界。

系统能力： SystemCapability.Graphics.Drawing

返回值：

类型	说明
common2D.Rect	返回画布裁剪区域的矩形边界。

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let clipRect: common2D.Rect = {
      left : 150, top : 150, right : 300, bottom : 400
    };
    canvas.clipRect(clipRect,drawing.ClipOp.DIFFERENCE, true);
    console.info("test rect.left: " + clipRect.left);
    console.info("test rect.top: " + clipRect.top);
    console.info("test rect.right: " + clipRect.right);
    console.info("test rect.bottom: " + clipRect.bottom);
    canvas.getLocalClipBounds();
  }
}

getTotalMatrix²⁰⁺

getTotalMatrix(): Matrix

获取画布矩阵。

系统能力： SystemCapability.Graphics.Drawing

返回值：

类型	说明
Matrix	返回画布矩阵。

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let matrix = new drawing.Matrix();
    matrix.setMatrix([5, 0, 0, 0, 1, 1, 0, 0, 1]);
    canvas.setMatrix(matrix);
    let matrixResult =canvas.getTotalMatrix();
  }
}

drawCircle

drawCircle(x: number, y: number, radius: number): void

绘制一个圆形。如果半径小于等于零，则不绘制。默认使用黑色填充。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
x	number	是	圆心的x坐标，该参数为浮点数。
y	number	是	圆心的y坐标，该参数为浮点数。
radius	number	是	圆的半径，大于0的浮点数。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed.

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setStrokeWidth(5);
    pen.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    canvas.attachPen(pen);
    canvas.drawCircle(10, 10, 2);
    canvas.detachPen();
  }
}

drawImage

drawImage(pixelmap: image.PixelMap, left: number, top: number, samplingOptions?: SamplingOptions): void

画一张图片，图片的左上角坐标为(left, top)。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
pixelmap	image.PixelMap	是	图片的PixelMap。
left	number	是	图片位置的左上角x轴坐标，该参数为浮点数。
top	number	是	图片位置的左上角y轴坐标，该参数为浮点数。
samplingOptions²⁰⁺	SamplingOptions	否	采样选项对象，默认为不使用任何参数构造的原始采样选项对象。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { image } from '@kit.ImageKit';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  pixelMap: image.PixelMap | null = null;

  async draw(context : DrawContext) {
    const canvas = context.canvas;
    let options = new drawing.SamplingOptions(drawing.FilterMode.FILTER_MODE_NEAREST);
    if (this.pixelMap != null) {
      canvas.drawImage(this.pixelMap, 0, 0, options);
    }
  }
}

drawImageRect²⁰⁺

drawImageRect(pixelmap: image.PixelMap, dstRect: common2D.Rect, samplingOptions?: SamplingOptions): void

将图片绘制到画布的指定区域上。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
pixelmap	image.PixelMap	是	图片的PixelMap。
dstRect	common2D.Rect	是	矩形对象，用于指定画布上图片的绘制区域。
samplingOptions	SamplingOptions	否	采样选项对象，默认为不使用任何参数构造的原始采样选项对象。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { image } from '@kit.ImageKit';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
pixelMap: image.PixelMap | null = null;
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let pen = new drawing.Pen();
    canvas.attachPen(pen);
    let rect: common2D.Rect = { left: 0, top: 0, right: 200, bottom: 200 };
    canvas.drawImageRect(this.pixelMap, rect);
    canvas.detachPen();
  }
}

drawImageRectWithSrc²⁰⁺

drawImageRectWithSrc(pixelmap: image.PixelMap, srcRect: common2D.Rect, dstRect: common2D.Rect, samplingOptions?: SamplingOptions, constraint?: SrcRectConstraint): void

将图片的指定区域绘制到画布的指定区域。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
pixelmap	image.PixelMap	是	图片的PixelMap。
srcRect	common2D.Rect	是	矩形对象，用于指定图片的待绘制区域。
dstRect	common2D.Rect	是	矩形对象，用于指定画布上图片的绘制区域。
samplingOptions	SamplingOptions	否	采样选项对象，默认为不使用任何参数构造的原始采样选项对象。
constraint	SrcRectConstraint	否	源矩形区域约束类型，默认为STRICT。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { image } from '@kit.ImageKit';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
pixelMap: image.PixelMap | null = null;
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let pen = new drawing.Pen();
    canvas.attachPen(pen);
    let srcRect: common2D.Rect = { left: 0, top: 0, right: 100, bottom: 100 };
    let dstRect: common2D.Rect = { left: 100, top: 100, right: 200, bottom: 200 };
    canvas.drawImageRectWithSrc(this.pixelMap, srcRect, dstRect);
    canvas.detachPen();
  }
}

drawColor

drawColor(color: common2D.Color, blendMode?: BlendMode): void

使用指定颜色并按照指定的BlendMode对画布当前可绘制区域进行填充。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
color	common2D.Color	是	ARGB格式的颜色，每个颜色通道的值是0到255之间的整数。
blendMode	BlendMode	否	颜色混合模式，默认模式为SRC_OVER。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let color: common2D.Color = {
      alpha : 255,
      red: 0,
      green: 10,
      blue: 10
    }
    canvas.drawColor(color, drawing.BlendMode.CLEAR);
  }
}

drawColor²⁰⁺

drawColor(alpha: number, red: number, green: number, blue: number, blendMode?: BlendMode): void

使用指定颜色并按照指定的BlendMode对画布当前可绘制区域进行填充。性能优于drawColor接口，推荐使用本接口。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
alpha	number	是	ARGB格式颜色的透明度通道值，该参数是0到255之间的整数，传入范围内的浮点数会向下取整。
red	number	是	ARGB格式颜色的红色通道值，该参数是0到255之间的整数，传入范围内的浮点数会向下取整。
green	number	是	ARGB格式颜色的绿色通道值，该参数是0到255之间的整数，传入范围内的浮点数会向下取整。
blue	number	是	ARGB格式颜色的蓝色通道值，该参数是0到255之间的整数，传入范围内的浮点数会向下取整。
blendMode	BlendMode	否	颜色混合模式，默认模式为SRC_OVER。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed.

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    canvas.drawColor(255, 0, 10, 10, drawing.BlendMode.CLEAR);
  }
}

drawColor²⁰⁺

drawColor(color: number, blendMode?: BlendMode): void

使用指定颜色并按照指定的BlendMode对画布当前可绘制区域进行填充。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
color	number	是	16进制ARGB格式的颜色。
blendMode	BlendMode	否	颜色混合模式，默认模式为SRC_OVER。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed.

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    canvas.drawColor(0xff000a0a, drawing.BlendMode.CLEAR);
  }
}

drawPixelMapMesh²⁰⁺

drawPixelMapMesh(pixelmap: image.PixelMap, meshWidth: number, meshHeight: number, vertices: Array<number>, vertOffset: number, colors: Array<number>, colorOffset: number): void

在网格上绘制像素图，网格均匀分布在像素图上。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
pixelmap	image.PixelMap	是	用于绘制网格的像素图。
meshWidth	number	是	网格中的列数，大于0的整数。
meshHeight	number	是	网格中的行数，大于0的整数。
vertices	Array<number>	是	顶点数组，指定网格的绘制位置，浮点数组，大小必须为((meshWidth+1) * (meshHeight+1) + vertOffset) * 2。
vertOffset	number	是	绘图前要跳过的vert元素数，大于等于0的整数。
colors	Array<number>	是	颜色数组，在每个顶点指定一种颜色，整数数组，可为null，大小必须为(meshWidth+1) * (meshHeight+1) + colorOffset。
colorOffset	number	是	绘制前要跳过的颜色元素数，大于等于0的整数。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { image } from '@kit.ImageKit';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  pixelMap: image.PixelMap | null = null;

  async draw(context : DrawContext) {
    const canvas = context.canvas;
    if (this.pixelMap != null) {
      const brush = new drawing.Brush(); // 只支持brush，使用pen没有绘制效果。
      canvas.attachBrush(brush);
      let verts : Array<number> = [0, 0, 50, 0, 410, 0, 0, 180, 50, 180, 410, 180, 0, 360, 50, 360, 410, 360]; // 18
      canvas.drawPixelMapMesh(this.pixelMap, 2, 2, verts, 0, null, 0);
      canvas.detachBrush();
    }
  }
}

clear²⁰⁺

clear(color: common2D.Color): void

使用指定颜色填充画布上的裁剪区域。效果等同于drawColor。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
color	common2D.Color	是	ARGB格式的颜色，每个颜色通道的值是0到255之间的整数。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let color: common2D.Color = {alpha: 255, red: 255, green: 0, blue: 0};
    canvas.clear(color);
  }
}

clear²⁰⁺

clear(color: common2D.Color | number): void

使用指定颜色填充画布上的裁剪区域。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
color	common2D.Color \| number	是	颜色，可以用16进制ARGB格式的无符号整数表示。

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let color: number = 0xffff0000;
    canvas.clear(color);
  }
}

getWidth²⁰⁺

getWidth(): number

获取画布的宽度。

系统能力： SystemCapability.Graphics.Drawing

返回值：

类型	必填	说明
number	是	返回画布的宽度，该参数为浮点数。

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let width = canvas.getWidth();
    console.info('get canvas width:' + width);
  }
}

getHeight²⁰⁺

getHeight(): number

获取画布的高度。

系统能力： SystemCapability.Graphics.Drawing

返回值：

类型	必填	说明
number	是	返回画布的高度，该参数为浮点数。

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let height = canvas.getHeight();
    console.log('get canvas height:' + height);
  }
}

drawOval²⁰⁺

drawOval(oval: common2D.Rect): void

在画布上绘制一个椭圆，椭圆的形状和位置由椭圆的外切矩形给出。

系统能力： SystemCapability.Graphics.Drawing

参数

参数名	类型	必填	说明
oval	common2D.Rect	是	矩形区域，该矩形的内切椭圆即为待绘制椭圆。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setStrokeWidth(5);
    const color : common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 };
    pen.setColor(color);
    canvas.attachPen(pen);
    const rect: common2D.Rect = {left:100, top:50, right:400, bottom:500};
    canvas.drawOval(rect);
    canvas.detachPen();
  }
}

drawArc²⁰⁺

drawArc(arc: common2D.Rect, startAngle: number, sweepAngle: number): void

在画布上绘制圆弧。该方法允许指定起始角度、扫描角度。当扫描角度的绝对值大于360度时，则绘制椭圆。

系统能力： SystemCapability.Graphics.Drawing

参数

参数名	类型	必填	说明
arc	common2D.Rect	是	包含要绘制的圆弧的椭圆的矩形边界。
startAngle	number	是	弧的起始角度，单位为度，该参数为浮点数。0度时起始点位于椭圆的右端点，正数时以顺时针方向放置起始点，负数时以逆时针方向放置起始点。
sweepAngle	number	是	弧的扫描角度，单位为度，该参数为浮点数。为正数时顺时针扫描，为负数时逆时针扫描。它的有效范围在-360度到360度之间，当绝对值大于360度时，该方法绘制的是一个椭圆。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setStrokeWidth(5);
    const color : common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 };
    pen.setColor(color);
    canvas.attachPen(pen);
    const rect: common2D.Rect = {left:100, top:50, right:400, bottom:200};
    canvas.drawArc(rect, 90, 180);
    canvas.detachPen();
  }
}

drawPoint

drawPoint(x: number, y: number): void

绘制一个点。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
x	number	是	点的x轴坐标，该参数为浮点数。
y	number	是	点的y轴坐标，该参数为浮点数。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setStrokeWidth(5);
    pen.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    canvas.attachPen(pen);
    canvas.drawPoint(10, 10);
    canvas.detachPen();
  }
}

drawPoints²⁰⁺

drawPoints(points: Array<common2D.Point>, mode?: PointMode): void

在画布上绘制一组点、线段或多边形。通过指定点的数组和绘制模式来决定绘制方式。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
points	Array<common2D.Point>	是	要绘制的点的数组。长度不能为0。
mode	PointMode	否	绘制数组中的点的方式，默认为drawing.PointMode.POINTS。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setStrokeWidth(30);
    const color : common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 };
    pen.setColor(color);
    canvas.attachPen(pen);
    canvas.drawPoints([{x: 100, y: 200}, {x: 150, y: 230}, {x: 200, y: 300}], drawing.PointMode.POINTS);
    canvas.detachPen();
  }
}

drawPath

drawPath(path: Path): void

绘制一个自定义路径，该路径包含了一组路径轮廓，每个路径轮廓可以是开放的或封闭的。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
path	Path	是	要绘制的路径对象。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setStrokeWidth(5);
    pen.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    let path = new drawing.Path();
    path.moveTo(10,10);
    path.cubicTo(10, 10, 10, 10, 15, 15);
    path.close();
    canvas.attachPen(pen);
    canvas.drawPath(path);
    canvas.detachPen();
  }
}

drawLine

drawLine(x0: number, y0: number, x1: number, y1: number): void

画一条直线段，从指定的起点到终点。如果直线段的起点和终点是同一个点，无法绘制。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
x0	number	是	线段起点的X坐标，该参数为浮点数。
y0	number	是	线段起点的Y坐标，该参数为浮点数。
x1	number	是	线段终点的X坐标，该参数为浮点数。
y1	number	是	线段终点的Y坐标，该参数为浮点数。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setStrokeWidth(5);
    pen.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    canvas.attachPen(pen);
    canvas.drawLine(0, 0, 20, 20);
    canvas.detachPen();
  }
}

drawTextBlob

drawTextBlob(blob: TextBlob, x: number, y: number): void

绘制一段文字。若构造blob的字体不支持待绘制字符，则该部分字符无法绘制。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
blob	TextBlob	是	TextBlob对象。
x	number	是	所绘制出的文字基线（下图蓝线）的左端点（下图红点）的横坐标，该参数为浮点数。
y	number	是	所绘制出的文字基线（下图蓝线）的左端点（下图红点）的纵坐标，该参数为浮点数。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const brush = new drawing.Brush();
    brush.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    const font = new drawing.Font();
    font.setSize(20);
    const textBlob = drawing.TextBlob.makeFromString("Hello, drawing", font, drawing.TextEncoding.TEXT_ENCODING_UTF8);
    canvas.attachBrush(brush);
    canvas.drawTextBlob(textBlob, 20, 20);
    canvas.detachBrush();
  }
}

drawSingleCharacter²⁰⁺

drawSingleCharacter(text: string, font: Font, x: number, y: number): void

绘制单个字符。当前字型中的字体不支持待绘制字符时，退化到使用系统字体绘制字符。

系统能力： SystemCapability.Graphics.Drawing

参数

参数名	类型	必填	说明
text	string	是	待绘制的单个字符，字符串的长度必须为1。
font	Font	是	字型对象。
x	number	是	所绘制出的字符基线（下图蓝线）的左端点（下图红点）的横坐标，该参数为浮点数。
y	number	是	所绘制出的字符基线（下图蓝线）的左端点（下图红点）的纵坐标，该参数为浮点数。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed.

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const brush = new drawing.Brush();
    brush.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    const font = new drawing.Font();
    font.setSize(20);
    canvas.attachBrush(brush);
    canvas.drawSingleCharacter("你", font, 100, 100);
    canvas.drawSingleCharacter("好", font, 120, 100);
    canvas.detachBrush();
  }
}

drawRegion²⁰⁺

drawRegion(region: Region): void

绘制一个区域。

系统能力： SystemCapability.Graphics.Drawing

参数

参数名	类型	必填	说明
region	Region	是	绘制的区域。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    let region = new drawing.Region();
    pen.setStrokeWidth(10);
    pen.setColor({ alpha: 255, red: 255, green: 0, blue: 0 });
    canvas.attachPen(pen);
    region.setRect(100, 100, 400, 400);
    canvas.drawRegion(region);
    canvas.detachPen();
  }
}

attachPen

attachPen(pen: Pen): void

绑定画笔到画布上，在画布上进行绘制时，将使用画笔的样式去绘制图形形状的轮廓。

说明：

执行该方法后，若pen的效果发生改变并且开发者希望该变化生效于接下来的绘制动作，需要再次执行该方法以确保变化生效。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
pen	Pen	是	画笔对象。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setStrokeWidth(5);
    pen.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    canvas.attachPen(pen);
    canvas.drawRect({ left : 0, right : 10, top : 0, bottom : 10 });
    canvas.detachPen();
  }
}

attachBrush

attachBrush(brush: Brush): void

绑定画刷到画布上，在画布上进行绘制时，将使用画刷的样式对绘制图形形状的内部进行填充。

说明：

执行该方法后，若brush的效果发生改变并且开发者希望该变化生效于接下来的绘制动作，需要再次执行该方法以确保变化生效。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
brush	Brush	是	画刷对象。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const brush = new drawing.Brush();
    brush.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    canvas.attachBrush(brush);
    canvas.drawRect({ left : 0, right : 10, top : 0, bottom : 10 });
    canvas.detachBrush();
  }
}

detachPen

detachPen(): void

将画笔与画布解绑，在画布上进行绘制时，不会再使用画笔去绘制图形形状的轮廓。

系统能力： SystemCapability.Graphics.Drawing

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setStrokeWidth(5);
    pen.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    canvas.attachPen(pen);
    canvas.drawRect({ left : 0, right : 10, top : 0, bottom : 10 });
    canvas.detachPen();
  }
}

detachBrush

detachBrush(): void

将画刷与画布解绑，在画布上进行绘制时，不会再使用画刷对绘制图形形状的内部进行填充。

系统能力： SystemCapability.Graphics.Drawing

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const brush = new drawing.Brush();
    brush.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    canvas.attachBrush(brush);
    canvas.drawRect({ left : 0, right : 10, top : 0, bottom : 10 });
    canvas.detachBrush();
  }
}

clipPath²⁰⁺

clipPath(path: Path, clipOp?: ClipOp, doAntiAlias?: boolean): void

使用自定义路径对画布的可绘制区域进行裁剪。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
path	Path	是	路径对象。
clipOp	ClipOp	否	裁剪方式。默认为INTERSECT。
doAntiAlias	boolean	否	表示是否使能抗锯齿绘制。true表示使能，false表示不使能。默认为false。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let path = new drawing.Path();
    path.moveTo(10, 10);
    path.cubicTo(100, 100, 80, 150, 300, 150);
    path.close();
    canvas.clipPath(path, drawing.ClipOp.INTERSECT, true);
    canvas.clear({alpha: 255, red: 255, green: 0, blue: 0});
  }
}

clipRect²⁰⁺

clipRect(rect: common2D.Rect, clipOp?: ClipOp, doAntiAlias?: boolean): void

使用矩形对画布的可绘制区域进行裁剪。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
rect	common2D.Rect	是	需要裁剪的矩形区域。
clipOp	ClipOp	否	裁剪方式。默认为INTERSECT。
doAntiAlias	boolean	否	表示是否使能抗锯齿绘制。true表示使能，false表示不使能。默认为false。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    canvas.clipRect({left : 10, right : 500, top : 300, bottom : 900}, drawing.ClipOp.DIFFERENCE, true);
    canvas.clear({alpha: 255, red: 255, green: 0, blue: 0});
  }
}

save²⁰⁺

save(): number

保存当前画布状态（画布矩阵和可绘制区域）到栈顶。需要与恢复接口restore配合使用。

系统能力： SystemCapability.Graphics.Drawing

返回值：

类型	说明
number	画布状态个数，该参数为正整数。

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let rect: common2D.Rect = {left: 10, right: 200, top: 100, bottom: 300};
    canvas.drawRect(rect);
    let saveCount = canvas.save();
  }
}

saveLayer²⁰⁺

saveLayer(rect?: common2D.Rect | null, brush?: Brush | null): number

保存当前画布的矩阵和裁剪区域，并为后续绘制分配位图。调用恢复接口restore将会舍弃对矩阵和裁剪区域做的更改，并绘制位图。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
rect	common2D.Rect\|null	否	矩形对象，用于限制图层大小，默认为当前画布大小。
brush	Brush\|null	否	画刷对象，绘制位图时会应用画刷对象的透明度，颜色滤波器效果和混合模式，默认不设置额外效果。

返回值：

类型	说明
number	返回调用前保存的画布状态数，该参数为正整数。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: Mandatory parameters are left unspecified.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    canvas.saveLayer(null, null);
    const brushRect = new drawing.Brush();
    const colorRect: common2D.Color = {alpha: 255, red: 255, green: 255, blue: 0};
    brushRect.setColor(colorRect);
    canvas.attachBrush(brushRect);
    const rect: common2D.Rect = {left:100, top:100, right:500, bottom:500};
    canvas.drawRect(rect);

    const brush = new drawing.Brush();
    brush.setBlendMode(drawing.BlendMode.DST_OUT);
    canvas.saveLayer(rect, brush);

    const brushCircle = new drawing.Brush();
    const colorCircle: common2D.Color = {alpha: 255, red: 0, green: 0, blue: 255};
    brushCircle.setColor(colorCircle);
    canvas.attachBrush(brushCircle);
    canvas.drawCircle(500, 500, 200);
    canvas.restore();
    canvas.restore();
    canvas.detachBrush();
  }
}

scale²⁰⁺

scale(sx: number, sy: number): void

在当前画布矩阵（默认是单位矩阵）的基础上再叠加一个缩放矩阵，后续绘制操作和裁剪操作的形状和位置都会自动叠加一个缩放效果。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
sx	number	是	x轴方向的缩放比例，该参数为浮点数。
sy	number	是	y轴方向的缩放比例，该参数为浮点数。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setStrokeWidth(5);
    pen.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    canvas.attachPen(pen);
    canvas.scale(2, 0.5);
    canvas.drawRect({left : 10, right : 500, top : 300, bottom : 900});
    canvas.detachPen();
  }
}

skew²⁰⁺

skew(sx: number, sy: number) : void

在当前画布矩阵（默认是单位矩阵）的基础上再叠加一个倾斜矩阵，后续绘制操作和裁剪操作的形状和位置都会自动叠加一个倾斜效果。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
sx	number	是	x轴上的倾斜量，该参数为浮点数。正值会使绘制沿y轴增量方向向右倾斜；负值会使绘制沿y轴增量方向向左倾斜。
sy	number	是	y轴上的倾斜量，该参数为浮点数。正值会使绘制沿x轴增量方向向下倾斜；负值会使绘制沿x轴增量方向向上倾斜。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setStrokeWidth(5);
    pen.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    canvas.attachPen(pen);
    canvas.skew(0.1, 0.1);
    canvas.drawRect({left : 10, right : 500, top : 300, bottom : 900});
    canvas.detachPen();
  }
}

rotate²⁰⁺

rotate(degrees: number, sx: number, sy: number) : void

在当前画布矩阵（默认是单位矩阵）的基础上再叠加一个旋转矩阵，后续绘制操作和裁剪操作的形状和位置都会自动叠加一个旋转效果。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
degrees	number	是	旋转角度，单位为度，该参数为浮点数，正数为顺时针旋转，负数为逆时针旋转。
sx	number	是	旋转中心的横坐标，该参数为浮点数。
sy	number	是	旋转中心的纵坐标，该参数为浮点数。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setStrokeWidth(5);
    pen.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    canvas.attachPen(pen);
    canvas.rotate(30, 100, 100);
    canvas.drawRect({left : 10, right : 500, top : 300, bottom : 900});
    canvas.detachPen();
  }
}

translate²⁰⁺

translate(dx: number, dy: number): void

在当前画布矩阵（默认是单位矩阵）的基础上再叠加一个平移矩阵，后续绘制操作和裁剪操作的形状和位置都会自动叠加一个平移效果。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
dx	number	是	x轴方向的移动距离，该参数为浮点数。
dy	number	是	y轴方向的移动距离，该参数为浮点数。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setStrokeWidth(5);
    pen.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    canvas.attachPen(pen);
    canvas.translate(10, 10);
    canvas.drawRect({left : 10, right : 500, top : 300, bottom : 900});
    canvas.detachPen();
  }
}

getSaveCount²⁰⁺

getSaveCount(): number

获取栈中保存的画布状态（画布矩阵和裁剪区域）的数量。

系统能力： SystemCapability.Graphics.Drawing

返回值：

类型	说明
number	已保存的画布状态的数量，该参数为正整数。

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setStrokeWidth(5);
    pen.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    canvas.attachPen(pen);
    canvas.drawRect({left: 10, right: 200, top: 100, bottom: 300});
    canvas.save();
    canvas.drawRect({left : 10, right : 500, top : 300, bottom : 900});
    canvas.getSaveCount();
    canvas.detachPen();
  }
}

restoreToCount²⁰⁺

restoreToCount(count: number): void

恢复到指定数量的画布状态（画布矩阵和裁剪区域）。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
count	number	是	要恢复的画布状态深度，该参数为整数。小于等于1时，恢复为初始状态；大于已保存的画布状态数量时，不执行任何操作。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setStrokeWidth(5);
    pen.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    canvas.attachPen(pen);
    canvas.drawRect({left: 10, right: 200, top: 100, bottom: 300});
    canvas.save();
    canvas.drawRect({left: 10, right: 200, top: 100, bottom: 500});
    canvas.save();
    canvas.drawRect({left: 100, right: 300, top: 100, bottom: 500});
    canvas.save();
    canvas.restoreToCount(2);
    canvas.drawRect({left : 10, right : 500, top : 300, bottom : 900});
    canvas.detachPen();
  }
}

restore²⁰⁺

restore(): void

恢复保存在栈顶的画布状态（画布矩阵和裁剪区域）。

系统能力： SystemCapability.Graphics.Drawing

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setStrokeWidth(5);
    pen.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    canvas.attachPen(pen);
    canvas.restore();
    canvas.detachPen();
  }
}

concatMatrix²⁰⁺

concatMatrix(matrix: Matrix): void

画布现有矩阵左乘传入矩阵，不影响之前的绘制操作，后续绘制操作和裁剪操作的形状和位置都会受到该矩阵的影响。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
matrix	Matrix	是	矩阵对象。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let matrix = new drawing.Matrix();
    matrix.setMatrix([5, 0, 0, 0, 1, 2, 0, 0, 1]);
    canvas.concatMatrix(matrix);
    canvas.drawRect({left: 10, right: 200, top: 100, bottom: 500});
  }
}

setMatrix²⁰⁺

setMatrix(matrix: Matrix): void

设置画布的矩阵，后续绘制操作和裁剪操作的形状和位置都会受到该矩阵的影响。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
matrix	Matrix	是	矩阵对象。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let matrix = new drawing.Matrix()
    matrix.setMatrix([5, 0, 0, 0, 1, 1, 0, 0, 1]);
    canvas.setMatrix(matrix);
    canvas.drawRect({left: 10, right: 200, top: 100, bottom: 500});
  }
}

isClipEmpty²⁰⁺

isClipEmpty(): boolean

判断裁剪后的可绘制区域是否为空。

系统能力： SystemCapability.Graphics.Drawing

返回值：

类型	说明
boolean	返回画布的可绘制区域是否为空的结果，true表示为空，false表示不为空。

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    if (canvas.isClipEmpty()) {
      console.info("canvas.isClipEmpty() returned true");
    } else {
      console.info("canvas.isClipEmpty() returned false");
    }
  }
}

clipRegion²⁰⁺

clipRegion(region: Region, clipOp?: ClipOp): void

在画布上裁剪一个区域。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
region	Region	是	区域对象，表示裁剪范围。
clipOp	ClipOp	否	裁剪方式，默认为INTERSECT。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let region : drawing.Region = new drawing.Region();
    region.setRect(0, 0, 500, 500);
    canvas.clipRegion(region);
    let color: common2D.Color = {alpha: 255, red: 255, green: 0, blue: 0};
    canvas.clear(color);
  }
}

clipRoundRect²⁰⁺

clipRoundRect(roundRect: RoundRect, clipOp?: ClipOp, doAntiAlias?: boolean): void

在画布上裁剪一个圆角矩形。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
roundRect	RoundRect	是	圆角矩形对象，表示裁剪范围。
clipOp	ClipOp	否	裁剪方式，默认为INTERSECT。
doAntiAlias	boolean	否	表示是否使能抗锯齿。true表示使能，false表示不使能。默认为false。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let rect: common2D.Rect = { left: 10, top: 100, right: 200, bottom: 300 };
    let roundRect = new drawing.RoundRect(rect, 10, 10);
    canvas.clipRoundRect(roundRect);
    let color: common2D.Color = {alpha: 255, red: 255, green: 0, blue: 0};
    canvas.clear(color);
  }
}

resetMatrix²⁰⁺

resetMatrix(): void

将当前画布的矩阵重置为单位矩阵。

系统能力： SystemCapability.Graphics.Drawing

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    canvas.scale(4, 6);
    canvas.resetMatrix();
  }
}

quickRejectPath²⁰⁺

quickRejectPath(path: Path): boolean

判断路径与画布区域是否不相交。画布区域包含边界。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
path	Path	是	路径对象。

返回值：

类型	说明
boolean	返回路径是否与画布区域不相交的结果。true表示路径与画布区域不相交，false表示路径与画布区域相交。

示例：

import { RenderNode } from '@kit.ArkUI';
import { drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let path = new drawing.Path();
    path.moveTo(10, 10);
    path.cubicTo(10, 10, 10, 10, 15, 15);
    path.close();
    if (canvas.quickRejectPath(path)) {
      console.info("canvas and path do not intersect.");
    } else {
      console.info("canvas and path intersect.");
    }
  }
}

quickRejectRect²⁰⁺

quickRejectRect(rect: common2D.Rect): boolean

判断矩形和画布区域是否不相交。画布区域包含边界。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
rect	common2D.Rect	是	矩形区域。

返回值：

类型	说明
boolean	返回矩形是否与画布区域不相交的结果。true表示矩形与画布区域不相交，false表示矩形与画布区域相交。

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let rect: common2D.Rect = { left : 10, top : 20, right : 50, bottom : 30 };
    if (canvas.quickRejectRect(rect)) {
      console.info("canvas and rect do not intersect.");
    } else {
      console.info("canvas and rect intersect.");
    }
  }
}

drawArcWithCenter²⁰⁺

drawArcWithCenter(arc: common2D.Rect, startAngle: number, sweepAngle: number, useCenter: boolean): void

在画布上绘制圆弧。该方法允许指定圆弧的起始角度、扫描角度以及圆弧的起点和终点是否连接圆弧的中心点。

系统能力： SystemCapability.Graphics.Drawing

参数

参数名	类型	必填	说明
arc	common2D.Rect	是	包含要绘制的圆弧的椭圆的矩形边界。
startAngle	number	是	弧的起始角度，单位为度，该参数为浮点数。0度时起始点位于椭圆的右端点，为正数时以顺时针方向放置起始点，为负数时以逆时针方向放置起始点。
sweepAngle	number	是	弧的扫描角度，单位为度，该参数为浮点数。为正数时顺时针扫描，为负数时逆时针扫描。扫描角度可以超过360度，将绘制一个完整的椭圆。
useCenter	boolean	是	绘制时弧形的起点和终点是否连接弧形的中心点。true表示连接，false表示不连接。

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    const pen = new drawing.Pen();
    pen.setStrokeWidth(5);
    const color : common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 };
    pen.setColor(color);
    canvas.attachPen(pen);
    const rect: common2D.Rect = { left: 100, top: 50, right: 400, bottom: 200 };
    canvas.drawArcWithCenter(rect, 90, 180, false);
    canvas.detachPen();
  }
}

drawImageNine²⁰⁺

drawImageNine(pixelmap: image.PixelMap, center: common2D.Rect, dstRect: common2D.Rect, filterMode: FilterMode): void

通过绘制两条水平线和两条垂直线将图像分割成9个部分：四个边，四个角和中心。
若角落的4个区域尺寸不超过目标矩形，则会在不缩放的情况下被绘制在目标矩形，反之则会按比例缩放绘制在目标矩形；如果还有剩余空间，剩下的5个区域会通过拉伸或压缩来绘制，以便能够完全覆盖目标矩形。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
pixelmap	image.PixelMap	是	用于绘制网格的像素图。
center	common2D.Rect	是	分割图像的中心矩形。矩形四条边所在的直线将图像分成了9个部分。
dstRect	common2D.Rect	是	在画布上绘制的目标矩形区域。
filterMode	FilterMode	是	过滤模式。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';
import { image } from '@kit.ImageKit';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let pixelMap: image.PixelMap = globalThis.getInstance().getPixelMap("test_2.jpg");
    canvas.drawImage(pixelMap, 0, 0); // 原图
    let center: common2D.Rect = { left: 20, top: 10, right: 50, bottom: 40 };
    let dst: common2D.Rect = { left: 70, top: 0, right: 100, bottom: 30 };
    let dst1: common2D.Rect = { left: 110, top: 0, right: 200, bottom: 90 };
    canvas.drawImageNine(pixelMap, center, dst, drawing.FilterMode.FILTER_MODE_NEAREST); // 示例1
    canvas.drawImageNine(pixelMap, center, dst1, drawing.FilterMode.FILTER_MODE_NEAREST); // 示例2
  }
}

drawImageLattice²⁰⁺

drawImageLattice(pixelmap: image.PixelMap, lattice: Lattice, dstRect: common2D.Rect, filterMode: FilterMode): void

将图像按照矩形网格对象的设置划分为多个网格，并把图像的每个部分按照网格对象的设置绘制到画布上的目标矩形区域。
偶数行和列（起始计数为0）的每个交叉点都是固定的，若固定网格区域的尺寸不超过目标矩形，则会在不缩放的情况下被绘制在目标矩形，反之则会按比例缩放绘制在目标矩形；如果还有剩余空间，剩下的区域会通过拉伸或压缩来绘制，以便能够完全覆盖目标矩形。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
pixelmap	image.PixelMap	是	用于绘制网格的像素图。
lattice	Lattice	是	矩形网格对象。
dstRect	common2D.Rect	是	目标矩形区域。
filterMode	FilterMode	是	过滤模式。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
401	Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed.

示例：

import { RenderNode } from '@kit.ArkUI';
import { common2D, drawing } from '@kit.ArkGraphics2D';
import { image } from '@kit.ImageKit';

class DrawingRenderNode extends RenderNode {
  draw(context : DrawContext) {
    const canvas = context.canvas;
    let pixelMap: image.PixelMap = globalThis.getInstance().getPixelMap("test_3.jpg");
    canvas.drawImage(pixelMap, 0, 0); // 原图
    let xDivs: Array<number> = [28, 36, 44, 52];
    let yDivs: Array<number> = [28, 36, 44, 52];
    let lattice = drawing.Lattice.createImageLattice(xDivs, yDivs, 4, 4);
    let dst: common2D.Rect = { left: 100, top: 0, right: 164, bottom: 64 };
    let dst1: common2D.Rect = { left: 200, top: 0, right: 360, bottom: 160 };
    canvas.drawImageLattice(pixelMap, lattice, dst, drawing.FilterMode.FILTER_MODE_NEAREST); // 示例1
    canvas.drawImageLattice(pixelMap, lattice, dst1, drawing.FilterMode.FILTER_MODE_NEAREST); // 示例2
  }
}

Class (Canvas)

导入模块

Canvas

constructor

drawRect

drawRect20+

drawRoundRect20+

drawNestedRoundRect20+

drawBackground20+

drawShadow20+

drawShadow20+

getLocalClipBounds20+

getTotalMatrix20+

drawCircle

drawImage

drawImageRect20+

drawImageRectWithSrc20+

drawColor

drawColor20+

drawColor20+

drawPixelMapMesh20+

clear20+

clear20+

getWidth20+

getHeight20+

drawOval20+

drawArc20+

drawPoint

drawPoints20+

drawPath

drawLine

drawTextBlob

drawSingleCharacter20+

drawRegion20+

attachPen

attachBrush

detachPen

detachBrush

clipPath20+

clipRect20+

save20+

saveLayer20+

scale20+

skew20+

rotate20+

translate20+

getSaveCount20+

restoreToCount20+

restore20+

concatMatrix20+

setMatrix20+

isClipEmpty20+

clipRegion20+

clipRoundRect20+

resetMatrix20+

quickRejectPath20+

quickRejectRect20+

drawArcWithCenter20+

drawImageNine20+

drawImageLattice20+

drawRect²⁰⁺

drawRoundRect²⁰⁺

drawNestedRoundRect²⁰⁺

drawBackground²⁰⁺

drawShadow²⁰⁺

drawShadow²⁰⁺

getLocalClipBounds²⁰⁺

getTotalMatrix²⁰⁺

drawImageRect²⁰⁺

drawImageRectWithSrc²⁰⁺

drawColor²⁰⁺

drawColor²⁰⁺

drawPixelMapMesh²⁰⁺

clear²⁰⁺

clear²⁰⁺

getWidth²⁰⁺

getHeight²⁰⁺

drawOval²⁰⁺

drawArc²⁰⁺

drawPoints²⁰⁺

drawSingleCharacter²⁰⁺

drawRegion²⁰⁺

clipPath²⁰⁺

clipRect²⁰⁺

save²⁰⁺

saveLayer²⁰⁺

scale²⁰⁺

skew²⁰⁺

rotate²⁰⁺

translate²⁰⁺

getSaveCount²⁰⁺

restoreToCount²⁰⁺

restore²⁰⁺

concatMatrix²⁰⁺

setMatrix²⁰⁺

isClipEmpty²⁰⁺

clipRegion²⁰⁺

clipRoundRect²⁰⁺

resetMatrix²⁰⁺

quickRejectPath²⁰⁺

quickRejectRect²⁰⁺

drawArcWithCenter²⁰⁺

drawImageNine²⁰⁺

drawImageLattice²⁰⁺