dot-canvas-designer

Dot Canvas 设计器

当用户希望设计或修改 Dot Canvas API 卡片、仪表板、状态面板或 windowData 布局时，使用此技能。

不要仅为了向设备发送现有负载而使用此技能。对于设备操作，请使用 dot-device-openapi。

输出边界

生成 Canvas 负载或 windowData 对象。此处不处理 API 密钥、设备 ID 或发送到设备的操作。

当用户要求设计并发送 Canvas 卡片时：

1. 使用此技能构建 Canvas 负载。
2. 使用 dot-device-openapi 发送负载。

设计工作流

编写布局前，阅读 content-design.md，确定主要事实、实际数据、目标、语言和状态行为。阅读 display-design.md，了解层级、字体排印、图像处理和小屏幕布局。这些决策用于指导公开的 Canvas 负载，不是额外的负载字段。

对于 Read Pico 或 Rand/0 相关请求，请先查阅产品与集成指南。通用设计原则适用于各种设备，但必须单独确认 Canvas 的交付支持情况。

组合模型

将 windowData 构建为 JSON，而不是 JSX、JavaScript、原始 HTML、外部 CSS 或图像。

根结构：

{
  "default": [
    {
      "type": "div",
      "props": {
        "tw": "flex flex-col flex-1 bg-white text-black",
        "children": "Hello Dot."
      }
    }
  ]
}

元素结构：

• type：div、span 或 img
• props：渲染属性
• props.tw：类似 Tailwind 的实用类
• props.style：显式内联样式对象
• props.children：字符串、单个元素对象或元素对象数组

动态值应通过简单的 get 表达式读取 Canvas data，例如 {{get inputData "title" default="-"}}。

支持的模板逻辑

仅使用稳定的显示层辅助函数：

• $for / $empty：列表结构
• $ifAny / $then / $else：结构条件
• if / else：根据值是否有内容进行简短内容分支
• compare：简短文本分支
• formatDate：日期显示
• formatCompactNumber：数字显示
• get：读取 JSON 路径

避免在公开 Canvas 负载中使用 imageSrc、stripHtml、math 或 regexMatch 等内部清理或转换辅助函数。请在构建 JSON 负载前完成数据清理和复杂计算。

布局指南

• 优先使用一个带边界的根容器，并设置 flex、w-full、h-full 以及明确的背景色和文本颜色。
• 使用固定区域和受支持的文本裁剪方式，控制阅读内容量。仅在确实需要收缩、截断或裁剪时添加 min-w-0、min-h-0 或 overflow-hidden；不要添加不会改变预期结果的防御性样式。
• 最外层 Canvas 元素通常不应添加内边距；设备布局的间距由 layoutFull 控制。
• 使用 layoutFull.tw 或 layoutFull.style 设置全出血渲染、背景或内边距覆盖。
• 尽量减少元素数量和嵌套层级。通过清晰的分区进行组合，避免层层嵌套的装饰。

参考资料

• references/content-design.md

• references/display-design.md

• references/windowdata.md

• references/examples.md