await-widget

安装 Skill

本文档与 await-widget Skill 配套，用于借助 AI 编码 Agent 构建 Await 小组件。开始之前，请先安装此 Skill：

npx skills add await-widget/skills

使用时更新

如果此 Skill 是通过 npx skills add 安装的，请在每次调用开始时检查更新。全局安装时，运行 npx skills update await-widget -g；项目安装时，在安装项目的根目录运行 npx skills update await-widget -p。命令完成后，重新阅读已安装的 SKILL.md，并在任务剩余过程中遵循其中的当前说明。

路由

将此 Skill 视为路由层，而非完整参考资料。

将其与用户已安装的 @await-widget/runtime 声明，以及此 Skill 的 docs-source/ 目录中针对具体任务的文档结合使用。请相对于此 SKILL.md 文件解析这些路径，而非相对于用户的工作区。请参阅 docs-source/index.md，找到指南目录，然后只阅读当前任务所需的指南。

docs-source/guides/design.md 涵盖小组件尺寸、布局规则、易读性与内容、动画稳定性和按钮。docs-source/guides/resources.md 涵盖本地 SVG、图像和音频资源。

概览

Await 小组件使用 TSX 语法和 SwiftUI 风格的命名，但它们并不是 React、DOM 或 SwiftUI。语法和命名借鉴自这些技术，但 API 契约完全由 @await-widget/runtime 类型定义。

Await 向 iOS 提供两个回调函数：widgetTimeline() 返回带日期的条目，widget(entry) 返回 iOS 指定条目的视图。iOS 决定何时调用这些函数，并可能为节省电量而拒绝过于频繁的时间线刷新请求。

[1] iOS decides when to update the widget
     │
     ▼ calls
[2] widgetTimeline()
     │
     ▼ returns Entry[]
[3] { entry@09:00, entry@09:01, entry@09:02, ... }
     │
     ▼ iOS specifies entry@09:01, calls
[4] widget(entry)
     │
     ▼ returns the widget view

核心规则

• 所有可用的 API 和类型都定义在 node_modules/@await-widget/runtime/types/*.d.ts 中。请将这些文件视为唯一可信来源。不要使用这些声明之外的任何 API 或功能，包括 HTML DOM、浏览器和 Node API（包括 fetch）、CSS 或 React 风格的钩子和状态。
• TSX 组件从 await 模块导入（例如 import {Text, ZStack} from 'await';）。组件、属性和修饰符的定义位于 node_modules/@await-widget/runtime/types/await.d.ts。
• 桥接 API 是宿主提供的全局变量（Await、AwaitStore、AwaitNetwork、AwaitMusic 等）。请直接使用，不要导入。其签名位于 node_modules/@await-widget/runtime/types/bridge.d.ts。
• 组件属性分为初始化属性和修饰符。修饰符可以在同一组件上重复使用，并且顺序很重要——与 SwiftUI 修饰符一样。当 TSX 元素需要多次使用同一修饰符时，请在属性名称后添加唯一后缀（例如 frame_ 或 frame_1），以避免 TSX 语法错误。
• 保持小组件视图树精简：不要添加不必要的视图、嵌套或时间线条目。iOS 小组件受严格的内存限制。小组件开销大致与 timeline entries * view tree node count 成正比，因此除非小组件必须随时间显示明显不同的状态，否则优先使用单个时间线条目。