为嵌入式设备UI的智能体开发推出Canvas2D编码技能
内容提要
Qt 6.12 推出 Canvas2D，其 API 类似 HTML5 canvas 但不完全兼容，AI 代理常误用不存在的功能导致运行时错误。Qt 为此发布 Canvas2D 编码技能，提供权威 API 参考和规则，涵盖项目设置、GPU 绘制模型、path2d 缓存及不可用功能的替代方案。该技能包含 19 个可运行示例，从静态图形到示波器、仪表盘等，并已在多款 AI 工具中测试，可通过 Qt 代理技能 GitHub 仓库获取。
延伸解读
AI 代理误用 Canvas2D 的典型陷阱
由于 Canvas2D 的 API 与 HTML5 canvas 相似但不完全兼容，AI 代理常误用不存在的功能，如裁剪任意形状、绘制虚线、读取像素颜色或添加柔和阴影。这些错误在编译时可能通过，但运行时会出现黑块或镜像错误。该技能通过提供权威 API 参考和规则，帮助代理避免这些陷阱，确保绘制正确。
技能的核心能力与实用价值
该技能提供准确的 API 基础、正确的默认值设置、通过 path2d 实现性能优化、移植指导以及 19 个可运行示例。它覆盖从静态图形到仪表盘、示波器等常见场景，每个示例演示不同的规则组合。开发者可基于最接近的示例进行适配，避免从零开始，同时学习最佳实践。
技能的范围与协作建议
该技能严格限定于 canvas 项本身，包括 onPaint 函数、绘制调用和 canvas 级属性，不涉及周围的 QML 组件结构、导入或属性绑定。当任务涉及 canvas 之外的 QML 时，建议同时调用 qt-qml 编码技能。这种分工确保代理在正确范围内工作，避免越界错误。
兼容性与获取方式
该技能已在多种 AI 工具中测试，包括 Claude Code CLI、GitHub Copilot 和 Qwen Code。它可通过 Qt 代理技能 GitHub 仓库或 Claude qt-development 插件获取，与其他 Qt 特定代理能力一同提供。这为嵌入式设备 UI 开发提供了跨工具的标准化支持。
Q&A
Qt Canvas2D 和 HTML5 canvas 有什么区别？为什么 AI 代理容易出错？
Qt Canvas2D 的 API 类似 HTML5 canvas，但并非 100% 兼容。AI 代理因熟悉 HTML5 canvas，会误用 Canvas2D 中不存在的功能，如裁剪任意形状、绘制虚线、读取像素颜色、添加柔和阴影等，导致编译通过但运行时出错。
Canvas2D 编码技能主要包含哪些功能？
该技能提供权威 API 参考和规则，涵盖项目设置、GPU 绘制模型、save/restore 规范、path2d 缓存性能优化，以及不可用功能的替代方案。还包含 19 个可运行示例，从静态图形到示波器、仪表盘等。
Canvas2D 编码技能如何帮助提升性能？
通过 path2d 缓存，将持久几何图形缓存在 GPU 端的路径组中，并通过变换实例化，而不是每帧重建，从而提升性能。
这个技能提供了哪些可运行的示例？
技能包含 19 个可运行示例，如 static-shapes.qml、animated-line-chart.qml、bar-chart.qml、pie-donut-chart.qml、scatter-plot.qml、radial-gauge.qml、progress-ring.qml、analog-clock.qml、oscilloscope.qml 等，覆盖从静态图形到仪表盘、示波器等多种场景。
这个技能是否覆盖 QML 组件结构或窗口设置？
不覆盖。该技能严格限定于 canvas 项本身：onPaint 函数、绘图调用和 canvas 级属性。不涉及周围的 QML 组件结构、导入、属性绑定或 Window/ApplicationWindow 设置。对于这些，建议同时调用 qt-qml 编码技能。
如何获取 Canvas2D 编码技能？
可通过 Qt 代理技能 GitHub 仓库（github.com/TheQtCompanyRnD/agent-skills）或 Claude qt-development 插件获取，同时还有 QML 编码技能、QML 分析器技能等其他 Qt 专用代理能力。
