使用教程

新建一个组件

在组件库首页，点右上角的 “＋”。

选择尺寸

选择小号、中号或大号，尺寸与主屏幕上的小组件完全一致。选好后点右上角的 “创建”。

接入你的 API（可选）

在预览下方的 API 栏填入你的 HTTPS 地址，点刷新按钮，预览会立刻用接口返回的数据渲染。

小提示这一步可以跳过：不填 API 也能设计外观、添加图层并保存，等接口准备好了再回来填写。

选择外观

在 “小组件” 面板中打开 “表面材质”，左右滑动挑选液态玻璃、玻璃、纯色、渐变、氛围光或图片，再点 “应用此风格”。

添加图层，绑定数据（可选）

点 “添加图层”，选择文本、曲线等图层。把 “来源” 设为 “API 数据” 并填写数据路径（例如 data.orders），图层就会显示接口返回的实时数值。

小提示数据路径可以先留空，图层照样能添加、编辑和保存，等接口准备好了再回来绑定。

命名并保存

给组件起个名字，点右上角 “保存”。它会出现在组件库里，接下来就能添加到主屏幕了。

在主屏幕上添加

回到主屏幕，长按空白处直到图标晃动，点左上角 “编辑”，再选择 “添加小组件”。

选对风格和尺寸

搜索 “Glance Widgets”，左右滑动，选出与你的组件相同的风格和尺寸，再点 “添加小组件”。

小提示风格要与组件的材质对应：液态玻璃选 “液态玻璃”，玻璃选 “玻璃”，纯色、渐变、氛围光、图片都选 “基础”。尺寸也要一致。

选择要显示的组件

长按刚添加的小组件，点 “编辑小组件”，在 “小组件” 一项中选择要显示的组件。

小提示列表里只会出现尺寸和风格都匹配的组件。找不到时，请回到 App 确认它的尺寸和材质。

在 App 中管理

在组件库里长按卡片或点 “…”，可以立即刷新、复制、编辑或删除。卡片显示 “刷新失败” 时，也可以在这里重试。

用自定义 API 驱动动态内容与样式

小组件会向你设置的 API 地址请求数据。你的服务端按协议返回 JSON，就能让小组件的内容与样式随业务变化。

用 SDK，或自己实现

SDK 只是用来简化开发，并非必需。你可以用官方 SDK 生成协议数据，也可以用熟悉的语言和框架自行实现，只要返回符合协议的 JSON 即可。

按需兼容设备尺寸

尺寸和位置通常使用相对值，会随画布自适应。一个 API 往往只对应一个特定的小组件，一般不需要单独适配尺寸。

小提示如果同一内容需要显示在多台屏幕尺寸略有差异的设备上，并且你观察到绘制效果不一致，再根据请求中的 gw_canvas_width_pt / gw_canvas_height_pt 做兼容即可。

用 data 承载业务数据

把订单数、状态、趋势等业务数据放在响应的 data 字段里。图层通过 data.orders 这样的数据路径读取，数据一更新，显示的内容就随之变化。

也可直接展示 服务端绘制的图片

服务端也可以完全接管绘制：把内容渲染成一张图片，通过 API 返回。小组件把表面材质设为 “图片”、来源选 “API”，再填写图片的数据路径，就能直接显示实时生成的画面。

小提示这是一种替代方式，无需再配置 Glance Widgets 图层，也不必深入掌握绘制语法。API 仍返回 JSON，图片链接或 Base64 放在 data 中。

按需为请求加上签名

若要校验请求来源，在编辑页的 “API签名秘钥” 中生成并复制秘钥，配置到服务端。请求只携带时间戳和签名，秘钥本身不会被发送；服务端可以自行校验，也可以使用 SDK 的 verifySignature。

在 App 里就能预览

编辑页和首页列表都会直接预览小组件，效果与主屏幕上的显示基本一致，调整内容和样式时随时可以查看。

认识 StandBy

iPhone 锁定后，一边充电一边横放，就会进入 StandBy（待机显示），以大尺寸全屏显示时钟和小组件。把你的组件放在这里，放在桌边也能一眼看到。

确认已开启

StandBy 需要 iOS 17 或更高版本，默认开启。如果一直没有出现，打开 设置 › 待机显示，确认开关已打开。之后只要同时满足锁定、充电、横放，就会自动进入。

把组件放上来

在 StandBy 中长按小组件，用面容 ID 解锁后进入编辑。点左上角 “＋”，找到 Glance Widgets，添加小号组件后点 “完成”。要选择显示哪个组件，方法和主屏幕相同：长按 › “编辑小组件”。

在 StandBy 中更好看

StandBy 会去掉组件背景、放大显示内容；环境变暗时还会进入夜间模式，整体变成红色调。对比度高、去掉背景后依然清晰的设计效果最好。

小提示材质为“图片”的组件已做专门适配：StandBy 中图片会照常显示，不会被移除。