输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心

HarmonyOS

输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
API参考
高级筛选
API version全部版本
设备全部
元服务API集不筛选
您当前正在浏览HarmonyOS最新文档，覆盖已发布的所有API版本，可在API参考中筛选您使用的API版本。详细的版本配套关系请参考版本说明。
API参考应用框架ArkUI（方舟UI框架）ArkTS组件画布绘制Canvas

Canvas

更新时间: 2026-07-28 11:23
本文导读
展开章节

提供画布组件，用于自定义绘制图形。

说明

该组件从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

子组件

PhonePC/2in1TabletTVWearable

不支持。

接口

PhonePC/2in1TabletTVWearable

Canvas23+

PhonePC/2in1TabletTVWearable

Canvas(params: CanvasParams)

使用CanvasParams创建不缓存指令的Canvas组件。创建Canvas组件时，最大面积不超过10000px*10000px，超过最大面积则无法正常创建。Canvas组件未设置固定尺寸时，默认扩展至其最大可用尺寸。

说明

  • 使用本接口创建的Canvas组件将在onReady23+回调的入参中返回一个DrawingRenderingContext12+对象，可用于在该Canvas组件上进行绘制。

  • 使用本接口创建的Canvas组件在组件不可见时将不响应绘制指令。

  • 不可见场景主要包括组件所在的页面进入后台、组件滑到窗口外、设置visibility属性为隐藏等，不包括组件被其他组件或是其他窗口遮挡导致不可见的场景。

元服务API： 从API version 23开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

模型约束： 此接口仅可在Stage模型下使用。

参数：

展开
参数名 类型 必填 说明
params CanvasParams 是 Canvas组件的构造参数，用于创建不缓存指令的Canvas组件。配置参数详见CanvasParams。

Canvas

PhonePC/2in1TabletTVWearable

Canvas(context?: CanvasRenderingContext2D | DrawingRenderingContext)

创建Canvas组件时，最大面积不超过10000px*10000px，超过最大面积则无法正常创建。

使用本接口创建的Canvas组件在组件不可见时将不响应绘制指令。不可见场景主要包括组件所在的页面进入后台、组件滑到窗口外、设置visibility属性为隐藏等，不包括组件被其他组件或是其他窗口遮挡导致不可见的场景。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
context CanvasRenderingContext2D | DrawingRenderingContext12+ 否

CanvasRenderingContext2D: 不支持多个Canvas共用一个CanvasRenderingContext2D对象，具体描述见CanvasRenderingContext2D对象。DrawingRenderingContext: 不支持多个Canvas共用一个DrawingRenderingContext对象，具体描述见DrawingRenderingContext对象。

异常值null和undefined按未设置context处理。

Canvas12+

PhonePC/2in1TabletTVWearable

Canvas(context: CanvasRenderingContext2D | DrawingRenderingContext, imageAIOptions: ImageAIOptions)

创建Canvas组件时，最大面积不超过10000px*10000px，超过最大面积则无法正常创建。支持设置CanvasRenderingContext2D对象或DrawingRenderingContext对象，支持设置AI分析选项。

使用本接口创建的Canvas组件在组件不可见时将不响应绘制指令。不可见场景主要包括组件所在的页面进入后台、组件滑到窗口外、设置visibility属性为隐藏等，不包括组件被其他组件或是其他窗口遮挡导致不可见的场景。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
context CanvasRenderingContext2D | DrawingRenderingContext12+ 是

CanvasRenderingContext2D: 不支持多个Canvas共用一个CanvasRenderingContext2D对象，具体描述见CanvasRenderingContext2D对象。DrawingRenderingContext: 不支持多个Canvas共用一个DrawingRenderingContext对象，具体描述见DrawingRenderingContext对象。

异常值null和undefined按未设置context处理。
imageAIOptions ImageAIOptions 是

给组件设置一个AI分析选项，通过此项可配置分析类型或绑定一个分析控制器。

异常值null和undefined按ImageAIOptions的默认值处理，默认取值为{ type: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT], aiController: new ImageAnalyzerController() }，即开启主体识别和文字识别功能。

CanvasParams23+

PhonePC/2in1TabletTVWearable

定义Canvas的具体配置参数。

元服务API： 从API version 23开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

模型约束： 此接口仅可在Stage模型下使用。

展开
名称 类型 只读 可选 说明
unit LengthMetricsUnit 否 是

用于描述Canvas绘制时所采用的单位模式，不同单位模式会影响绘制时的坐标和尺寸计算方式，具体说明见LengthMetricsUnit。

仅可在创建Canvas时设置，后续不可修改。

默认值：LengthMetricsUnit.DEFAULT
imageAIOptions ImageAIOptions 否 是

给组件设置一个AI分析选项，通过此项可配置分析类型或绑定一个分析控制器。

