openharmony 鸿蒙 arkts-apis-graphics-drawing-Pen

2026-08-25 浏览 (1)

Class (Pen)

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

说明：

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

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

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

导入模块

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

constructor12+

constructor()

构造一个新的画笔对象。

系统能力： SystemCapability.Graphics.Drawing

示例：

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

const pen = new drawing.Pen();

constructor12+

constructor(pen: Pen)

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

系统能力： SystemCapability.Graphics.Drawing

参数：

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

错误码：

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

错误码ID错误信息
401Parameter 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);

setMiterLimit12+

setMiterLimit(miter: number): void

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

系统能力： SystemCapability.Graphics.Drawing

参数：

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

错误码：

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

错误码ID错误信息
401Parameter 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);

getMiterLimit12+

getMiterLimit(): number

获取折线尖角的限制值。

系统能力： SystemCapability.Graphics.Drawing

返回值：

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

示例：

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

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

setImageFilter12+

setImageFilter(filter: ImageFilter|null): void

设置画笔的图像滤波器。

系统能力： SystemCapability.Graphics.Drawing

参数：

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

错误码：

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

错误码ID错误信息
401Parameter 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);

getColorFilter12+

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

参数：

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

错误码：

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

错误码ID错误信息
401Parameter 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);

setColor12+

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

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

系统能力： SystemCapability.Graphics.Drawing

参数：

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

错误码：

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

错误码ID错误信息
401Parameter 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);

setColor18+

setColor(color: number) : void

设置画笔的颜色。

系统能力： SystemCapability.Graphics.Drawing

参数：

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

示例：

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

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

setColor4f20+

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

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

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名类型必填说明
color4fcommon2D.Color4f是ARGB格式的颜色，每个颜色通道的值是0.0-1.0之间的浮点数，大于1.0时，取1.0，小于0.0时，取0.0。
colorSpacecolorSpaceManager.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);

getColor12+

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();

getColor4f20+

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();

getHexColor18+

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

参数：

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

错误码：

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

错误码ID错误信息
401Parameter 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);

getWidth12+

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

参数：

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

错误码：

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

错误码ID错误信息
401Parameter 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);

isAntiAlias12+

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

参数：

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

错误码：

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

错误码ID错误信息
401Parameter 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);

getAlpha12+

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

参数：

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

错误码：

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

错误码ID错误信息
401Parameter 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);

setMaskFilter12+

setMaskFilter(filter: MaskFilter|null): void

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

系统能力： SystemCapability.Graphics.Drawing

参数：

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

错误码：

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

错误码ID错误信息
401Parameter 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);
  }
}

setPathEffect12+

setPathEffect(effect: PathEffect|null): void

设置画笔路径效果。

系统能力： SystemCapability.Graphics.Drawing

参数：

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

错误码：

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

错误码ID错误信息
401Parameter 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);
  }
}

setShaderEffect12+

setShaderEffect(shaderEffect: ShaderEffect|null): void

设置画笔着色器效果。

系统能力： SystemCapability.Graphics.Drawing

参数：

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

错误码：

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

错误码ID错误信息
401Parameter 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);

setShadowLayer12+

setShadowLayer(shadowLayer: ShadowLayer|null): void

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

系统能力： SystemCapability.Graphics.Drawing

参数：

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

错误码：

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

错误码ID错误信息
401Parameter 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

参数：

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

错误码：

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

错误码ID错误信息
401Parameter 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);

setJoinStyle12+

setJoinStyle(style: JoinStyle): void

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

系统能力： SystemCapability.Graphics.Drawing

参数：

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

错误码：

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

错误码ID错误信息
401Parameter 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);
  }
}

getJoinStyle12+

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();
  }
}

setCapStyle12+

setCapStyle(style: CapStyle): void

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

系统能力： SystemCapability.Graphics.Drawing

参数：

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

错误码：

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

错误码ID错误信息
401Parameter 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);
  }
}

getCapStyle12+

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

参数：

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

错误码：

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

错误码ID错误信息
401Parameter 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);

getFillPath12+

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

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

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名类型必填说明
srcPath是源路径对象。
dstPath是目标路径对象。

返回值：

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

错误码：

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

错误码ID错误信息
401Parameter 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);

reset12+

reset(): void

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

系统能力： SystemCapability.Graphics.Drawing

示例：

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

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

你可能感兴趣的鸿蒙文章

openharmony 鸿蒙 capi-drawing-gpu-context-h

openharmony 鸿蒙 capi-drawing-nativepixelmap-

openharmony 鸿蒙 capi-nativevsync-oh-nativevsync-expectedraterange

openharmony 鸿蒙 capi-drawing-oh-drawing-brush

openharmony 鸿蒙 capi-drawing-oh-drawing-image-info

openharmony 鸿蒙 capi-drawing-text-linetypography-h

openharmony 鸿蒙 capi-oh-nativeimage-oh-nativeimage

openharmony 鸿蒙 capi-drawing-typeface-h

openharmony 鸿蒙 capi-drawing-brush-h

openharmony 鸿蒙 capi-nativewindow

  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 本文链接 https://seaxiang.com/blog/3PCrqFWF