`canvas.draw()`

一次向宿主绘图面提交一批有序 2D 指令。它是即时绘制接口，不保存场景树，也不返回像素。

Syntax

await host.canvas.draw(canvasId, operations);

Parameters

参数	类型	说明
`canvasId`	`string`	目标绘图面
`operations`	`DrawOperation[]`	按数组顺序执行的有界指令批次

DrawOperation 是模块页定义的封闭联合类型。未知 op、NaN/Infinity、过深状态栈和无效字体句柄必须拒绝。v0.1 不接受图片、URL、路径或文件 token。

目标绘图面在 manifest 中必须是 mode: "draw"。状态栈、transform/clip、路径合法性和固定 source-over 合成语义见模块页；有限但极大的坐标由安全裁剪处理，不能触发实现私有阈值。

Return value

无。整批要么按顺序全部执行，要么以 HostError 整体失败；成功返回时不得丢弃任何指令。

Examples

await host.canvas.draw('main', [
  { op: 'clear', color: { r: 16, g: 20, b: 24, a: 255 } },
  { op: 'fillRect', rect: { x: 20, y: 20, width: 160, height: 80 }, color: { r: 35, g: 134, b: 54, a: 255 } },
  { op: 'fillText', x: 36, y: 66, text: 'Hello', style: { size: 16, align: 'start', direction: 'ltr' }, color: { r: 255, g: 255, b: 255, a: 255 } },
]);

批量提交优于每个矩形调用一次 Host API：

const operations = bars.map((bar) => ({
  op: 'fillRect', rect: { x: bar.x, y: bar.y, width: bar.width, height: bar.height }, color: bar.color,
}));
await host.canvas.draw('chart', operations);

Errors

特有错误：denied、not-found、invalid-operation、resource-denied、limit-exceeded。mode 不匹配属于 invalid-operation；结构非法或超预算必须整体失败。

Requirements

能力：host:canvas.draw
用户激活：不需要
信任档位：green

canvas.draw()