ui_canvas

ui_canvas 模块提供画布组件，支持自由绘制直线、矩形、圆弧、曲线等基本图形。

Class Summary

OHOS::UICanvas

画布组件，用于绘制多种 2D 图形

• 构造：无

• 成员函数：

  接口名称	功能简述
  GetViewType	获取视图类型
  Clear	清空画布
  SetStartPosition	设置绘制起点坐标
  GetStartPosition	获取绘制起点坐标
  DrawLine	绘制直线
  DrawCurve	绘制三次贝塞尔曲线
  DrawRect	绘制矩形
  StrokeRect	绘制无填充的矩形路径
  ClearRect	清除矩形区域内的像素
  DrawCircle	绘制圆形
  DrawSector	绘制扇形
  DrawArc	绘制弧线
  DrawImage	绘制图像
  DrawLabel	绘制文本
  BeginPath	创建路径
  MoveTo	移动路径起点
  LineTo	创建直线路径段
  ArcTo	创建弧线路径段
  AddRect	创建矩形路径
  ClosePath	关闭当前路径
  DrawPath	绘制路径
  FillPath	填充路径
  StrokeText	在画布上绘制文本
  MeasureText	测量文本尺寸
  Save	保存画笔状态
  Restore	恢复上一次保存的画笔状态
  OnDraw	执行画布绘制

• 使用包含头文件：#include "components/ui_canvas.h"

• 声明头文件：middleware/services/gui/uikit/ui/interfaces/kits/components/ui_canvas.h
• 公有运算符：无
• 继承关系：UIView
• 嵌套类型：FontStyle、DrawCmd
• 模板形参：无

Functions

OHOS::UICanvas

GetViewType

UIViewType GetViewType() const override

功能说明

• 核心用途：获取当前视图的类型标识
• 返回值固定为 UI_CANVAS，用于区分画布视图与其他 UIView 子类
• 可用于运行时类型判断与视图分发处理

返回值

• 返回类型：UIViewType

返回视图类型标识

返回值	触发场景
UI_CANVAS	当前对象为 UICanvas 类型

Clear

void Clear()

功能说明

• 核心用途：清空画布上所有已绘制的图形指令
• 调用后画布上的绘制内容全部移除，画布回到空白状态
• 清空后自动触发界面刷新

SetStartPosition

void SetStartPosition(const Point& startPoint)

功能说明

• 核心用途：设置后续绘制操作的起点坐标
• 起点坐标影响 DrawLine、DrawCurve 等接口在不指定起点时的默认起始位置
• 每次绘制操作完成后，起点会自动更新为上一个操作的终点

入参

名称	参数类型	详细说明	约束取值范围
startPoint	const Point&	起点坐标，入参只读引用，不修改所指对象	x/y 坐标需在画布有效范围内

GetStartPosition

const Point& GetStartPosition() const

功能说明

• 核心用途：获取当前绘制起点坐标
• 返回值为 const 引用，不修改对象状态
• 返回的坐标为最近一次 SetStartPosition 设置或上一次绘制操作自动更新的终点

返回值

• 返回类型：const Point&

返回当前起点坐标的只读引用

返回值	触发场景
Point&	返回起点坐标引用

DrawLine

void DrawLine(const Point& endPoint, const Paint& paint)

功能说明

• 核心用途：从当前起点到指定终点绘制一条直线
• 若未通过 SetStartPosition 设置起点，则从上一次绘制的终点开始绘制
• 绘制完成后起点自动更新为 endPoint

入参

名称	参数类型	详细说明	约束取值范围
endPoint	const Point&	直线终点坐标，入参只读引用	x/y 坐标需在画布有效范围内
paint	const Paint&	直线样式（线宽、颜色、透明度等），入参只读引用	参考 Paint 类型定义

DrawLine

void DrawLine(const Point& startPoint, const Point& endPoint, const Paint& paint)

功能说明

