当组件本身的绘制内容不满足需求时,可使用自定义组件绘制功能,在原有组件基础上部分绘制,或者全部自行绘制,以达到预期效果。例如:独特的按钮形状、文字和图像混合的图标等。自定义组件绘制提供了自定义绘制修改器,来实现更自由的组件绘制。
从API version 12开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
本模块接口仅可在Stage模型下使用。
drawModifier(modifier: DrawModifier | undefined): T
设置组件的自定义绘制修改器。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
组件支持范围:
AlphabetIndexer、Badge、Blank、Button、CalendarPicker、Checkbox、CheckboxGroup、Circle、Column、ColumnSplit、Counter、DataPanel、DatePicker、Ellipse、Flex、FlowItem、FolderStack、FormLink、Gauge、Grid、GridCol、GridItem、GridRow、Hyperlink、Image、ImageAnimator、ImageSpan、Line、List、ListItem、ListItemGroup、LoadingProgress、Marquee、Menu、MenuItem、MenuItemGroup、NavDestination、Navigation、Navigator、NavRouter、NodeContainer、Path、PatternLock、Polygon、Polyline、Progress、QRCode、Radio、Rating、Rect、Refresh、RelativeContainer、RichEditor、Row、RowSplit、Scroll、ScrollBar、Search、Select、Shape、SideBarContainer、Slider、Stack、Stepper、StepperItem、Swiper、SymbolGlyph、TabContent、Tabs、Text、TextArea、TextClock、TextInput、TextPicker、TextTimer、TimePicker、Toggle、WaterFlow、XComponent
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| modifier | DrawModifier | undefined | 是 | 自定义绘制修改器,其中定义了自定义绘制的逻辑。 默认值:undefined,未设置自定义绘制修改器时,组件使用原有默认绘制行为,不进行自定义绘制。 说明: 每个自定义绘制修改器只对当前绑定组件的FrameNode生效,对其子节点不生效。每个DrawModifier实例只能设置到一个组件上,禁止重复设置。 |
返回值:
| 类型 | 说明 |
|---|---|
| T | 返回当前组件,用于链式调用。 |
DrawModifier可设置遮罩层(drawOverlay23+)、前景(drawForeground20+)、内容前景(drawFront)、内容(drawContent)和内容背景(drawBehind)的绘制方法,还提供主动触发重绘的方法invalidate。每个DrawModifier实例只能设置到一个组件上,禁止重复设置。
绘制顺序从下到上依次为:内容背景(drawBehind)→ 内容(drawContent)→ 内容前景(drawFront)→ 前景(drawForeground)→ 遮罩层(drawOverlay)。每个层级独立绘制,各层级方法可选实现。
自定义层级示例图