异常值null和undefined按不开启AI分析功能处理。

默认值：不开启AI分析功能。

属性

PhonePC/2in1TabletTVWearable

除支持通用属性外，还支持以下属性：

enableAnalyzer12+

PhonePC/2in1TabletTVWearable

enableAnalyzer(enable: boolean)

设置组件支持AI分析，当前支持主体识别、文字识别和对象查找等功能，支持attributeModifier动态设置属性方法。

需要搭配CanvasRenderingContext2D中的startImageAnalyzer和stopImageAnalyzer一起使用。

不能和overlay属性同时使用，两者同时设置时overlay中CustomBuilder属性将失效。该特性依赖设备能力，可通过ImageAnalyzerController.getImageAnalyzerSupportTypes接口查询设备支持的分析类型。

说明

从API version 20开始，该接口支持在attributeModifier中调用。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
enable boolean 是

设置组件是否开启AI分析功能，开启时需要组件内容支持主体识别、文字识别或对象查找。

设置为true时，组件可进行AI分析，设置为false时，组件不可进行AI分析。

异常值null和undefined按false处理。

默认值：false

事件

PhonePC/2in1TabletTVWearable

除支持通用事件外，还支持如下事件：

onReady

PhonePC/2in1TabletTVWearable

onReady(event: VoidCallback)

Canvas组件初始化完成或者发生大小变化时的事件回调，支持attributeModifier动态设置属性方法。

当该事件被触发时画布被清空，该事件之后Canvas组件宽高确定且可获取，可使用Canvas相关API进行绘制。当Canvas组件仅发生位置变化时，只触发onAreaChange事件，不触发onReady事件。onAreaChange事件在onReady事件后触发。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
event VoidCallback 是 Canvas组件初始化完成或者发生大小变化时的回调事件。

onReady23+

PhonePC/2in1TabletTVWearable

onReady(event: Callback<DrawingRenderingContext | undefined> | undefined)

Canvas组件初始化完成或者发生大小变化时的事件回调，支持attributeModifier动态设置属性方法。

当该事件被触发时画布被清空，该事件之后Canvas组件宽高确定且可获取，可使用Canvas相关API进行绘制。当Canvas组件仅发生位置变化时，只触发onAreaChange事件，不触发onReady事件。onAreaChange事件在onReady事件后触发。

卡片能力： 从API version 23开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 23开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

模型约束： 此接口仅可在Stage模型下使用。

参数：

展开
参数名 类型 必填 说明
event Callback<DrawingRenderingContext | undefined> | undefined 是

Canvas组件初始化完成或者发生大小变化时的回调事件。

关于Callback<DrawingRenderingContext |undefined>类型的入参：

1. 只有使用CanvasParams创建的Canvas组件在该回调中返回DrawingRenderingContext对象，否则返回undefined。

2. 该回调返回的DrawingRenderingContext对象不允许作为参数创建Canvas组件，否则会导致应用崩溃。

示例

PhonePC/2in1TabletTVWearable

示例1（使用CanvasRenderingContext2D中的方法）

该示例实现了如何在Canvas组件使用CanvasRenderingContext2D中的方法进行绘制。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct CanvasExample {
  5.   private settings: RenderingContextSettings = new RenderingContextSettings(true);
  6.   private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings);
  7. 

  8.   build() {
  9.     Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
  10.       Canvas(this.context)
  11.         .width('100%')
  12.         .height('100%')
  13.         .backgroundColor('#ffff00')
  14.         .onReady(() => {
  15.           this.context.fillRect(0, 30, 100, 100)
  16.         })
  17.     }
  18.     .width('100%')
  19.     .height('100%')
  20.   }
  21. }

示例2（使用DrawingRenderingContext中的方法）

该示例实现了如何在Canvas组件使用DrawingRenderingContext中的方法进行绘制。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct CanvasExample {
  5.   private context: DrawingRenderingContext = new DrawingRenderingContext();
  6. 

  7.   build() {
  8.     Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
  9.       Canvas(this.context)
  10.         .width('100%')
  11.         .height('100%')
  12.         .backgroundColor('rgb(213,213,213)')
  13.         .onReady(() => {
  14.           this.context.canvas.drawCircle(200, 200, 100)
  15.           this.context.invalidate()
  16.         })
  17.     }
  18.     .width('100%')
  19.     .height('100%')
  20.   }
  21. }

示例3（使用attributeModifier动态设置Canvas组件的属性及方法）

该示例展示了如何使用attributeModifier动态设置Canvas组件的enableAnalyzer属性和onReady方法。

说明