• 核心用途：从指定起点到指定终点绘制一条直线
• 显式指定起点，不受当前起点坐标影响
• 绘制完成后起点自动更新为 endPoint

入参

名称	参数类型	详细说明	约束取值范围
startPoint	const Point&	直线起点坐标，入参只读引用	x/y 坐标需在画布有效范围内
endPoint	const Point&	直线终点坐标，入参只读引用	x/y 坐标需在画布有效范围内
paint	const Paint&	直线样式（线宽、颜色、透明度等），入参只读引用	参考 Paint 类型定义

DrawCurve

void DrawCurve(const Point& control1, const Point& control2, const Point& endPoint, const Paint& paint)

功能说明

• 核心用途：从当前起点绘制三次贝塞尔曲线到指定终点
• 若未通过 SetStartPosition 设置起点，则从上一次绘制的终点开始绘制
• 曲线线宽上限为 3，不支持设置透明度
• 绘制完成后起点自动更新为 endPoint

入参

名称	参数类型	详细说明	约束取值范围
control1	const Point&	第一个控制点坐标，入参只读引用	x/y 坐标需在画布有效范围内
control2	const Point&	第二个控制点坐标，入参只读引用	x/y 坐标需在画布有效范围内
endPoint	const Point&	曲线终点坐标，入参只读引用	x/y 坐标需在画布有效范围内
paint	const Paint&	曲线样式，入参只读引用	线宽不超过 3；参考 Paint 类型定义

DrawCurve

void DrawCurve(const Point& startPoint, const Point& control1, const Point& control2, const Point& endPoint, const Paint& paint)

功能说明

• 核心用途：从指定起点绘制三次贝塞尔曲线到指定终点
• 显式指定起点，不受当前起点坐标影响
• 曲线线宽上限为 3，不支持设置透明度
• 绘制完成后起点自动更新为 endPoint

入参

名称	参数类型	详细说明	约束取值范围
startPoint	const Point&	曲线起点坐标，入参只读引用	x/y 坐标需在画布有效范围内
control1	const Point&	第一个控制点坐标，入参只读引用	x/y 坐标需在画布有效范围内
control2	const Point&	第二个控制点坐标，入参只读引用	x/y 坐标需在画布有效范围内
endPoint	const Point&	曲线终点坐标，入参只读引用	x/y 坐标需在画布有效范围内
paint	const Paint&	曲线样式，入参只读引用	线宽不超过 3；参考 Paint 类型定义

DrawRect

void DrawRect(const Point& startPoint, int16_t height, int16_t width, const Paint& paint)

功能说明

• 核心用途：绘制矩形，支持填充和描边两种样式
• 矩形位置由左上角起点坐标和宽高确定
• Paint 样式的 STROKE_STYLE 控制描边，FILL_STYLE 控制填充，两者可同时使用

入参

名称	参数类型	详细说明	约束取值范围
startPoint	const Point&	矩形左上角坐标，入参只读引用	x/y 坐标需在画布有效范围内
height	int16_t	矩形高度	大于 0
width	int16_t	矩形宽度	大于 0
paint	const Paint&	矩形样式（填充色、描边色、线宽等），入参只读引用	参考 Paint 类型定义

StrokeRect

void StrokeRect(const Point& startPoint, int16_t height, int16_t width, const Paint& paint)

功能说明

• 核心用途：绘制仅描边无填充的矩形
• 根据 Paint 的 changeFlag 状态决定使用直接描边或路径绘制方式
• 绘制完成后起点自动更新为 startPoint

入参

名称	参数类型	详细说明	约束取值范围
startPoint	const Point&	矩形左上角坐标，入参只读引用	x/y 坐标需在画布有效范围内
height	int16_t	矩形高度	大于 0
width	int16_t	矩形宽度	大于 0
paint	const Paint&	描边样式（描边色、线宽等），入参只读引用	参考 Paint 类型定义

ClearRect

void ClearRect(const Point& startPoint, int16_t height, int16_t width)

功能说明

