Class (Pen)

画笔对象，描述所绘制图形形状的轮廓信息。

说明：

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

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

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

导入模块

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

constructor¹²⁺

constructor()

构造一个新的画笔对象。

系统能力： SystemCapability.Graphics.Drawing

示例：

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

const pen = new drawing.Pen();

constructor¹²⁺

constructor(pen: Pen)

复制构造一个新的画笔对象。

系统能力： SystemCapability.Graphics.Drawing

参数：

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

错误码：

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

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

示例：

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

const pen = new drawing.Pen();
const penColor: common2D.Color = { alpha: 255, red: 0, green: 255, blue: 0 };
pen.setColor(penColor);
pen.setStrokeWidth(10);
const newPen = new drawing.Pen(pen);

setMiterLimit¹²⁺

setMiterLimit(miter: number): void

设置折线尖角长度与线宽的最大比值，当画笔绘制一条折线，并且JoinStyle为MITER_JOIN时，若尖角长度与线宽的比值大于限制值，则该折角使用BEVEL_JOIN绘制。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
miter	number	是	折线尖角长度与线宽的最大比值，负数在绘制时会被视作4.0处理，非负数正常生效，该参数为浮点数。

错误码：

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

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

示例：

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

const pen = new drawing.Pen();
pen.setMiterLimit(5);

getMiterLimit¹²⁺

getMiterLimit(): number

获取折线尖角的限制值。

系统能力： SystemCapability.Graphics.Drawing

返回值：

类型	说明
number	返回折线尖角长度与线宽的最大比值。

示例：

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

const pen = new drawing.Pen();
let miter = pen.getMiterLimit();

setImageFilter¹²⁺

setImageFilter(filter: ImageFilter | null): void

设置画笔的图像滤波器。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
filter	ImageFilter | null	是	图像滤波器，null表示清空画笔的图像滤波器效果。

错误码：

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

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

示例：

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

let colorfilter = drawing.ColorFilter.createSRGBGammaToLinear();
let imgFilter = drawing.ImageFilter.createFromColorFilter(colorfilter);
let pen = new drawing.Pen();
pen.setImageFilter(imgFilter);
pen.setImageFilter(null);

getColorFilter¹²⁺

getColorFilter(): ColorFilter

获取画笔的颜色滤波器。

系统能力： SystemCapability.Graphics.Drawing

返回值：

类型	说明
ColorFilter	返回颜色滤波器。

示例：

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

let pen = new drawing.Pen();
let colorfilter = drawing.ColorFilter.createLumaColorFilter();
pen.setColorFilter(colorfilter);
let filter = pen.getColorFilter();

setColor

setColor(color: common2D.Color) : void

设置画笔的颜色。

系统能力： 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;3.Parameter verification failed.

示例：

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

const color : common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 };
const pen = new drawing.Pen();
pen.setColor(color);

setColor¹²⁺

setColor(alpha: number, red: number, green: number, blue: number): void

设置画笔的颜色。性能优于setColor接口，推荐使用本接口。

系统能力： SystemCapability.Graphics.Drawing

参数：

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

错误码：

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

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

示例：

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

const pen = new drawing.Pen();
pen.setColor(255, 255, 0, 0);

setColor¹⁸⁺

setColor(color: number) : void

设置画笔的颜色。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
color	number	是	16进制ARGB格式的颜色。

示例：

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

const pen = new drawing.Pen();
pen.setColor(0xffff0000);

setColor4f²⁰⁺

setColor4f(color4f: common2D.Color4f, colorSpace: colorSpaceManager.ColorSpaceManager | null): void

设置画笔的颜色以及标准色域，与setColor区别在于可以单独设置色域，适用于需要单独设置色域的场景。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
color4f	common2D.Color4f	是	ARGB格式的颜色，每个颜色通道的值是0.0-1.0之间的浮点数，大于1.0时，取1.0，小于0.0时，取0.0。
colorSpace	colorSpaceManager.ColorSpaceManager | null	是	标准色域对象，null表示使用SRGB色域。

示例：

import { common2D, drawing, colorSpaceManager } from "@kit.ArkGraphics2D";

const pen = new drawing.Pen();
let colorSpace = colorSpaceManager.create(colorSpaceManager.ColorSpace.BT2020_HLG);
let color4f:common2D.Color4f = {alpha:1, red:0.5, green:0.4, blue:0.7};
pen.setColor4f(color4f, colorSpace);

getColor¹²⁺

getColor(): common2D.Color

获取画笔的颜色。

系统能力： SystemCapability.Graphics.Drawing

返回值：

类型	说明
common2D.Color	返回画笔的颜色。

示例：

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

const color : common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 };
const pen = new drawing.Pen();
pen.setColor(color);
let colorGet = pen.getColor();

getColor4f²⁰⁺

