1#  Canvas
2
3提供画布组件，用于自定义绘制图形。
4
5> **说明：**
6>
7>  该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
8
9## 子组件
10
11不支持。
12
13## 接口
14
15### Canvas
16
17Canvas(context?: CanvasRenderingContext2D | DrawingRenderingContext)
18
19**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
20
21**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
22
23**系统能力：** SystemCapability.ArkUI.ArkUI.Full
24
25**参数：**
26
27| 参数名  | 类型    | 必填 | 说明   |
28| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
29| context | [CanvasRenderingContext2D](ts-canvasrenderingcontext2d.md) \| [DrawingRenderingContext<sup>12+</sup>](ts-drawingrenderingcontext.md) | 否   | CanvasRenderingContext2D: 不支持多个Canvas共用一个CanvasRenderingContext2D对象，具体描述见[CanvasRenderingContext2D](ts-canvasrenderingcontext2d.md)对象。DrawingRenderingContext: 不支持多个Canvas共用一个DrawingRenderingContext对象，具体描述见[DrawingRenderingContext](ts-drawingrenderingcontext.md)对象。 |
30
31### Canvas<sup>12+</sup>
32
33Canvas(context: CanvasRenderingContext2D | DrawingRenderingContext, imageAIOptions: ImageAIOptions)
34
35**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
36
37**系统能力：** SystemCapability.ArkUI.ArkUI.Full
38
39**参数：**
40
41| 参数名  | 类型  | 必填 | 说明 |
42| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
43| context | [CanvasRenderingContext2D](ts-canvasrenderingcontext2d.md) \| [DrawingRenderingContext<sup>12+</sup>](ts-drawingrenderingcontext.md) | 是   | CanvasRenderingContext2D: 不支持多个Canvas共用一个CanvasRenderingContext2D对象，具体描述见[CanvasRenderingContext2D](ts-canvasrenderingcontext2d.md)对象。DrawingRenderingContext: 不支持多个Canvas共用一个DrawingRenderingContext对象，具体描述见[DrawingRenderingContext](ts-drawingrenderingcontext.md)对象。 |
44| imageAIOptions  | [ImageAIOptions](ts-image-common.md#imageaioptions) | 是   | 给组件设置一个AI分析选项，通过此项可配置分析类型或绑定一个分析控制器。 |
45
46## 属性
47
48除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性：
49
50### enableAnalyzer<sup>12+</sup>
51
52设置组件支持AI分析，当前支持主体识别、文字识别和对象查找等功能。
53需要搭配[context](ts-canvasrenderingcontext2d.md)中的[StartImageAnalyzer](ts-canvasrenderingcontext2d.md#startimageanalyzer12)和[StopImageAnalyzer](ts-canvasrenderingcontext2d.md#stopimageanalyzer12)一起使用。
54不能和[overlay](ts-universal-attributes-overlay.md#overlay)属性同时使用，两者同时设置时overlay中CustomBuilder属性将失效。该特性依赖设备能力。
55
56**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
57
58**系统能力：** SystemCapability.ArkUI.ArkUI.Full
59
60**参数：**
61
62| 参数名 | 类型    | 必填 | 说明 |
63| ------ | ------- | ---- | ------------------------------------------------------------ |
64| enable  | boolean | 是   | 组件支持AI分析，设置为true时，组件可进行AI分析。<br/>默认值：false |
65
66## 事件
67
68除支持[通用事件](ts-universal-events-click.md)外，还支持如下事件：
69
70### onReady
71
72onReady(event: VoidCallback)
73
74Canvas组件初始化完成时或者Canvas组件发生大小变化时的事件回调。
75
76当该事件被触发时画布被清空，该事件之后Canvas组件宽高确定且可获取，可使用Canvas相关API进行绘制。当Canvas组件仅发生位置变化时，只触发[onAreaChange](ts-universal-component-area-change-event.md#onAreaChange)事件，不触发onReady事件。[onAreaChange](ts-universal-component-area-change-event.md#onAreaChange)事件在onReady事件后触发。
77
78**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
79
80**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
81
82**系统能力：** SystemCapability.ArkUI.ArkUI.Full
83
84**参数：**
85
86| 参数名 | 类型    | 必填 | 说明 |
87| ------ | ------- | ---- | ------------------------------------------------------------ |
88| event  | [VoidCallback](ts-types.md#voidcallback12) | 是   | Canvas组件初始化完成时或者Canvas组件发生大小变化时的事件回调事件。 |
89
90**示例：**
91
92该示例实现了如何在Canvas组件使用CanvasRenderingContext2D中的方法进行绘制。
93
94```ts
95// xxx.ets
96@Entry
97@Component
98struct CanvasExample {
99  private settings: RenderingContextSettings = new RenderingContextSettings(true)
100  private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings)
101
102  build() {
103    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
104      Canvas(this.context)
105        .width('100%')
106        .height('100%')
107        .backgroundColor('#ffff00')
108        .onReady(() => {
109          this.context.fillRect(0, 30, 100, 100)
110        })
111    }
112    .width('100%')
113    .height('100%')
114  }
115}
116```
117  ![zh-cn_image_0000001194032666](figures/zh-cn_image_0000001194032666.png)
118
119
120该示例实现了如何在Canvas组件使用DrawingRenderingContext中的方法进行绘制。
121
122```ts
123// xxx.ets
124@Entry
125@Component
126struct CanvasExample {
127  private context: DrawingRenderingContext = new DrawingRenderingContext()
128
129  build() {
130    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
131      Canvas(this.context)
132        .width('100%')
133        .height('100%')
134        .backgroundColor('#ffff00')
135        .onReady(() => {
136          this.context.canvas.drawCircle(200, 200, 100)
137          this.context.invalidate()
138        })
139    }
140    .width('100%')
141    .height('100%')
142  }
143}
144```
145  ![zh-cn_image_0000001194032666](figures/canvas_drawingRenderingContext.png)