• 核心用途：清除指定矩形区域内的像素
• 使用画布背景色填充指定矩形区域实现清除效果
• 清除后该区域恢复为背景色

入参

名称	参数类型	详细说明	约束取值范围
startPoint	const Point&	矩形左上角坐标，入参只读引用	x/y 坐标需在画布有效范围内
height	int16_t	矩形高度	大于 0
width	int16_t	矩形宽度	大于 0

DrawCircle

void DrawCircle(const Point& center, uint16_t radius, const Paint& paint)

功能说明

• 核心用途：绘制圆形，支持填充和描边两种样式
• 圆形由圆心坐标和半径确定
• Paint 样式的 FILL_STYLE 控制填充，STROKE_STYLE 控制描边，两者可同时使用

入参

名称	参数类型	详细说明	约束取值范围
center	const Point&	圆心坐标，入参只读引用	x/y 坐标需在画布有效范围内
radius	uint16_t	圆的半径	大于 0，且圆需在画布有效范围内
paint	const Paint&	圆形样式（填充色、描边色、线宽等），入参只读引用	参考 Paint 类型定义

DrawSector

void DrawSector(const Point& center, uint16_t radius, float startAngle, float endAngle, const Paint& paint)

功能说明

• 核心用途：绘制扇形
• 起始角度小于结束角度时顺时针绘制，否则逆时针绘制
• 角度值 0 表示 12 点钟方向，90 表示 3 点钟方向
• 当起始角度与结束角度相等时不绘制

入参

名称	参数类型	详细说明	约束取值范围
center	const Point&	扇形圆心坐标，入参只读引用	x/y 坐标需在画布有效范围内
radius	uint16_t	扇形半径	大于 0
startAngle	float	起始角度，0 表示 12 点钟方向，90 表示 3 点钟方向	合法角度值
endAngle	float	结束角度，0 表示 12 点钟方向，90 表示 3 点钟方向	合法角度值
paint	const Paint&	扇形样式，入参只读引用	参考 Paint 类型定义

DrawArc

void DrawArc(const Point& center, uint16_t radius, float startAngle, float endAngle, const Paint& paint)

功能说明

• 核心用途：绘制弧线，仅支持描边样式
• 起始角度小于结束角度时顺时针绘制，否则逆时针绘制
• 角度值 0 表示 12 点钟方向，90 表示 3 点钟方向
• 当起始角度与结束角度相等时不绘制

入参

名称	参数类型	详细说明	约束取值范围
center	const Point&	弧线圆心坐标，入参只读引用	x/y 坐标需在画布有效范围内
radius	uint16_t	弧线半径	大于 0
startAngle	float	起始角度，0 表示 12 点钟方向，90 表示 3 点钟方向	合法角度值
endAngle	float	结束角度，0 表示 12 点钟方向，90 表示 3 点钟方向	合法角度值
paint	const Paint&	弧线样式（仅描边生效），入参只读引用	参考 Paint 类型定义

DrawImage

void DrawImage(const Point& startPoint, const char* image, const Paint& paint)

功能说明

• 核心用途：在画布指定位置绘制图像，图像源为文件路径字符串
• 仅在 Paint 样式为 FILL_STYLE 时绘制
• 需启用 GRAPHIC_ENABLE_DRAW_IMAGE_FLAG 宏

前置条件

• 需启用宏 GRAPHIC_ENABLE_DRAW_IMAGE_FLAG
• image 指针不为 nullptr 且指向有效的图像资源路径

入参

名称	参数类型	详细说明	约束取值范围
startPoint	const Point&	图像左上角坐标，入参只读引用	x/y 坐标需在画布有效范围内
image	const char*	图像源文件路径，入参指针，不可为 nullptr	指向有效的图像资源路径
paint	const Paint&	图像样式，入参只读引用	需包含 FILL_STYLE；参考 Paint 类型定义

Kconfig 配置

配置项	说明	默认值
GRAPHIC_ENABLE_DRAW_IMAGE_FLAG	启用画布图像绘制功能	需显式启用