元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
drawFront?(drawContext: DrawContext): void
自定义绘制内容前景的接口,若重载该方法则可进行内容前景的自定义绘制。内容前景位于内容和前景之间,适用于需要在组件内容之上、组件前景之下添加绘制内容的场景。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| drawContext | DrawContext | 是 | 图形绘制上下文,提供canvas(画布对象)和size(绘制区域尺寸)等属性,用于在自定义绘制方法中执行具体的绘制操作。 |
示例:
drawContent?(drawContext: DrawContext): void
自定义绘制内容的接口,若重载该方法则可进行内容的自定义绘制,会替换组件原本的内容绘制函数。适用于需要完全自定义组件内容绘制、不使用组件原本内容绘制逻辑的场景。该接口的DrawContext中的Canvas是用于记录指令的临时Canvas,并非节点的真实Canvas。使用请参见调整自定义绘制Canvas的变换矩阵。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| drawContext | DrawContext | 是 | 图形绘制上下文,提供canvas(画布对象)和size(绘制区域尺寸)等属性,用于在自定义绘制方法中执行具体的绘制操作。 |
示例:
drawBehind?(drawContext: DrawContext): void
自定义绘制内容背景的接口,若重载该方法则可进行内容背景的自定义绘制。背景位于组件内容层之下,适用于需要在组件底层添加装饰性背景元素的场景。该接口的DrawContext中的Canvas是用于记录指令的临时Canvas,并非节点的真实Canvas。使用请参见调整自定义绘制Canvas的变换矩阵。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| drawContext | DrawContext | 是 | 图形绘制上下文,提供canvas(画布对象)和size(绘制区域尺寸)等属性,用于在自定义绘制方法中执行具体的绘制操作。 |
示例:
drawForeground(drawContext: DrawContext): void
自定义绘制前景的接口,若重载该方法则可进行前景的自定义绘制。与drawFront(内容前景)相比,drawForeground位于更高层级,绘制在内容前景之上、遮罩层之下。drawFront适用于绘制组件内容自身的前景效果,drawForeground适用于需要在内容前景之上添加额外前景效果的场景。该接口的DrawContext中的Canvas是用于记录指令的临时Canvas,并非节点的真实Canvas。使用请参见调整自定义绘制Canvas的变换矩阵。
元服务API: 从API version 20开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| drawContext | DrawContext | 是 | 图形绘制上下文,提供canvas(画布对象)和size(绘制区域尺寸)等属性,用于在自定义绘制方法中执行具体的绘制操作。 |
示例:
drawOverlay(drawContext: DrawContext): void
自定义绘制遮罩层的接口,若重载该方法则可进行遮罩层的自定义绘制。遮罩层是最上层的绘制层级,适用于需要在组件最上层添加遮罩效果(如高亮、蒙版等)的场景。该接口的DrawContext中的Canvas是用于记录指令的临时Canvas,并非节点的真实Canvas。使用请参见调整自定义绘制Canvas的变换矩阵。
元服务API: 从API version 23开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| drawContext | DrawContext | 是 | 图形绘制上下文,提供canvas(画布对象)和size(绘制区域尺寸)等属性,用于在自定义绘制方法中执行具体的绘制操作。 |
示例:
// test.ets
import { drawing } from '@kit.ArkGraphics2D';
class MyOverlayDrawModifier extends DrawModifier {
public scaleX: number = 3;
public scaleY: number = 3;
uiContext: UIContext;
constructor(uiContext: UIContext) {
super();
this.uiContext = uiContext;
}
// 重载drawOverlay方法,实现自定义绘制遮罩层
drawOverlay(context: DrawContext): void {
const brush = new drawing.Brush();
brush.setColor({
alpha: 255,
red: 0,
green: 50,
blue: 100
});
context.canvas.attachBrush(brush);
const halfWidth = context.size.width / 2;
const halfHeight = context.size.height / 2;
context.canvas.drawRect({
left: this.uiContext.vp2px(halfWidth - 30 * this.scaleX),
top: this.uiContext.vp2px(halfHeight - 30 * this.scaleY),
right: this.uiContext.vp2px(halfWidth + 30 * this.scaleX),
bottom: this.uiContext.vp2px(halfHeight + 60 * this.scaleY)
});
}
}
@Entry
@Component
struct DrawModifierExample {
// 将自定义绘制遮罩层的类实例化,传入UIContext实例
private overlayModifier: MyOverlayDrawModifier = new MyOverlayDrawModifier(this.getUIContext());
build() {
Column() {
Text('此文本是子节点')
.fontSize(36)
.width('100%')
.height('100%')
.textAlign(TextAlign.Center)
}
.margin(50)
.width(280)
.height(300)
.backgroundColor(0x87CEEB)
// 调用此接口并传入自定义绘制遮罩层的类实例,即可实现自定义绘制遮罩层
.drawModifier(this.overlayModifier)
}
} invalidate(): void
主动触发重绘的接口,开发者无需也无法重载,调用会触发所绑定组件的重绘。当自定义绘制所依赖的属性(如尺寸、颜色、位置等)发生变化时(例如在动画过程中动态更新绘制参数),需要调用该方法使最新的绘制效果生效。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
示例:
type DrawContext = import('../api/arkui/Graphics').DrawContext
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 类型 | 说明 |
|---|---|
| import('../api/arkui/Graphics').DrawContext | 图形绘制上下文,用于执行自定义绘制操作。 |
通过DrawModifier对Text组件进行自定义绘制。
// xxx.ets
import { drawing } from '@kit.ArkGraphics2D';
import { AnimatorResult } from '@kit.ArkUI';
// 继承DrawModifier实现自定义绘制控制器
class MyFullDrawModifier extends DrawModifier {
public scaleX: number = 1;
public scaleY: number = 1;
uiContext: UIContext;
constructor(uiContext: UIContext) {
super();
this.uiContext = uiContext;
}
// 重载drawBehind方法,自定义绘制背景
drawBehind(context: DrawContext): void {
const brush = new drawing.Brush();
brush.setColor({
alpha: 255,
red: 255,
green: 0,
blue: 0
});
context.canvas.attachBrush(brush);
const halfWidth = context.size.width / 2;
const halfHeight = context.size.height / 2;
context.canvas.drawRect({
left: this.uiContext.vp2px(halfWidth - 50 * this.scaleX),
top: this.uiContext.vp2px(halfHeight - 50 * this.scaleY),
right: this.uiContext.vp2px(halfWidth + 50 * this.scaleX),
bottom: this.uiContext.vp2px(halfHeight + 50 * this.scaleY)
});
}
// 重载drawContent方法,自定义绘制内容
drawContent(context: DrawContext): void {
const brush = new drawing.Brush();
brush.setColor({
alpha: 255,
red: 0,
green: 255,
blue: 0
});
context.canvas.attachBrush(brush);
const halfWidth = context.size.width / 2;
const halfHeight = context.size.height / 2;
context.canvas.drawRect({
left: this.uiContext.vp2px(halfWidth - 30 * this.scaleX),
top: this.uiContext.vp2px(halfHeight - 30 * this.scaleY),
right: this.uiContext.vp2px(halfWidth + 30 * this.scaleX),
bottom: this.uiContext.vp2px(halfHeight + 30 * this.scaleY)
});
}
// 重载drawFront方法,自定义绘制内容前景
drawFront(context: DrawContext): void {
const brush = new drawing.Brush();
brush.setColor({
alpha: 255,
red: 0,
green: 0,
blue: 255
});
context.canvas.attachBrush(brush);
const halfWidth = context.size.width / 2;
const halfHeight = context.size.height / 2;
const radiusScale = (this.scaleX + this.scaleY) / 2;
context.canvas.drawCircle(this.uiContext.vp2px(halfWidth), this.uiContext.vp2px(halfHeight),
this.uiContext.vp2px(20 * radiusScale));
}
}
// 继承DrawModifier实现自定义绘制控制器,仅支持自定义绘制内容前景
class MyFrontDrawModifier extends DrawModifier {
public scaleX: number = 1;
public scaleY: number = 1;
uiContext: UIContext;
constructor(uiContext: UIContext) {
super();
this.uiContext = uiContext;
}
drawFront(context: DrawContext): void {
const brush = new drawing.Brush();
brush.setColor({
alpha: 255,
red: 0,
green: 0,
blue: 255
});
context.canvas.attachBrush(brush);
const halfWidth = context.size.width / 2;
const halfHeight = context.size.height / 2;
const radiusScale = (this.scaleX + this.scaleY) / 2;
context.canvas.drawCircle(this.uiContext.vp2px(halfWidth), this.uiContext.vp2px(halfHeight),
this.uiContext.vp2px(20 * radiusScale));
}
}
@Entry
@Component
struct DrawModifierExample {
private fullModifier: MyFullDrawModifier = new MyFullDrawModifier(this.getUIContext());
private frontModifier: MyFrontDrawModifier = new MyFrontDrawModifier(this.getUIContext());
private drawAnimator: AnimatorResult | undefined = undefined;
@State modifier: DrawModifier = new MyFrontDrawModifier(this.getUIContext());
private count = 0;
// 创建Animator对象并设置动画
create() {
let self = this;
this.drawAnimator = this.getUIContext().createAnimator({
duration: 1000,
easing: 'ease',
delay: 0,
fill: 'forwards',
direction: 'normal',
iterations: 1,
begin: 0,
end: 2
});
// 设置帧回调,动态更新缩放值并触发重绘
this.drawAnimator.onFrame = (value: number) => {
console.info('frame value =', value);
const tempModifier = self.modifier as MyFullDrawModifier | MyFrontDrawModifier;
tempModifier.scaleX = Math.abs(value - 1);
tempModifier.scaleY = Math.abs(value - 1);
// 主动触发重绘
self.modifier.invalidate();
};
}
build() {
Column() {
Row() {
Text('test text')
.width(100)
.height(100)
.margin(10)
.backgroundColor(Color.Gray)
.onClick(() => {
const tempModifier = this.modifier as MyFullDrawModifier | MyFrontDrawModifier;
tempModifier.scaleX -= 0.1;
tempModifier.scaleY -= 0.1;
})
.drawModifier(this.modifier)
}
Row() {
Button('create')
.width(100)
.height(100)
.borderRadius(50)
.margin(10)
.onClick(() => {
this.create();
})
Button('play')
.width(100)
.height(100)
.borderRadius(50)
.margin(10)
.onClick(() => {
if (this.drawAnimator) {
this.drawAnimator.play();
}
})
Button('changeModifier')
.width(100)
.height(100)
.borderRadius(50)
.margin(10)
.onClick(() => {
this.count += 1;
if (this.count % 2 === 1) {
console.info('change to full modifier');
this.modifier = this.fullModifier;
} else {
console.info('change to front modifier');
this.modifier = this.frontModifier;
}
})
}
}
.width('100%')
.height('100%')
}
} 
通过DrawModifier对Column容器的前景进行自定义绘制。
// xxx.ets
import { drawing } from '@kit.ArkGraphics2D';
class MyForegroundDrawModifier extends DrawModifier {
public scaleX: number = 3;
public scaleY: number = 3;
uiContext: UIContext;
constructor(uiContext: UIContext) {
super();
this.uiContext = uiContext;
}
// 重载drawForeground方法,实现自定义绘制前景
drawForeground(context: DrawContext): void {
const brush = new drawing.Brush();
brush.setColor({
alpha: 255,
red: 0,
green: 50,
blue: 100
});
context.canvas.attachBrush(brush);
const halfWidth = context.size.width / 2;
const halfHeight = context.size.height / 2;
context.canvas.drawRect({
left: this.uiContext.vp2px(halfWidth - 30 * this.scaleX),
top: this.uiContext.vp2px(halfHeight - 30 * this.scaleY),
right: this.uiContext.vp2px(halfWidth + 30 * this.scaleX),
bottom: this.uiContext.vp2px(halfHeight + 30 * this.scaleY)
});
}
}
@Entry
@Component
struct DrawModifierExample {
// 将自定义绘制前景的类实例化,传入UIContext实例
private foregroundModifier: MyForegroundDrawModifier = new MyForegroundDrawModifier(this.getUIContext());
build() {
Column() {
Text('此文本是子节点')
.fontSize(36)
.width('100%')
.height('100%')
.textAlign(TextAlign.Center)
}
.margin(50)
.width(280)
.height(300)
.backgroundColor(0x87CEEB)
// 调用此接口并传入自定义绘制前景的类实例,即可实现自定义绘制前景
.drawModifier(this.foregroundModifier)
}
} 