getColor4f(): common2D.Color4f

获取画笔的颜色，与getColor的区别在于返回值类型为浮点数，适用于需要浮点数类型的场景。

系统能力： SystemCapability.Graphics.Drawing

返回值：

类型	说明
common2D.Color4f	返回画笔的颜色。

示例：

import { common2D, drawing, colorSpaceManager } from "@kit.ArkGraphics2D";

const pen = new drawing.Pen();
let colorSpace = colorSpaceManager.create(colorSpaceManager.ColorSpace.BT2020_HLG);
let color4f:common2D.Color4f = {alpha:1, red:0.5, green:0.4, blue:0.7};
pen.setColor4f(color4f, colorSpace);
let color = pen.getColor4f();

getHexColor¹⁸⁺

getHexColor(): number

获取画笔的颜色。

系统能力： SystemCapability.Graphics.Drawing

返回值：

类型	说明
number	返回画笔的颜色，以16进制ARGB格式的32位无符号整数表示。

示例：

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

let color : common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 };
let pen = new drawing.Pen();
pen.setColor(color);
let hex_color: number = pen.getHexColor();
console.info('getHexColor: ', hex_color.toString(16));

setStrokeWidth

setStrokeWidth(width: number) : void

设置画笔的线宽。0线宽被视作特殊的极细线宽，在绘制时始终会被绘制为1像素，不随画布的缩放而改变；负数线宽在实际绘制时会被视作0线宽。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
width	number	是	表示线宽，该参数为浮点数。单位为物理像素px。

错误码：

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

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

示例：

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

const pen = new drawing.Pen();
pen.setStrokeWidth(5);

getWidth¹²⁺

getWidth(): number

获取画笔的线宽属性，线宽描述了画笔绘制图形轮廓的宽度。

系统能力： SystemCapability.Graphics.Drawing

返回值：

类型	说明
number	返回画笔的线宽，单位为物理像素px。

示例：

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

const pen = new drawing.Pen();
let width = pen.getWidth();

setAntiAlias

setAntiAlias(aa: boolean) : void

设置画笔是否开启抗锯齿。开启后，可以使得图形的边缘在显示时更平滑。未调用此接口设置时，系统默认关闭抗锯齿。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
aa	boolean	是	表示是否开启抗锯齿。true表示开启，false表示关闭。

错误码：

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

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

示例：

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

const pen = new drawing.Pen();
pen.setAntiAlias(true);

isAntiAlias¹²⁺

isAntiAlias(): boolean

获取画笔是否开启抗锯齿属性。

系统能力： SystemCapability.Graphics.Drawing

返回值：

类型	说明
boolean	返回画笔是否开启抗锯齿属性，true表示开启，false表示关闭。

示例：

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

const pen = new drawing.Pen();
let isAntiAlias = pen.isAntiAlias();

setAlpha

setAlpha(alpha: number) : void

设置画笔的透明度。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
alpha	number	是	用于表示透明度的[0, 255]区间内的整数值，传入浮点类型时向下取整。

错误码：

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

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

示例：

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

const pen = new drawing.Pen();
pen.setAlpha(128);

getAlpha¹²⁺

getAlpha(): number

获取画笔的透明度。

系统能力： SystemCapability.Graphics.Drawing

返回值：

类型	说明
number	返回画笔的透明度，该返回值为0到255之间的整数。

示例：

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

const pen = new drawing.Pen();
let alpha = pen.getAlpha();

setColorFilter

setColorFilter(filter: ColorFilter | null) : void

给画笔添加额外的颜色滤波器。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
filter	ColorFilter | null	是	颜色滤波器。null表示清空颜色滤波器。

错误码：

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

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

示例：

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

const pen = new drawing.Pen();
let colorFilter = drawing.ColorFilter.createLinearToSRGBGamma();
pen.setColorFilter(colorFilter);

setMaskFilter¹²⁺

setMaskFilter(filter: MaskFilter | null): void

给画笔添加额外的蒙版滤镜。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
filter	MaskFilter | null	是	蒙版滤镜。null表示清空蒙版滤镜。

错误码：

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

错误码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});
    let maskFilter = drawing.MaskFilter.createBlurMaskFilter(drawing.BlurType.OUTER, 10);
    pen.setMaskFilter(maskFilter);
  }
}

setPathEffect¹²⁺

setPathEffect(effect: PathEffect | null): void

设置画笔路径效果。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
effect	PathEffect | null	是	路径效果对象。null表示清空路径效果。

错误码：

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

错误码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});
    let pathEffect = drawing.PathEffect.createDashPathEffect([30, 10], 0);
    pen.setPathEffect(pathEffect);
  }
}

setShaderEffect¹²⁺

setShaderEffect(shaderEffect: ShaderEffect | null): void