DrawImage

void DrawImage(const Point& startPoint, const char* image, const Paint& paint, int16_t width, int16_t height)

功能说明

• 核心用途：在画布指定位置绘制指定宽高的缩放图像，图像源为文件路径字符串
• 根据 width/height 与图像原始尺寸计算缩放比例
• 仅在 Paint 样式为 FILL_STYLE 时绘制
• 需启用 GRAPHIC_ENABLE_DRAW_IMAGE_FLAG 宏

前置条件

• 需启用宏 GRAPHIC_ENABLE_DRAW_IMAGE_FLAG
• image 指针不为 nullptr 且指向有效的图像资源路径

入参

名称	参数类型	详细说明	约束取值范围
startPoint	const Point&	图像左上角坐标，入参只读引用	x/y 坐标需在画布有效范围内
image	const char*	图像源文件路径，入参指针，不可为 nullptr	指向有效的图像资源路径
paint	const Paint&	图像样式，入参只读引用	需包含 FILL_STYLE；参考 Paint 类型定义
width	int16_t	目标绘制宽度，用于计算水平缩放比例	大于 0
height	int16_t	目标绘制高度，用于计算垂直缩放比例	大于 0

Kconfig 配置

配置项	说明	默认值
GRAPHIC_ENABLE_DRAW_IMAGE_FLAG	启用画布图像绘制功能	需显式启用

DrawImage

void DrawImage(const Point& startPoint, ImageInfo* image, const Paint& paint)

功能说明

• 核心用途：在画布指定位置绘制图像，图像源为 ImageInfo 结构体指针
• 仅在 Paint 样式为 FILL_STYLE 时绘制
• 需启用 GRAPHIC_ENABLE_DRAW_IMAGE_FLAG 宏

前置条件

• 需启用宏 GRAPHIC_ENABLE_DRAW_IMAGE_FLAG
• image 指针不为 nullptr 且指向有效的 ImageInfo 数据

入参

名称	参数类型	详细说明	约束取值范围
startPoint	const Point&	图像左上角坐标，入参只读引用	x/y 坐标需在画布有效范围内
image	ImageInfo*	图像信息结构体指针，入参指针，不可为 nullptr	指向有效的 ImageInfo 数据
paint	const Paint&	图像样式，入参只读引用	需包含 FILL_STYLE；参考 Paint 类型定义

Kconfig 配置

配置项	说明	默认值
GRAPHIC_ENABLE_DRAW_IMAGE_FLAG	启用画布图像绘制功能	需显式启用

DrawLabel

void DrawLabel(const Point& startPoint, const char* text, uint16_t maxWidth, const FontStyle& fontStyle, const Paint& paint)

功能说明

• 核心用途：在画布上绘制文本，仅支持填充样式
• 文本超出 maxWidth 时自动截断
• 可设置文本方向、对齐方式、字体大小、字间距和字体名称

前置条件

• text 指针不为 nullptr

入参

名称	参数类型	详细说明	约束取值范围
startPoint	const Point&	文本左上角坐标，入参只读引用	x/y 坐标需在画布有效范围内
text	const char*	文本内容，入参指针，不可为 nullptr	指向有效的文本字符串
maxWidth	uint16_t	文本最大显示宽度，超出则截断	大于 0
fontStyle	const FontStyle&	文本布局与字体样式，入参只读引用	参考 FontStyle 结构体定义
paint	const Paint&	文本样式（填充色、透明度等），入参只读引用	需包含 FILL_STYLE；参考 Paint 类型定义

BeginPath

void BeginPath()

功能说明

• 核心用途：创建一条新的绘制路径
• 路径可用于组合多条线段和弧线，通过 DrawPath 或 FillPath 统一绘制
• 调用后之前的路径若未添加到绘制列表将被销毁
• 支持圆角连接两条线段，不支持 miter 和 bevel 连接方式

MoveTo

void MoveTo(const Point& point)

