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

2026-08-25 浏览 (1)

Class (Pen)

Defines a pen, which is used to describe the style and color to outline a shape.

NOTE

  • The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version.

  • This module uses the physical pixel unit, px.

  • The module operates under a single-threaded model. The caller needs to manage thread safety and context state transitions.

Modules to Import

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

constructor12+

constructor()

A constructor used to create a Pen object.

System capability: SystemCapability.Graphics.Drawing

Example

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

const pen = new drawing.Pen();

constructor12+

constructor(pen: Pen)

Copies a Pen object to create a new one.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
penPenYesPen object to copy.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

Example

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

Sets the maximum ratio allowed between the sharp corner length of a polyline and its line width. When drawing a polyline with the pen, if JoinStyle is set to MITER_JOIN and this maximum ratio is exceeded, the corner will be displayed as beveled instead of mitered.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
miternumberYesMaximum ratio of the sharp corner length of the polyline to the line width. A negative number is processed as 4.0 during drawing. Non-negative numbers take effect normally. The value is a floating point number.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

Example

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

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

getMiterLimit12+

getMiterLimit(): number

Obtains the maximum ratio allowed between the sharp corner length of a polyline and its line width.

System capability: SystemCapability.Graphics.Drawing

Returns

TypeDescription
numberMaximum ratio obtained.

Example

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

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

setImageFilter12+

setImageFilter(filter: ImageFilter|null): void

Sets an image filter for this pen.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
filterImageFilter |nullYesImage filter. If null is passed in, the image filter effect of the pen will be cleared.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types.

Example

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

Obtains the color filter of this pen.

System capability: SystemCapability.Graphics.Drawing

Returns

TypeDescription
ColorFilterColor filter.

Example

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

Sets a color for this pen.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
colorcommon2D.ColorYesColor in ARGB format. The value of each color channel is an integer ranging from 0 to 255.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed.

Example

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

Sets a color for this pen. This API provides better performance than setColor and is recommended.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
alphanumberYesAlpha channel value of the color in ARGB format. The value is an integer ranging from 0 to 255. Any passed-in floating point number is rounded down.
rednumberYesRed channel value of the color in ARGB format. The value is an integer ranging from 0 to 255. Any passed-in floating point number is rounded down.
greennumberYesGreen channel value of the color in ARGB format. The value is an integer ranging from 0 to 255. Any passed-in floating point number is rounded down.
bluenumberYesBlue channel value of the color in ARGB format. The value is an integer ranging from 0 to 255. Any passed-in floating point number is rounded down.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

Example

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

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

setColor18+

setColor(color: number) : void

Sets a color for this pen.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
colornumberYesColor in hexadecimal ARGB format.

Example

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

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

setColor4f20+

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

Sets the color and standard color gamut for this pen. The difference between this method and setColor is that the color gamut can be set separately.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
color4fcommon2D.Color4fYesColor in the ARGB format. The value of each color channel is a floating point number ranging from 0.0 to 1.0. Values above 1.0 default to 1.0, and values below 0.0 default to 0.0.
colorSpacecolorSpaceManager.ColorSpaceManager |nullYesStandard color gamut object. null indicates SRGB.

Example

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

Obtains the color of this pen.

System capability: SystemCapability.Graphics.Drawing

Returns

TypeDescription
common2D.ColorColor of the pen.

Example

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

Obtains the pen color. The difference between this method and getColor is that this method returns a floating point number.

System capability: SystemCapability.Graphics.Drawing

Returns

TypeDescription
common2D.Color4fColor of the pen.

Example

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

Obtains the color of this pen.

System capability: SystemCapability.Graphics.Drawing

Returns

TypeDescription
numberColor, represented as a 32-bit unsigned integer in hexadecimal ARGB format.

Example

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

Sets the stroke width for this pen. The value 0 is treated as an unusually thin width. During drawing, the width of 0 is always drawn as 1 pixel wide, regardless of any scaling applied to the canvas. Negative values are also regarded as the value 0 during the drawing process.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
widthnumberYesStroke width. The value is a floating point number. If a value less than 1 is passed in, the value 1 is used.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

