widget-ux-patterns

用途

widget-ux-patterns 用于设计智能体渲染的组件（agent widget）的视觉与交互层。其核心理念是：智能体组件是他人界面中的“客人”，它会继承宿主的主题、与宿主的输入框竞争，并在感觉像另一个应用时被立即关闭。因此设计应面向宿主容器，从能让用户理解结果或完成任务的最小呈现形式入手，仅在工作流程确实需要时才申请更多空间。

四种显示模式

内联卡片（Inline card）

用于聚焦的结果、确认或少量操作，是默认模式。规则包括：最多两个主要操作（一个主 CTA，一个可选次要操作）；卡片内不做深层导航、标签页或下钻；无嵌套滚动，内容自适应可用高度；绝不重复宿主已提供的功能；保持视觉层级：标题 → 支持文本 → CTA。移动端卡片可扩展高度以匹配内容，最高可到移动显示区域的高度。

内联轮播（Inline carousel）

用于浏览少量相似且视觉丰富的选项，如餐厅、播放列表、活动等。规则包括：3–8 个项目，更少显得残缺，更多则成了列表而非轮播；每项元数据不超过 3 行；每项一个明确 CTA；宽高比保持一致，参差不齐的轮播会显得像 bug。

全屏（Fullscreen）

用于需要空间的大型任务：地图、编辑画布、详细浏览。宿主输入框会保持叠加状态，设计应围绕它进行，绝不把控件放在输入框出现的位置。不要整体复制原生应用；全屏是聚焦表面，而非产品的移植。需提供明显的返回内联的方式。在 M365 Copilot 中，全屏是唯一支持的替代模式。

画中画（Picture-in-picture）

用于对话继续时仍应保持可见的进行中活动，如直播会话、游戏或视频。控件极简，堆满 chrome 的 PiP 在该尺寸下无法使用；必须响应对话输入，不能静止不动；会话结束时自动关闭，不要与之对抗。

请求模式

const modes = app.getHostContext()?.availableDisplayModes ?? ["inline"];
if (modes.includes("fullscreen") && app.requestDisplayMode) {
  await app.requestDisplayMode({ mode: "fullscreen" });
}

宿主可能授予与请求不同的模式。应根据被授予的模式渲染，而非请求的模式。

视觉设计

颜色：文本、图标和分割线等结构性元素使用系统色。品牌强调色仅用于徽标、小图标和主按钮，其他位置不用。不要用品牌色覆盖系统文本色或背景色。不使用自定义渐变或背景覆盖。遵循 hostContext.theme（并以 prefers-color-scheme 作为兜底，因为 onhostcontextchanged 并非普遍支持）。

排版：继承宿主的字体栈，任何情况下都不使用自定义字体，全屏也不行。遵循设备原生尺寸规则——iOS 上 SF Pro，Android 上 sans-serif。限制字号变化，优先使用 body 和 body-small。加粗、斜体、高亮等伙伴样式仅在内容区域使用。

布局：卡片和集合使用宿主的网格间距。内边距保持一致，绝不使用贴边文本。遵循宿主上下文中的 safeAreaInsets。高度应通过 sendSizeChanged / notifyIntrinsicHeight 驱动，而不是猜测固定高度。

图标与图像：使用匹配宿主语言、单色、描边的图标体系。固定宽高比，绝不拉伸变形。不要把自己的徽标作为响应元素渲染——宿主会自行追加署名。

无障碍（不可妥协）

文本与背景达到 WCAG AA 对比度最低要求。每张图片都有替代文本。文本缩放不得破坏布局——文字周围不使用固定像素高度。完整键盘可达性，可见焦点状态。使用语义元素和 ARIA 角色（aria-pressed、异步结果的 aria-live）。A2UI：将 AccessibilityAttributes 接入原生 API。遵循 prefers-reduced-motion。

加载、空与错误状态

每个组件需要四种状态，而其中三种常被跳过：

加载（Loading）：在结果到达前先用 ontoolinput 渲染骨架屏。已知形状时不要只显示一个裸 spinner。
空（Empty）：说明缺了什么以及下一步做什么，而不是仅说“无结果”。
错误（Error）：人类可读的消息加一条重试路径。同时调用 updateModelContext，让模型知道视图已降级并可提供帮助。
部分（Partial）：借助 ontoolinputpartial 渐进渲染，但将修复后的 JSON 视为不完整，绝不据此采取行动。

与对话的交互

组件和聊天是同一个体验，不要构建平行的聊天。当用户接下来应该说话时使用 ui/message / sendFollowUpMessage；当模型只需知道某件事时使用 ui/update-model-context。混淆二者会导致要么记录刷屏，要么模型完全不知道用户选了什么。每次用户操作只做一次有意义的更新，不要每次击键都流式传递上下文。

本地化

宿主会将 locale 镜像到 document.documentElement.lang。

const locale = document.documentElement.lang || "en-US";

根据该 locale 格式化日期、数字和货币，而不是根据服务器的。

清单

应该做：快速确认和简单操作使用内联；全屏中保持输入框可用；品牌色仅用于强调和徽章；每个轮播项一个明确 CTA；渲染任何依赖宿主的可供性之前先进行功能检测。

不应做：卡片内深层导航、标签页或下钻；嵌套滚动或拥挤布局；复制宿主原生功能；覆盖系统文本色或背景色；任何地方使用自定义字体；PiP 堆满控件或保持静止。

限制

资料未提供该技能的安装方式、收费或价格、支持平台范围、版本信息及效果数据，这些事实暂未提供。

技能介绍

用途