widget 从脚本到桌面

API 地图见 widget-api-index.md；完整签名见 widget-api-reference.md。

从第一行 Python 脚本到主屏/锁屏真正显示：写脚本 → 预览 → 调参 → 发布 → 系统添加小组件。

边界：本篇讲发布流程。API 与节点写法见 widget 概览；文档里的 previewWidget 只能预览，不能直接发布到桌面。

#本篇目标

#发布用脚本（可预览）

本篇示例专注发布验证：一个开关 + 状态文案，便于在桌面确认 AppIntent 是否生效。完整 API 写法（环形图、± 按钮等）见 widget 概览 · 饮水打卡。

预期效果：小组件预览面板显示与脚本一致的布局与交互。

import widget

habit = widget.param.text("习惯名", "每日阅读")
done = widget.state.bool("done", False)
accent = widget.param.color("主色", "#7C3AED")

w = widget.Widget(background=("#FAF5FF", "#1E1B4B"), padding=14)
w.text(habit, size=16, weight="semibold").line_limit(1).min_scale(0.72)
w.toggle("今日完成", state=done, color=accent, style="switch")
status = "已完成，发布验证通过" if done else "桌面点开关以验证"
w.text(status, size=12, color=accent if done else "secondary").line_limit(1).min_scale(0.72)
w.render()

预期效果

• medium：习惯名、开关、状态说明
• 桌面点开关后文案变为「已完成…」即表示 widget.state 与发布链路正常

#三条入口，别搞混

文档示例要上线：把代码复制到 Studio 新建脚本，或放进自己的 Widget 工程后再发布。

#发布流程（Widget Studio）

#1. 准备脚本

• 只创建一个 w = widget.Widget(...)
• 末尾调用 w.render()
• 交互按钮使用 widget.state 的 count.increment() 等 action

#2. 创建或打开项目

1. 打开 App 内 Widget Studio（小组件工作区）
2. 新建独立小组件项目，或打开已有脚本对应的项目
3. 将上例代码保存为项目的 Python 脚本

#3. 运行预览

1. 在项目卡片上点 运行（或等价入口）
2. 进入全屏/Sheet 小组件预览
3. 右上角切换 small / medium / large，确认无文字裁切
4. 在预览侧栏调整 widget.param（习惯名、主色等）

预览成功时，Studio 会生成草稿快照；满足条件时会自动发布到 App 的 Widget 扩展缓存（状态栏常见提示：「已生成并发布 N 个尺寸」或「Widget 已更新，可在桌面选择」）。

#4. 添加到 iOS 主屏幕

发布只代表 App 内已有可渲染快照；还要在系统里添加一次小组件：

1. 回到 iPhone 主屏幕（或锁屏编辑界面）
2. 长按空白处 → 编辑主屏幕 → 点左上角 +
3. 搜索并选择 Python IDE（或你的 App 显示名）
4. 选择尺寸（小/中/大或锁屏 accessory）
5. 若出现多个槽位/项目，选与 Studio 同名 的项目
6. 点 添加小组件

锁屏 accessory（圆形/矩形/行内）需在锁屏编辑界面单独添加，布局要更精简（见 布局与尺寸）。

#5. 桌面验证交互

1. 在主屏小组件上点 「今日完成」 开关
2. 状态文案应变为「已完成，发布验证通过」
3. 若不变：回到 Studio 重新运行发布，或删除桌面小组件后重新添加

#MiniApp Widget 工程（简表）

若 widget 脚本在 MiniApp 的 widgets/ 目录下：

1. 在 MiniApp 编辑器打开 widget 脚本
2. 运行 Widget 预览（工具栏/运行菜单）
3. 构建成功且可发布时，同样会提示 「Widget 已更新，可在桌面选择」
4. 按上一节 §4 在系统里添加或刷新小组件

多 widget _manifest、槽位与工程结构见 MiniApp 内说明；本篇不展开工程细节。

#发布前检查

#常见错误

#失败路径

#改脚本后要不要重新发布？

#相关文档

相关 API：widget-api-reference.md