组件（Widget）

组件的定位

组件（widget）是画布的最小内容单元，对应传统工具里的幻灯片一页、表格一个单元格、Notion 一个块——但比它们都更通用。VizChat 的组件可以是一张图、一段文字、一个完整的网页、一个跑着 JS 的交互组件。

每个组件自带数据与配置，并定义自己的一套操作。这些字段和操作属于组件自身、会随组件演进——Agent 用到时会去查，而不是假定一个固定形状。

两类组件

内置组件

VizChat 自带的组件，覆盖常见场景：图表与数据（含数学——坐标系、数轴、立体几何、概率分布、韦恩图、概率树、数据表）、富文本与代码、PDF、网页嵌入与外链、图片与信息图、幻灯片封面。完整清单与各自能做什么见组件类型总览。

自定义组件

内置组件覆盖不到时，Agent 可以替你做一个：计时器、看板、计算器，或任何特定的交互组件。自定义组件在运行时生成、存入你的组件库，并可跨文档复用。典型场景：

• 标准组件不覆盖的可视化（如桑基图、日历热力图）
• 需要状态管理和事件交互（筛选器、日期选择器）
• 需要嵌入第三方库

自定义组件默认 inline 挂载在画布内；需要完全隔离的运行环境时可选 nested 挂载，跑在沙盒 iframe 里。两种形态都通过受控 API 与宿主画布通信。默认仅你自己可见，也可以发布到市场供他人使用和收藏。

组件独立性

每个组件都是一个独立的小应用。它：

• 有自己的数据与配置，保存在文档里
• 有自己的生命周期（挂载、渲染、销毁）
• 可以单独编辑、复制、删除

组件更新

组件放进文档的那一刻，就固定在当时的版本上。作者之后发布新版本时，你的文档怎么跟上，取决于它的更新方式：

• 「读得懂」是按这份文档自己的数据判断的：同一次更新，对一份文档兼容，对另一份可能不兼容。判断不了时（比如文档里固定的那一版已经下线、查不到它原来的数据格式），不会自动更新，只列出来等你决定。
• 文档正打开着时不会被自动改动，这次更新只记下来，等你在提示里决定。
• 账号的默认方式在设置的「数据管理」里改；单个演示或看板可以另外设置：在它的标签上右键，选「文档设置」。
• 自动更新之后、以及有更新需要改动内容才能用时，你会收到通知，点开直接打开这份文档。画布上方会说明哪些组件已经自动更新，「查看更新」里留着最近的更新记录。
• 已发布的演示或看板被自动更新时，如果草稿里没有别的未发布修改，会顺带为它发布一个新版本；有的话只更新草稿，等你下次发布时一起发出。
• 自动更新不提供一键回退。不想让某份文档被自动改动，把它的更新方式设成「手动」。

还没用上的更新照常在画布上方提示：

• 打开演示或看板时，如果里面的组件有新版本，画布上方会出现一行「N 个组件有更新」，可以关掉不理。
• 修复更新（组件的数据格式没变）可以一键全部应用；功能更新先预览：用新版本把当前文件渲染一遍给你看，确认才更新。
• 如果新版本读这份文件里的某些数据对不上，会标出「可能影响第 3、5 页」。这只是提示，不会拦着你；更新后不满意，点「撤销」就回到原来的版本（也可以用撤销快捷键）。
• 需要改动内容才能用的更新，可以在对话里让 AI 帮你改，也可以先忽略。
• 也可以直接让 AI「把组件更新到最新」，它走的是同一套更新。

新加入的组件默认用最新版本。

AI 如何操作组件

你提出需求后，Agent 大致按这条路径工作：

1. 找组件——search_widgets 在同一个池子里检索内置组件与用户发布的组件；你收藏过的、或用 @ 提到的组件会被优先考虑。
2. 取契约——describe_widget 返回该组件实际接受的字段与操作。
3. 写入文档——把组件及其初始数据写进文档；后续修改用 edit_yaml_path 做精确路径编辑。
4. 验证——check_board 检查文档结构、引用的组件是否都已创建、引用的工作空间文档是否存在。

如果组件库里没有合适的，Agent 会转而替你新建一个自定义组件。

Next step

• 画布心智模型
• 内置组件类型
• Agent 工作流