Widget
画布内容的基本单元——内置 widget 和运行时 Widget 两大类。
Widget 的定位
Widget 是 Canvas 的最小内容单元，对应传统工具里的幻灯片一页、表格一个单元格、Notion 一个块——但比它们都更通用。VizChat 的 widget 可以是一张图、一段文字、一个完整的网页、一个跑着 JS 的交互组件。
Widget 的三层结构：
- Schema：纯数据层，用 Zod v4 定义。AI 修改 widget 时写的是 schema。
- Config：元信息（类型、尺寸、图标、i18n）
- Renderer：React 组件，负责把 schema 渲染为 UI。通常跑在 iframe 里以保证隔离。
三大类 widget
类别 1：内置 widget（Built-in Custom Widget）
编译时绑定、类型固定的 widget，由代码实现，种子到数据库后供 AI 调用。目前 VizChat 内置约 13 种 widget 类型：
| 类型 | 用途 |
|---|---|
bar-chart | 柱状图（可堆叠、分组） |
line-chart | 折线图（支持多条线、时间轴） |
pie-chart | 饼图 / 环形图 |
code-viewer | 语法高亮的代码块 |
rich-text | 富文本编辑（Tiptap） |
slide-title | 演示标题 / 章节分割 |
math-coordinate | 数学坐标系，画函数曲线 |
widget | 运行时生成的 HTML+JS Widget 容器 |
pdf-viewer | PDF 查看器，支持解析和批注 |
web-viewer | 内嵌网页 / 书签预览 |
infographic | 信息图容器 |
详见 内置 widget 类型总览。
类别 2：运行时 Widget
Widget 是 AI 在运行时生成的 HTML + JS 组件，存在数据库里（按 username/slug@version 三元组寻址），可以跨画布复用。典型场景：
- 需要一个标准图表类型不覆盖的组件（如 Sankey 图、日历热力图）
- 需要状态管理和事件交互（筛选器、日期选择器）
- 需要嵌入第三方库（ECharts、D3、Three.js）
Widget 跑在沙盒 iframe 里，有受控的跨 frame API 与宿主画布通信。发布后可进入 Widget Marketplace 被其他用户收藏。
详见 Widget 完整文档。
Widget 独立性与连线
每个 widget 都是一个独立的小应用。它：
- 有自己的状态（保存在 YAML 的
data字段） - 有自己的生命周期（挂载、渲染、销毁）
- 可以单独编辑、复制、删除
- 通过连线和其他 widget 交换数据（Widget 场景）
AI 如何操作 widget
Agent 通过 widget_operations 工具集修改 widget：
# 伪代码示意
tools = [
create_widget, # 创建新 widget
edit_widget, # 修改 widget schema
delete_widget, # 删除 widget
edit_yaml_path, # 精确路径修改（最常用）
validate_board, # 修改后验证整张画布合法性
]每次对话 AI 可能调用多个工具——先搜索相似 widget、再推荐类型、然后创建 + 编辑 + 验证。