设置画笔着色器效果。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
shaderEffect	ShaderEffect | null	是	着色器对象。null表示清空着色器效果。

错误码：

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

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

示例：

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

const pen = new drawing.Pen();
let shaderEffect = drawing.ShaderEffect.createLinearGradient({x: 100, y: 100}, {x: 300, y: 300}, [0xFF00FF00, 0xFFFF0000], drawing.TileMode.REPEAT);
pen.setShaderEffect(shaderEffect);

setShadowLayer¹²⁺

setShadowLayer(shadowLayer: ShadowLayer | null): void

设置画笔阴影层效果。当前仅在绘制文字时生效。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
shadowLayer	ShadowLayer | null	是	阴影层对象。null表示清空阴影层效果。

错误码：

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

错误码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 font = new drawing.Font();
    font.setSize(60);
    let textBlob = drawing.TextBlob.makeFromString("hello", font, drawing.TextEncoding.TEXT_ENCODING_UTF8);
    let pen = new drawing.Pen();
    pen.setStrokeWidth(2.0);
    let pen_color : common2D.Color = {alpha: 0xFF, red: 0xFF, green: 0x00, blue: 0x00};
    pen.setColor(pen_color);
    canvas.attachPen(pen);
    canvas.drawTextBlob(textBlob, 100, 100);
    canvas.detachPen();
    let color : common2D.Color = {alpha: 0xFF, red: 0x00, green: 0xFF, blue: 0x00};
    let shadowLayer = drawing.ShadowLayer.create(3, -3, 3, color);
    pen.setShadowLayer(shadowLayer);
    canvas.attachPen(pen);
    canvas.drawTextBlob(textBlob, 100, 200);
    canvas.detachPen();
  }
}

setBlendMode

setBlendMode(mode: BlendMode) : void

设置画笔的混合模式。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
mode	BlendMode	是	颜色的混合模式。

错误码：

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

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

示例：

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

const pen = new drawing.Pen();
pen.setBlendMode(drawing.BlendMode.SRC);

setJoinStyle¹²⁺

setJoinStyle(style: JoinStyle): void

设置画笔绘制转角的样式。未调用此接口设置时，系统默认的转角样式为MITER_JOIN。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
style	JoinStyle	是	折线转角样式。

错误码：

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

错误码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(5);
    pen.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    pen.setJoinStyle(drawing.JoinStyle.ROUND_JOIN);
  }
}

getJoinStyle¹²⁺

getJoinStyle(): JoinStyle

获取画笔绘制转角的样式。

系统能力： SystemCapability.Graphics.Drawing

返回值：

类型	说明
JoinStyle	返回折线转角的样式。

示例：

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});
    pen.setJoinStyle(drawing.JoinStyle.ROUND_JOIN);
    let joinStyle = pen.getJoinStyle();
  }
}

setCapStyle¹²⁺

setCapStyle(style: CapStyle): void

设置画笔的线帽样式。未调用此接口设置时，系统默认的线帽样式为FLAT_CAP。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
style	CapStyle	是	描述画笔的线帽样式。

错误码：

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

错误码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(5);
    pen.setColor({alpha: 255, red: 255, green: 0, blue: 0});
    pen.setCapStyle(drawing.CapStyle.SQUARE_CAP);
  }
}

getCapStyle¹²⁺

getCapStyle(): CapStyle

获取画笔的线帽样式。

系统能力： SystemCapability.Graphics.Drawing

返回值：

类型	说明
CapStyle	返回画笔的线帽样式。

示例：

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});
    pen.setCapStyle(drawing.CapStyle.SQUARE_CAP);
    let capStyle = pen.getCapStyle();
  }
}

setDither

setDither(dither: boolean) : void

开启画笔的抖动绘制效果。抖动绘制可以使得绘制出的颜色更加真实。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
dither	boolean	是	是否开启画笔的抖动绘制效果。true表示开启，false表示关闭。

错误码：

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

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

示例：

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

const pen = new drawing.Pen();
pen.setDither(true);

getFillPath¹²⁺

getFillPath(src: Path, dst: Path): boolean

获取使用画笔绘制的源路径轮廓，并用目标路径表示。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
src	Path	是	源路径对象。
dst	Path	是	目标路径对象。

返回值：

类型	说明
boolean	返回获取源路径轮廓是否成功，true表示成功，false表示失败。

错误码：

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

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

示例：

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

let pen = new drawing.Pen();
let pathSrc: drawing.Path = new drawing.Path();
let pathDst: drawing.Path = new drawing.Path();
pathSrc.moveTo(0, 0);
pathSrc.lineTo(700, 700);
let value = pen.getFillPath(pathSrc, pathDst);

reset¹²⁺

reset(): void

重置当前画笔为初始状态。

系统能力： SystemCapability.Graphics.Drawing

示例：

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

const pen = new drawing.Pen();
pen.reset();