add vitepress docs

2026-09-21 16:05:14 +08:00
parent b435bf992e
commit 37cf38fe27
73 changed files with 7003 additions and 802 deletions
@@ -0,0 +1,42 @@
+# AI 对话
+
+把对话面板嵌进带标题栏的页面骨架，并自定义欢迎语与角色名。
+
+## 组合演示
+
+:::preview 完整对话 || 回答由本地假流逐块吐出，可随时点「停止」或用「清空」重开
+
+demo-preview=../demos/scenarios/ai.vue
+
+:::
+
+## 这个场景覆盖了什么
+
+- **会话接线**：`useAiChat` 提供 `messages` 与生成状态，面板只负责渲染
+- **页面骨架**：标题栏与面板组合成完整页面，`清空` 调用 `resetConversation`
+- **自定义文案**：`roleNames` 把「助手」换成「分析助手」，`welcome` 插槽替换空态
+- **流式呈现**：思考过程、工具状态、回答与引用按事件依次出现
+
+## 换成真实后端
+
+示例里的 `request` 返回的是本地构造的假流。接真实接口时只要返回一个 SSE 流式的 `Response` 即可，其余不用改：
+
+```ts
+const chat = useAiChat({
+	request: ({ message, signal }) => fetch("/api/chat", {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ message }),
+		signal
+	})
+});
+```
+
+事件名与载荷字段见 [AiChatPanel](/components/ai-chat-panel) 的协议表；后端用的是另一套事件名时，用 `parseEvent` 转换。
+
+## 相关组件
+
+- [AiChatPanel](/components/ai-chat-panel)
+- [AiChatMessageList](/components/ai-chat-message-list)
+- [AiChatComposer](/components/ai-chat-composer)
+- [AiChatThinking](/components/ai-chat-thinking)
@@ -0,0 +1,27 @@
+# 文章编辑与预览
+
+编辑与预览共用同一个 `Article` 对象，用标签在两种视图之间切换。
+
+## 组合演示
+
+:::preview 编辑与预览联动 || 切换正文类型时两个标签页同时切换渲染分支
+
+demo-preview=../demos/scenarios/article.vue
+
+:::
+
+## 这个场景覆盖了什么
+
+- **正文类型切换**：纯文本、Markdown、富文本三种形态共用一份数据
+- **数据联动**：`ArticleEditor` 抛出的更新直接喂给 `ArticleView`
+- **字段保留**：`title` 等业务字段由外层维护，编辑器不会丢字段
+- **提交语义**：`submit()` 等待未完成的媒体上传后再返回最终数据
+
+## 为什么用标签而不是分栏
+
+PC 端可以左右并排，移动端宽度不够。用标签切换既保证了对比的便利，又不牺牲编辑区的可用宽度。
+
+## 相关组件
+
+- [ArticleEditor](/components/article-editor)
+- [ArticleView](/components/article-view)
@@ -0,0 +1,24 @@
+# 编辑器能力总览
+
+把富文本编辑器、只读视图与代码编辑器放在一个页面里，验证它们共用同一套内容模型与检索能力。
+
+## 组合演示
+
+:::preview 组合用法 || 标签切换而不是左右分栏——移动端宽度放不下分栏
+
+demo-preview=../demos/scenarios/editor.vue
+
+:::
+
+## 这个场景覆盖了什么
+
+- **富文本编辑**：工具栏、媒体上传、提交前的占位内容处理
+- **只读渲染**：同一份 HTML 交给 `TiptapView`，展示效果与编辑态一致
+- **代码编辑**：行号、语法高亮与查找替换
+- **统一检索**：`openSearch()` 在两类编辑器上语义一致，便于封装统一的快捷键
+
+## 相关组件
+
+- [TiptapEditor](/components/tiptap-editor)
+- [TiptapView](/components/tiptap-view)
+- [CodeEditor](/components/code-editor)
@@ -0,0 +1,27 @@
+# 移动端组件
+
+移动端最典型的两种浮现方式：整块选择面板与操作确认，都从底部升起。
+
+## 组合演示
+
+:::preview 组合用法 || 点击「缓存有效期」行打开 Picker，点按钮打开底部弹层
+
+demo-preview=../demos/scenarios/mobile.vue
+
+:::
+
+## 这个场景覆盖了什么
+
+- **列表触发的选择面板**：`t-cell` 当前值 + 箭头，点击后用 `t-popup` 从底部升起 `DurationPicker`
+- **操作确认**：`BottomPopup` 承载标题与左右按钮，按钮只抛事件、关闭由业务决定
+- **间距**：`Space` 统一控制一组元素之间的间距
+
+## 关于 destroy-on-close
+
+示例里的 Picker 弹层加了 `destroy-on-close`，每次打开都重建，避免上次的选择残留。选择面板这类有内部滚动状态的组件建议都带上。
+
+## 相关组件
+
+- [DurationPicker](/components/duration-picker)
+- [BottomPopup](/components/bottom-popup)
+- [Space](/components/space)
@@ -0,0 +1,22 @@
+# 通知编辑与预览
+
+通知复用文章编辑器的正文能力，同时保留主题、状态等自有字段。
+
+## 组合演示
+
+:::preview 编辑与预览联动 || 状态字段由外层维护，切状态不影响正文
+
+demo-preview=../demos/scenarios/notify.vue
+
+:::
+
+## 这个场景覆盖了什么
+
+- **能力复用**：`NotifyEditor` 内部就是 `ArticleEditor`，正文体验一致
+- **元数据独立**：`subject`、`status` 等字段与正文互不干扰
+- **字段透传**：业务字段在编辑过程中原样保留
+
+## 相关组件
+
+- [NotifyEditor](/components/notify-editor)
+- [NotifyView](/components/notify-view)