功能说明

• 核心用途：将路径起点移动到指定坐标
• 若前一个路径命令也是 MoveTo，则覆盖前一个命令
• 需在 BeginPath 之后调用，否则操作无效

入参

名称	参数类型	详细说明	约束取值范围
point	const Point&	移动目标点坐标，入参只读引用	x/y 坐标需在画布有效范围内

LineTo

void LineTo(const Point& point)

功能说明

• 核心用途：从当前路径终点到指定点创建一条直线路径段
• 若路径中无任何命令，则自动将起点设为当前点
• 需在 BeginPath 之后调用，否则操作无效

入参

名称	参数类型	详细说明	约束取值范围
point	const Point&	直线终点坐标，入参只读引用	x/y 坐标需在画布有效范围内

ArcTo

void ArcTo(const Point& center, uint16_t radius, int16_t startAngle, int16_t endAngle)

功能说明

• 核心用途：在路径中创建一段弧线路径
• 若路径中已有命令，弧线起点会与路径终点自动连接
• 角度值 0 表示 12 点钟方向，90 表示 3 点钟方向
• 需在 BeginPath 之后调用，否则操作无效

入参

名称	参数类型	详细说明	约束取值范围
center	const Point&	弧线圆心坐标，入参只读引用	x/y 坐标需在画布有效范围内
radius	uint16_t	弧线半径	大于 0
startAngle	int16_t	起始角度，0 表示 12 点钟方向	合法角度值
endAngle	int16_t	结束角度，0 表示 12 点钟方向	合法角度值

AddRect

void AddRect(const Point& point, int16_t height, int16_t width)

功能说明

• 核心用途：在路径中添加一个矩形路径
• 矩形路径由 MoveTo、LineTo、ClosePath 命令组合构成
• 需在 BeginPath 之后调用，否则操作无效

入参

名称	参数类型	详细说明	约束取值范围
point	const Point&	矩形左上角坐标，入参只读引用	x/y 坐标需在画布有效范围内
height	int16_t	矩形高度	大于 0
width	int16_t	矩形宽度	大于 0

ClosePath

void ClosePath()

功能说明

• 核心用途：关闭当前路径，将路径终点连接回起点
• 路径无命令时调用无效
• 需在 BeginPath 之后调用

DrawPath

void DrawPath(const Paint& paint)

功能说明

• 核心用途：以描边方式绘制当前路径
• 路径无命令时不绘制

前置条件

• 调用时序约束：需先通过 BeginPath、MoveTo、LineTo、ArcTo 等接口构建路径后再调用

入参

名称	参数类型	详细说明	约束取值范围
paint	const Paint&	路径描边样式（线宽、颜色、透明度等），入参只读引用	参考 Paint 类型定义

FillPath

void FillPath(const Paint& paint)

功能说明

• 核心用途：以填充方式绘制当前路径
• 路径无命令时不绘制

前置条件

• 调用时序约束：需先通过 BeginPath、MoveTo、LineTo、ArcTo 等接口构建路径后再调用

入参

名称	参数类型	详细说明	约束取值范围
paint	const Paint&	路径填充样式（填充色、透明度等），入参只读引用	参考 Paint 类型定义

StrokeText

void StrokeText(const char* text, const Point& point, const FontStyle& fontStyle, const Paint& paint)

功能说明

• 核心用途：在画布上绘制文本
• 仅在 Paint 样式为 FILL_STYLE 时绘制
• 需启用 GRAPHIC_ENABLE_DRAW_TEXT_FLAG 宏

前置条件

• 需启用宏 GRAPHIC_ENABLE_DRAW_TEXT_FLAG
• text 指针不为 nullptr

入参

名称	参数类型	详细说明	约束取值范围
text	const char*	文本内容，入参指针，不可为 nullptr	指向有效的文本字符串
point	const Point&	文本绘制位置坐标，入参只读引用	x/y 坐标需在画布有效范围内
fontStyle	const FontStyle&	文本布局与字体样式，入参只读引用	参考 FontStyle 结构体定义
paint	const Paint&	文本样式（填充色、透明度等），入参只读引用	需包含 FILL_STYLE；参考 Paint 类型定义