此示例的资源不在src > main > resource目录下，从DevEco Studio 6.0.0 Beta2版本开始，新建工程或模块时，默认创建的模块不会对非resources目录下的资源进行打包，需启用相关开关：模块的build-profile.json5中buildOption > resOptions > copyCodeResource > enable设置为true，详见resOptions中copyCodeResource相关介绍。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. 

  4. class MyCanvasModifier implements AttributeModifier<CanvasAttribute> {
  5.   context: CanvasRenderingContext2D = new CanvasRenderingContext2D()
  6. 

  7.   applyNormalAttribute(instance: CanvasAttribute): void {
  8.     // 从（0，0）绘制一张宽高为200vp的图片
  9.     instance.onReady(() => {
  10.       // "common/img.png"需要替换为开发者所需的图像资源文件
  11.       let image = new ImageBitmap("common/img.png")
  12.       this.context.drawImage(image, 0, 0, 200, 200)
  13.     })
  14.     // 设置开启组件AI分析功能，点击start按钮调用startImageAnalyzer方法启动AI分析
  15.     instance.enableAnalyzer(true)
  16.   }
  17. }
  18. 

  19. @Entry
  20. @Component
  21. struct attributeDemo {
  22.   @State modifier: MyCanvasModifier = new MyCanvasModifier()
  23.   private settings: RenderingContextSettings = new RenderingContextSettings(true)
  24.   private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings)
  25.   private config: ImageAnalyzerConfig = {
  26.     types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT]
  27.   }
  28.   private aiController: ImageAnalyzerController = new ImageAnalyzerController()
  29.   private options: ImageAIOptions = {
  30.     types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT],
  31.     aiController: this.aiController
  32.   }
  33. 

  34.   build() {
  35.     Row() {
  36.       Column() {
  37.         Button('start')
  38.           .width(100)
  39.           .height(50)
  40.           .margin(5)
  41.           .onClick(() => {
  42.             this.context.startImageAnalyzer(this.config)
  43.               .then(() => {
  44.                 console.info("analysis complete")
  45.               })
  46.               .catch((error: BusinessError) => {
  47.                 console.error(`Error code: ${error.code}, message: ${error.message}`)
  48.               })
  49.           })
  50.         Button('stop')
  51.           .width(100)
  52.           .height(50)
  53.           .margin(5)
  54.           .onClick(() => {
  55.             this.context.stopImageAnalyzer()
  56.           })
  57.         Button('getTypes')
  58.           .width(100)
  59.           .height(50)
  60.           .margin(5)
  61.           .onClick(() => {
  62.             this.aiController.getImageAnalyzerSupportTypes()
  63.           })
  64.         Canvas(this.context, this.options)
  65.           .borderWidth(1)
  66.           .height(200)
  67.           .width(200)
  68.           .attributeModifier(this.modifier)
  69.           .onAppear(() => {
  70.             this.modifier.context = this.context
  71.           })
  72.       }
  73.     }
  74.   }
  75. }

示例4（创建不缓存指令Canvas并进行绘制）

该示例介绍了如何使用CanvasParams创建不缓存指令的Canvas组件并进行绘制。

从API version 23开始，新增CanvasParams接口。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. import { LengthMetricsUnit } from '@kit.ArkUI';
  3. import { drawing } from '@kit.ArkGraphics2D';
  4. 

  5. @Entry
  6. @Component
  7. struct CanvasExample {
  8.   build() {
  9.     Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
  10.       Canvas({ unit: LengthMetricsUnit.DEFAULT })
  11.         .onReady((drawingContext?: DrawingRenderingContext) => {
  12.           if (!drawingContext) {
  13.             return
  14.           }
  15.           // 使用DrawingRenderingContext进行绘制。
  16.           let brush = new drawing.Brush()
  17.           brush.setColor({
  18.             alpha: 255,
  19.             red: 39,
  20.             green: 135,
  21.             blue: 217
  22.           })
  23.           drawingContext.canvas.attachBrush(brush)
  24.           drawingContext.canvas.drawCircle(200, 200, 100)
  25.           drawingContext.invalidate()
  26. 

  27.           // 使用CanvasRenderingContext2D进行绘制。
  28.           let context2D: CanvasRenderingContext2D =
  29.             CanvasRenderingContext2D.getContext2DFromDrawingContext(drawingContext, { antialias: true })
  30.           context2D.fillStyle = 'rgb(39,135,217)'
  31.           context2D.fillRect(110, 30, 100, 100)
  32.         })
  33.     }
  34.     .width('100%')
  35.     .height('100%')
  36.   }
  37. }

画布绘制
CanvasGradient
相关推荐
文档OffscreenCanvas
文档canvas组件
文档Canvas对象
文档CanvasRenderingContext2D
文档使用画布绘制自定义图形 (Canvas)
文档canvas
文档DrawingRenderingContext
文档Class (Canvas)
文档Path
文档画布
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明
在 API参考 中进行搜索
请输入您想要搜索的关键词