# 小部件设计最佳实践 ## 决策框架 ### 平台选择根据目标客户选择： * **GPT 应用程序**：目标是 ChatGPT。需要 `_meta.openai` 和 `widgetAccessible: true`。 * **MCP 应用程序**：目标是任何外部应用程序客户端。最小配置，自动工作。 ### 处理程序类型选择场景 |处理程序 |原因 ---|---|--- 需要用户交互（按钮、输入）|反应 (`.tsx`) |带钩子的状态管理显示外部小部件库 |模板文字 |只需加载脚本/样式来自工具参数的动态内容 |反应 |道具自然流动没有状态的静态 HTML |模板文字 |更简单，开销更少 **经验法则**：如果不确定，请从 React 开始。后期转换比简单开始更难。 ## 小部件设计原则 ### 1\.小部件不是 Web 应用程序小部件在对话中内联呈现。设计限制： * **无导航**：仅限单屏体验 * **宽度有限**：大多数客户端的最大宽度约为 600-700 像素 * **沙盒** ：外部资源需要 CSP 声明 * **短暂** ：可能会重新渲染，不依赖于持久性 ### 2\.即时价值显示有用的内容而不需要用户操作： // 不好：需要点击才能看到任何内容导出默认函数 Widget() { const [数据，setData] = useState(null); return ; } // 好：立即显示数据导出默认函数 Widget({ query }) { const [数据，setData] = useState(null); useEffect(() => { fetchData(query).then(setData); }, [query]); 返回数据？ <结果数据={data} /> : <加载/>; } ### 3\.有限空间内的视觉层次由于宽度有限，层次结构更重要：

{/* 标签：小、静音、大写 */}

温度

{/* 价值：大、突出 */}

72°F

{/* 支持：中等、次要 */}

感觉温度为 68°F

### 4\.每个交互元素都需要反馈用户需要视觉确认元素是交互式的： // 不好：没有视觉反馈 // 好：悬停 + 过渡 <按钮 className="px-4 py-2 bg-white/10 悬停:bg-white/20 边框 border-white/10 悬停:border-white/20 过渡-all 持续时间-200"> 点击 ## 状态管理指南 ### 保持状态本地且简单小部件是隔离的。没有 Redux、Zustand 或外部状态。 // 好：带有钩子的本地状态 const [items, setItems] = useState([]); const [正在加载，setLoading] = useState(true); const [错误，setError] = useState(null); ### 始终处理三种状态每个异步操作都有三种状态。处理所有这些：导出默认函数 Widget() { const [数据，setData] = useState(null); const [正在加载，setLoading] = useState(true); const [错误，setError] = useState(null); 使用效果（（）=> { 获取数据() .then(设置数据) .catch(e => setError(e.message)) .finally(() => setLoading(false)); }, []); 如果（正在加载）返回<正在加载/>； if (错误) return <错误消息={error} />; return <显示数据={data} />; } ### 在安装时获取，而不是在单击时获取小部件应该立即显示价值： // 不好：用户必须点击才能查看数据 // 好：自动获取 useEffect(() => { fetchData(); }, []); ## 常见错误 ### 1\.缺少 widgetAccessible（GPT 应用程序）如果没有这个，小部件将不会渲染： // 损坏 _meta: { openai: { 工具调用: { ... } } } // 固定 _meta: { openai: { widgetAccessible: true, toolInspiration: { ... } } } ### 2\.不带 CSP 的外部读取请求被静默阻止： // 损坏：获取失败且无提示 fetch('{{WEATHER_API_URL}}'); // 修正：在元数据中声明 _元：{ 打开：{ widgetCSP: { connect_domains: ["{{WEATHER_API_BASE_URL}}"] } } } ### 3\.硬编码尺寸小部件在不同的屏幕尺寸上会崩溃： // 不好

...

// 好

...

### 4\.无误差边界崩溃显示空白小部件： // 始终包装有风险的操作尝试{ const 结果 = JSON.parse(data); } 抓住 { return <错误消息=“无效的数据格式”/>; } ## 平台特定注释 ### GPT 应用程序：用于小部件通信的结构化内容将数据从工具传递到小部件：返回{ StructuredContent: { 游戏: "doom", url: "..." }, 内容：[{ 类型：“文本”，文本：“启动 DOOM...” }]， }; 小部件通过 `useToolOutput()` 钩子读取。 ### MCP 应用程序：最小配置 MCP 应用程序仅与 React 组件配合使用： // 这对于 MCP 应用程序来说已经足够了导出 const 元数据 = { 名称：“小部件”，描述：“...” }; 导出默认函数 Widget() { return

Hello

; } ## 快速参考 ### GPT 应用清单 * 元数据中的`widgetAccessible: true` * 64 个字符以下的“toolInspiration”消息 * 外部域的 CSP ## 参考文献请参阅 [references/design-principles.md]() 了解： * 完整的小部件示例（计数器、天气、街机） * 组件模式（卡片、按钮、选项卡） * CSS 模块示例 * GPT 应用程序提交要求 * 项目结构模板

小部件设计

包含技能