Kconfig 配置

配置项	说明	默认值
GRAPHIC_ENABLE_DRAW_TEXT_FLAG	启用画布文本绘制功能	需显式启用

MeasureText

Point MeasureText(const char* text, const FontStyle& fontStyle)

功能说明

• 核心用途：测量指定文本在给定字体样式下的像素尺寸
• 返回值中 x 为文本宽度，y 为文本高度
• 可在绘制文本前调用以确定文本占位

入参

名称	参数类型	详细说明	约束取值范围
text	const char*	待测量的文本内容	指向有效的文本字符串
fontStyle	const FontStyle&	文本字体样式，入参只读引用	参考 FontStyle 结构体定义

返回值

• 返回类型：Point

返回文本尺寸，x 为宽度，y 为高度

返回值	触发场景
Point(x>0, y>0)	文本有效且字体配置正确
Point(0, 0)	文本为空或字体配置无效

Save

void Save(Paint paint)

功能说明

• 核心用途：将当前画笔状态压入内部栈中保存
• 保存的画笔状态可通过 Restore 依次恢复
• 支持多次保存，按后进先出顺序恢复

入参

名称	参数类型	详细说明	约束取值范围
paint	Paint	待保存的画笔状态，入参按值传递	参考 Paint 类型定义

Restore

Paint Restore()

功能说明

• 核心用途：从内部栈中弹出并恢复最近一次保存的画笔状态
• 若栈为空则返回默认构造的 Paint 对象
• 按后进先出顺序恢复，每次恢复栈顶元素并弹出

返回值

• 返回类型：Paint

返回恢复的画笔状态

返回值	触发场景
保存的 Paint 对象	栈中存在已保存的画笔状态
默认 Paint 对象	栈为空，无已保存的画笔状态

OnDraw

void OnDraw(BufferInfo& gfxDstBuffer, const Rect& invalidatedArea) override

功能说明

• 核心用途：执行画布绘制，将所有已提交的绘制指令渲染到目标缓冲区
• 按提交顺序依次执行绘制指令列表中的所有命令
• 由 UI 框架在刷新时自动调用，通常不需要外部直接调用

入参

名称	参数类型	详细说明	约束取值范围
gfxDstBuffer	BufferInfo&	目标图形缓冲区，入参引用，由调用方提供	缓冲区已初始化且有效
invalidatedArea	const Rect&	需要重绘的无效区域，入参只读引用	矩形区域需在画布有效范围内

Structures

FontStyle

struct FontStyle {
    UITextLanguageDirect direct;
    UITextLanguageAlignment align;
    UITextLanguageAlignment verticalAlign = TEXT_ALIGNMENT_TOP;
    uint8_t fontSize;
    int16_t letterSpace;
    const char* fontName;
};

成员说明

成员名称	数据类型	描述
direct	UITextLanguageDirect	文本方向
align	UITextLanguageAlignment	文本水平对齐方式
verticalAlign	UITextLanguageAlignment	文本垂直对齐方式，默认值 TEXT_ALIGNMENT_TOP
fontSize	uint8_t	字体大小
letterSpace	int16_t	字间距
fontName	const char*	字体名称

DrawCmd

struct DrawCmd : public HeapBase {
    Paint paint;
    void* param;
    void (*DrawGraphics)(BufferInfo&, void*, const Paint&, const Rect&, const Rect&, const Style&);
    void (*DeleteParam)(void*);
};

成员说明

成员名称	数据类型	描述
paint	Paint	绘制样式
param	void*	绘制参数指针
DrawGraphics	void ()(BufferInfo&, void, const Paint&, const Rect&, const Rect&, const Style&)	绘制图形回调函数指针
DeleteParam	void ()(void)	删除参数回调函数指针