widget API 地图
按任务/场景索引 Widget API；含 symbol 链式 color 等易错点。
发布流程见 从脚本到桌面；完整签名见 widget API 参考。
按任务和场景组织 widget 公开 API。需要确认参数名、返回值或修饰符链时，再查 API 参考。
边界：本页是索引，不展开教程。入门见 widget 概览；故障见 排错。
#本篇目标
#最小入口
可运行基线脚本见 排错 · 最小健康基线（全系列唯一基线，避免各篇重复）。本页只做 API 路由，不另附 runnable 示例。
#先看哪一类
| 你要做什么 | 先看 | 专题 |
|---|---|---|
| 从零写第一个小组件 | Widget()、text()、render() | 概览 |
| 发布到主屏 | Studio 发布流程 | 从脚本到桌面 |
| 预览里调配色/标题 | widget.param.* | 参数面板 |
| 桌面按钮/开关 | widget.state、button()、toggle() | 状态和交互 |
| small/medium/large 适配 | widget.context、family_value()、when() | 布局与尺寸 |
| 数字动画 / 定时刷新 | timeline()、widget.entry、flip() | 时间线和动画 |
| 深色/透明/图片/Symbol | container_background、symbol()、image() | 资源与外观 |
| 预览空白 / 桌面不对 | 基线排查、validate() | 排错 |
#按任务选 API
| 任务 | 首选 API | 注意 |
|---|---|---|
| 创建根容器 | Widget(background=, padding=, style=) | 脚本里只有一个 Widget() |
| 提交渲染 | w.render() | 必须在脚本末尾 |
| 布局诊断 | w.validate(family=) | Studio「Widget 诊断」对应此报告 |
| 流式横/纵排 | row()、column()、layer() | 必须用 with w.row(): 上下文 |
| 等列网格 | grid(columns=) | 子节点按顺序填格 |
| 表格线 / Bingo | table(rows, columns) + table.cell() | 勿用 rect 拼线 |
| 点坐标绘制 | canvas()、.place() | 读 content_width / content_height |
| 标题与数值 | text()、value()、title()、caption() | 可变文案加 line_limit + min_scale |
| SF Symbol | symbol(name) → .color() .font_size() | symbol 无 color=/size= 参数 |
| 图片 / SVG | image()、svg() | 支持 light/dark 双资源 |
| 进度与图表 | progress()、ring_chart()、line_chart()、bar_chart() | small 注意高度预算 |
| 可调配置 | widget.param.text/color/number/slider/bool/choice/file | 不是桌面 state |
| 桌面状态 | widget.state.int/bool/list/... | .increment()、.toggle()、.toggle_item() |
| 按钮/开关/链接 | button()、toggle()、link() | action 必须来自 state 工厂；link(..., icon=) 不可链 .line_limit() |
| 时间线 | w.timeline(entries=, update=) | entry 字段用 widget.entry.* |
| 数据动画 | .content_transition("numericText")、.id()、flip() | 非 60fps 循环 |
| 系统倒计时 | countdown()、timer_text() | 原生走时 |
| 外观/透明 | container_background()、transparent_background()、background_image() | 染色用 .accentable() |
| 缓存数据 | cache_json()、history()、save_image() | 见 API 参考 |
#索引
#Family 常量
| 名称 | 说明 |
|---|---|
widget.SMALL | 主屏小（约 158×158 内容区） |
widget.MEDIUM | 主屏中（约 338×158） |
widget.LARGE | 主屏大（约 338×354） |
widget.CIRCULAR | 锁屏圆形 accessory |
widget.RECTANGULAR | 锁屏矩形 accessory |
widget.INLINE | 锁屏行内 accessory |
#模块入口
| 名称 | 说明 |
|---|---|
widget.context | 当前 family、width/height、content_*、is_family() |
widget.param | 预览面板参数声明 |
widget.state | 桌面持久状态 + AppIntent 工厂 |
widget.entry | 当前 timeline entry 字段 |
widget.family_value() | 按 family 返回值 |
widget.action | 受控动作助手（高级） |
widget.color | 颜色助手 |
widget.storage | 轻量存储 |
#生命周期（Widget 实例）
| 方法 | 说明 |
|---|---|
Widget(...) | 创建根容器 |
w.render() | 输出 IR，结束构建 |
w.validate(family=) | 布局/动画诊断报告 |
w.timeline(...) | 声明时间线条目与刷新策略 |
w.background() | 运行时改根背景 |
w.container_background() | 系统容器背景 |
w.transparent_background() | 请求透明 |
w.content_margins() | 内容边距开关 |
w.background_image() | 背景图 + scrim |
#布局容器
| 方法 | 说明 |
|---|---|
row() / column() | 横/纵栈（with 块） |
layer() | 叠放 |
grid() | 等列网格 |
table() | 单路径表格线 |
canvas() | 点位坐标画布 |
when() / unless() | 按 family 显示/隐藏块 |
spacer() / divider() | 间距与分割线 |
#内容与媒体
| 方法 | 说明 |
|---|---|
text() / rich_text() | 文本 |
value() | 数字/状态展示 |
symbol() | SF Symbol（语义图标） |
icon() | 低级图标（一般优先 symbol） |
image() / svg() | 位图 / 矢量 |
badge() / label() / status() | 组合标签 |
progress() / ring_chart() / line_chart() / bar_chart() | 图表 |
flip() | 翻页数字块 |
countdown() / timer_text() / dynamic_date() | 时间相关 |
#交互
| 方法 | 说明 |
|---|---|
button(action=) | AppIntent 按钮 |
toggle(state=) | 开关（color=，无 tint=） |
link(title, url) | 打开链接 |
#常用修饰符（链式）
| 修饰符 | 说明 |
|---|---|
.line_limit(n) / .min_scale(f) | 防裁切 |
.color() / .font_size() / .font_weight() | 外观（symbol 用链式上色） |
.id() | 稳定视图身份 |
.content_transition() / .animation() / .transition() | 数据更新动画 |
.accentable() | 系统染色参与与否 |
.privacy_sensitive() / .redacted() | 锁屏隐私 |
.monospaced_digit() | 等宽数字 |
#工具函数
| 函数 | 说明 |
|---|---|
widget.save_image() | 注册图片供 image/background_image 引用 |
widget.cache_json() | 带 TTL 的 JSON 缓存 |
widget.history() | 按 bucket 保留历史序列 |
widget.validate_layout() | 对 IR 文档做诊断 |
#选择规则
- 信息卡默认
row/column；精确定位再用table/canvas。 - 用户调配置 →
widget.param；用户点桌面 →widget.state。 - 按钮
action只用 state 工厂，不传 Python 函数或字符串。 - 多 family 用
family_value/is_family/when，勿整体缩小 large 布局。 - 可变文案 默认
.line_limit(1).min_scale(0.65+)。 w.symbol("name")后链.color(accent).font_size(18)；多色用rendering="palette", palette=[...]。
已复制
# ❌ symbol 不接受 color=/size=
w.symbol("star.fill", color="#F59E0B", size=18)
# ✅
w.symbol("star.fill").color("#F59E0B").font_size(18)
w.symbol("paintpalette.fill", rendering="palette", palette=["#EF4444", "#3B82F6"])#专题文档地图
| 文档 | 覆盖 API |
|---|---|
| widget 概览 | 总览、快速开始、心智模型 |
| 从脚本到桌面 | render、发布、桌面验证 |
| 布局与尺寸 | row/grid/table/canvas、context |
| 参数面板 | widget.param |
| 状态和交互 | widget.state、button、toggle、link |
| 时间线和动画 | timeline、entry、flip、动画修饰符 |
| 资源与外观 | 背景、图片、SVG、accentable |
| 排错 | validate、常见 TypeError |
| API 参考 | 全部公开签名 |
#示例场景地图
每篇主打不同场景，避免复制粘贴同一套计数器示例：
| 文档 | 主打示例 |
|---|---|
| 概览 | 饮水环形图 ±、每日一言、折线图 |
| 从脚本到桌面 | 习惯开关发布验证 |
| 参数面板 | 主题天气 choice 换肤 |
| 状态和交互 | 连续签到、习惯清单、闹钟开关、链接 |
| 布局与尺寸 | 健康仪表盘、快递追踪、播客 when、周历 grid、Bingo table、canvas、锁屏 |
| 时间线和动画 | 零钱罐、分时电价、flip 翻页、阶段文案、会议倒计时 |
| 资源与外观 | 渐变、accentable、layer、背景图、头像、SVG、步数隐私 |
| 排错 | 最小健康基线（唯一 runnable 基线） |
#失败路径
| 现象 | 处理 |
|---|---|
| 不知道用哪个 API | 本文「先看哪一类」→ 专题文档 |
| 签名记不清 | API 参考 |
TypeError: unexpected keyword | 排错 对照表（tint、symbol color 等） |
| 示例能预览、桌面异常 | 发布流程 + 缓存重装 |
相关 API：widget-api-reference.md