Example

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

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

getWidth12+

getWidth(): number

Obtains the stroke width of this pen. The width describes the thickness of the outline of a shape.

System capability: SystemCapability.Graphics.Drawing

Returns

TypeDescription
numberStroke width for the pen, in px.

Example

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

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

setAntiAlias

setAntiAlias(aa: boolean) : void

Enables anti-aliasing for this pen. Anti-aliasing makes the edges of the content smoother. If this API is not called, anti-aliasing is disabled by default.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
aabooleanYesWhether to enable anti-aliasing. true to enable, false otherwise.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

Example

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

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

isAntiAlias12+

isAntiAlias(): boolean

Checks whether anti-aliasing is enabled for this pen.

System capability: SystemCapability.Graphics.Drawing

Returns

TypeDescription
booleanCheck result. The value true means that anti-aliasing is enabled, and false means the opposite.

Example

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

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

setAlpha

setAlpha(alpha: number) : void

Sets an alpha value for this pen.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
alphanumberYesAlpha value. The value is an integer in the range [0, 255]. If a floating point number is passed in, the value is rounded down.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed.

Example

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

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

getAlpha12+

getAlpha(): number

Obtains the alpha value of this pen.

System capability: SystemCapability.Graphics.Drawing

Returns

TypeDescription
numberAlpha value of the pen. The return value is an integer ranging from 0 to 255.

Example

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

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

setColorFilter

setColorFilter(filter: ColorFilter|null) : void

Sets a color filter for this pen.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
filterColorFilter |nullYesDefines a color filter. If null is passed in, the color filter is cleared.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

Example

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

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

setMaskFilter12+

setMaskFilter(filter: MaskFilter|null): void

Adds a mask filter for this pen.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
filterMaskFilter |nullYesMask filter. If null is passed in, the mask filter is cleared.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

Example

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

Sets the path effect for this pen.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
effectPathEffect |nullYesImplements a path effect. If null is passed in, the path filter is cleared.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

Example

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

Sets the shader effect for this pen.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
shaderEffectShaderEffect |nullYesShaderEffect object. If null is passed in, the shader effect will be cleared.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

Example

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

Sets a shadow layer for this pen. The shadow layer effect takes effect only when text is drawn.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
shadowLayerShadowLayer |nullYesImplements a shadow layer. If null is passed in, the shadow layer is cleared.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

Example

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

Sets a blend mode for this pen.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
modeBlendModeYesBlend mode.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed.

Example

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

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

setJoinStyle12+

setJoinStyle(style: JoinStyle): void

Sets the join style for this pen. If this API is not called, the default join style is MITER_JOIN.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
styleJoinStyleYesJoin style.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed.

Example

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

Obtains the join style of this pen.

System capability: SystemCapability.Graphics.Drawing

Returns

TypeDescription
JoinStyleJoin style.

Example

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

Sets the cap style for this pen. If this API is not called, the default cap style is FLAT_CAP.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
styleCapStyleYesCap style.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed.

Example

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

Obtains the cap style of this pen.

System capability: SystemCapability.Graphics.Drawing

Returns

TypeDescription
CapStyleCap style.

Example

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

Enables dithering for this pen. Dithering make the drawn color more realistic.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
ditherbooleanYesWhether to enable dithering. true to enable, false otherwise.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

Example

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

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

getFillPath12+

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

Obtains the source path outline drawn using this pen and represents it using a destination path.

System capability: SystemCapability.Graphics.Drawing

Parameters

NameTypeMandatoryDescription
srcPathYesSource path.
dstPathYesDestination path.

Returns

TypeDescription
booleanCheck result. The value true means that the source path outline is obtained, and false means the opposite.

Error codes

For details about the error codes, see Universal Error Codes.

IDError Message
401Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types.

Example

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

Resets this pen to the initial state.

System capability: SystemCapability.Graphics.Drawing

Example

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/lo9S58FD