229 lines
11 KiB
Markdown
229 lines
11 KiB
Markdown
# AI 写作 · 右侧文本编辑器(滑词 / 段落菜单)
|
||
|
||
> 说明 AI 写作页、开放画布中文稿右侧编辑器的实现方式:**编辑器本体基于 Tiptap v3**;选中文本浮层(「滑词」)与段落悬停按钮为**自研 React 组件**,未使用 `@tiptap/extension-bubble-menu` 官方 BubbleMenu。
|
||
|
||
---
|
||
|
||
## 一、功能概览
|
||
|
||
| 交互 | 用户感知 | 组件 | 触发方式 |
|
||
|------|----------|------|----------|
|
||
| **滑词** | 拖选一段文字后,选区上方出现工具条(AI 改写、加粗、斜体、下划线、H1、复制) | `WritingBubbleMenu` | Tiptap `selectionUpdate` + 浏览器 `window.getSelection()` |
|
||
| **段落菜单** | 鼠标移入某段/标题/引用块时,段落左侧出现 ✨ 按钮,点击可 AI 改写整段 | `WritingParagraphMenu` | 编辑器 DOM `mousemove` + ProseMirror `posAtCoords` |
|
||
| **AI 改写面板** | 点击「AI 改写」后弹出润色/扩写等操作与预览 | `WritingAiMenu` / `WritingRewritePreview` | 由 `TextArtifactRenderer` + `useWritingRewrite` 串联 |
|
||
|
||
画布线程页(`/page/canvas/:thread_id`)与 AI 写作页(`/page/workspace/ai-writing`)右侧草稿**共用同一套** `TextArtifactRenderer` 与菜单组件。
|
||
|
||
---
|
||
|
||
## 二、在 AI 写作中的挂载路径
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
AIWritingPage --> CanvasResizableLayout
|
||
CanvasResizableLayout --> AIWritingDraftPanel
|
||
AIWritingDraftPanel --> DraftStreamingPreview
|
||
AIWritingDraftPanel --> TextArtifactRenderer
|
||
DraftStreamingPreview["DraftStreamingPreview<br/>(流式只读 Markdown)"]
|
||
TextArtifactRenderer --> WritingBubbleMenu
|
||
TextArtifactRenderer --> WritingParagraphMenu
|
||
TextArtifactRenderer --> TiptapEditor
|
||
TextArtifactRenderer --> WritingAiMenu
|
||
```
|
||
|
||
| 阶段 | 右侧展示 | 滑词 / 段落菜单 |
|
||
|------|----------|-----------------|
|
||
| 草稿流式生成中(`writing_draft` / `revising` 且有 section 流) | `DraftStreamingPreview`(ReactMarkdown 只读) | **不可用** |
|
||
| 成稿可编辑(`isDraftEditable === true`) | `TextArtifactRenderer` + Tiptap | **可用** |
|
||
| 流式结束但尚未 editable | `TextArtifactRenderer` 且 `isStreaming={true}` | **不可用**(`editable: false`) |
|
||
|
||
相关状态由 [CanvasUIContext.tsx](../src/open-canvas/contexts/CanvasUIContext.tsx) 的 `isDraftStreaming`、`isDraftEditable` 控制;注释中「禁用编辑/润色/滑词」即指生成完成前不进入可编辑渲染器。
|
||
|
||
入口文件:
|
||
|
||
- [AIWritingDraftPanel.tsx](../src/open-canvas/components/ai-writing/AIWritingDraftPanel.tsx) — 决定流式预览 vs `TextArtifactRenderer`
|
||
- [TextArtifactRenderer.tsx](../src/open-canvas/components/artifact/TextArtifactRenderer.tsx) — 挂载编辑器与两套浮层菜单
|
||
|
||
---
|
||
|
||
## 三、技术栈:编辑器 vs 浮层
|
||
|
||
### 3.1 Tiptap 编辑器(有使用)
|
||
|
||
| 包 | 用途 |
|
||
|----|------|
|
||
| `@tiptap/react` | `useEditor`、`EditorContent` |
|
||
| `@tiptap/starter-kit` | 段落、标题、加粗、斜体、下划线等 |
|
||
| `@tiptap/extension-placeholder` | 空文档占位符 |
|
||
| `tiptap-markdown` | Markdown ↔ 文档互转 |
|
||
| 自研 `AiHighlightExtension` | AI 改写前高亮选区(ProseMirror Decoration) |
|
||
|
||
扩展注册见 [TiptapExtensions.ts](../src/open-canvas/editor/TiptapExtensions.ts);实例创建见 [useWritingEditor.ts](../src/open-canvas/hooks/useWritingEditor.ts)。
|
||
|
||
### 3.2 浮层菜单(自研,非 Tiptap 官方插件)
|
||
|
||
| 包 | 是否用于滑词/段落菜单 |
|
||
|----|----------------------|
|
||
| `@tiptap/extension-bubble-menu` | **未使用**(`package.json` 中有依赖,代码未 import) |
|
||
| `@tiptap/react` 的 `<BubbleMenu>` | **未使用** |
|
||
|
||
两套菜单均采用:
|
||
|
||
1. 监听 Tiptap / DOM 事件更新位置与选区;
|
||
2. `createPortal(..., document.body)` 挂到 `document.body`,避免被右侧滚动容器 `overflow` 裁切;
|
||
3. `position: fixed` + `getBoundingClientRect()` 定位。
|
||
|
||
命名上的 `WritingBubbleMenu` 仅表示「气泡式选区工具条」,实现上与 Tiptap 官方 Bubble Menu 扩展无关。
|
||
|
||
---
|
||
|
||
## 四、核心文件索引
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| [TiptapEditor.tsx](../src/open-canvas/editor/TiptapEditor.tsx) | `EditorContent` 渲染容器 |
|
||
| [TiptapExtensions.ts](../src/open-canvas/editor/TiptapExtensions.ts) | StarterKit、Placeholder、Markdown、AiHighlight |
|
||
| [AiHighlightExtension.ts](../src/open-canvas/editor/AiHighlightExtension.ts) | `setAiHighlight` / `clearAiHighlight` 命令 |
|
||
| [useWritingEditor.ts](../src/open-canvas/hooks/useWritingEditor.ts) | 创建 editor、同步外部 markdown、editable |
|
||
| [WritingBubbleMenu.tsx](../src/open-canvas/components/artifact/WritingBubbleMenu.tsx) | **滑词** 选区浮层 |
|
||
| [WritingParagraphMenu.tsx](../src/open-canvas/components/artifact/WritingParagraphMenu.tsx) | **段落** 左侧 ✨ 按钮 |
|
||
| [WritingAiMenu.tsx](../src/open-canvas/components/artifact/WritingAiMenu.tsx) | AI 改写操作菜单 |
|
||
| [WritingRewritePreview.tsx](../src/open-canvas/components/artifact/WritingRewritePreview.tsx) | 改写结果预览 |
|
||
| [useWritingRewrite.ts](../src/open-canvas/hooks/useWritingRewrite.ts) | 调用润色 API、写回编辑器 |
|
||
| [apply-rewrite.ts](../src/open-canvas/utils/apply-rewrite.ts) | 将改写结果应用到 ProseMirror 选区 |
|
||
| [CanvasUIContext.tsx](../src/open-canvas/contexts/CanvasUIContext.tsx) | `writingSelection` 全局状态 |
|
||
| [selection.ts](../src/open-canvas/types/selection.ts) | `WritingSelection` 类型定义 |
|
||
|
||
---
|
||
|
||
## 五、滑词:`WritingBubbleMenu`
|
||
|
||
### 5.1 行为
|
||
|
||
- 用户在编辑器内拖选非空文本时显示浮层;选区为空或位于 `codeBlock` 内时隐藏。
|
||
- 浮层按钮:`AI 改写`、`B` / `I` / `U`、`H1`、复制。
|
||
- 按钮 `onMouseDown` 使用 `e.preventDefault()`,避免点击时编辑器失焦导致选区丢失。
|
||
|
||
### 5.2 实现要点
|
||
|
||
```text
|
||
editor.on("selectionUpdate")
|
||
→ 读取 editor.state.selection (from, to, empty)
|
||
→ window.getSelection() + Range.getBoundingClientRect() 算屏幕坐标
|
||
→ setWritingSelection({ from, to, text }) 写入 CanvasUIContext
|
||
→ createPortal 渲染工具条,useLayoutEffect 做贴边 / 上方空间不足时翻到选区下方
|
||
```
|
||
|
||
关键代码位置:[WritingBubbleMenu.tsx](../src/open-canvas/components/artifact/WritingBubbleMenu.tsx) 中 `useEffect` 监听 `selectionUpdate` 与 `blur`。
|
||
|
||
点击「AI 改写」时:
|
||
|
||
1. `editor.commands.setAiHighlight(from, to)` 高亮选区;
|
||
2. 调用父组件传入的 `onAiRewrite()`,由 `TextArtifactRenderer` 打开 `WritingAiMenu`。
|
||
|
||
---
|
||
|
||
## 六、段落菜单:`WritingParagraphMenu`
|
||
|
||
### 6.1 行为
|
||
|
||
- 鼠标在编辑器内移动时,检测光标下的**块级节点**;
|
||
- 仅对 `paragraph`、`heading`、`blockquote` 且文本非空时,在块左侧显示 ✨ 按钮;
|
||
- 鼠标离开编辑器或移出可改写块后,延迟约 **380ms** 隐藏(`HIDE_DELAY`),并在按钮与正文之间留有 hover 桥接区,避免移向按钮时闪烁消失。
|
||
|
||
### 6.2 实现要点
|
||
|
||
```text
|
||
editor.view.dom mousemove
|
||
→ editor.view.posAtCoords({ left, top })
|
||
→ doc.resolve(pos).before(depth) 定位块起点
|
||
→ editor.view.nodeDOM(nodeStart) 取 DOM 矩形
|
||
→ createPortal 固定定位按钮在块左侧 (BTN_SIZE=24, BTN_GAP=6)
|
||
```
|
||
|
||
点击 ✨ 时:
|
||
|
||
1. `setTextSelection` 选中整段 ProseMirror 范围(`nodeFrom` ~ `nodeTo`);
|
||
2. `setAiHighlight` + `setWritingSelection`;
|
||
3. 触发与滑词相同的 `onAiRewrite()` 流程。
|
||
|
||
关键代码位置:[WritingParagraphMenu.tsx](../src/open-canvas/components/artifact/WritingParagraphMenu.tsx)。
|
||
|
||
---
|
||
|
||
## 七、AI 改写数据流
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User
|
||
participant Menu as BubbleMenu / ParagraphMenu
|
||
participant Ctx as CanvasUIContext
|
||
participant Renderer as TextArtifactRenderer
|
||
participant API as rewrite API
|
||
|
||
User->>Menu: 选中文本或点段落 ✨
|
||
Menu->>Ctx: setWritingSelection
|
||
Menu->>Renderer: onAiRewrite()
|
||
Renderer->>Renderer: phase = menu, WritingAiMenu
|
||
User->>Renderer: 选择润色/扩写等
|
||
Renderer->>API: useWritingRewrite.rewrite
|
||
API-->>Renderer: 流式结果
|
||
Renderer->>Renderer: WritingRewritePreview
|
||
User->>Renderer: 接受改写
|
||
Renderer->>Renderer: applyReplace / applyInsert
|
||
```
|
||
|
||
- 选区信息类型:`WritingSelection`(`from`、`to`、`text`),见 [selection.ts](../src/open-canvas/types/selection.ts)。
|
||
- 与画布聊天侧选区 `CanvasTextSelection` 分离;后者用于快捷操作栏等,不用于 Tiptap 改写。
|
||
|
||
---
|
||
|
||
## 八、与顶部工具栏、目录栏的关系
|
||
|
||
同一 `TextArtifactRenderer` 编辑模式下还包含:
|
||
|
||
| 组件 | 作用 |
|
||
|------|------|
|
||
| [WritingToolbar.tsx](../src/open-canvas/components/artifact/WritingToolbar.tsx) | 顶部固定格式栏、导出等 |
|
||
| [DraftOutlineSidebar.tsx](../src/open-canvas/components/artifact/DraftOutlineSidebar.tsx) | 左侧标题目录,点击滚动到对应 heading |
|
||
|
||
滑词 / 段落菜单与工具栏互不替代:工具栏面向全局格式;浮层面向**当前选区或当前段落**的快捷操作与 AI 改写入口。
|
||
|
||
---
|
||
|
||
## 九、开发与改造建议
|
||
|
||
### 9.1 若要改用官方 Bubble Menu
|
||
|
||
1. 在 [TiptapExtensions.ts](../src/open-canvas/editor/TiptapExtensions.ts) 或组件层引入 `@tiptap/react` 的 `BubbleMenu`(或注册 `@tiptap/extension-bubble-menu`);
|
||
2. 将 [WritingBubbleMenu.tsx](../src/open-canvas/components/artifact/WritingBubbleMenu.tsx) 内手写 `selectionUpdate` + Portal 逻辑替换为官方组件的 `shouldShow` / `tippyOptions`(v3 API 以官方文档为准);
|
||
3. **段落左侧按钮**仍建议保留自研 `WritingParagraphMenu`(官方 Bubble Menu 只覆盖选区,不覆盖 hover 段落场景)。
|
||
|
||
### 9.2 新增浮层按钮
|
||
|
||
- **滑词**:在 `WritingBubbleMenu` 的 `BubbleButton` 列表中增加,使用 `editor.chain().focus()....run()`。
|
||
- **段落**:在 `WritingParagraphMenu` 的 `handleClick` 或拆出多按钮布局;注意 `REWRITABLE_TYPES` 与 hover 延迟逻辑。
|
||
|
||
### 9.3 流式阶段禁止交互
|
||
|
||
不要在 `DraftStreamingPreview` 中挂载 Tiptap 菜单:流式阶段 token 高频更新,挂载 `useWritingEditor` 易引发更新风暴(见 [DraftStreamingPreview.tsx](../src/open-canvas/components/ai-writing/DraftStreamingPreview.tsx) 文件头注释)。应等 `isDraftEditable` 后再走 `TextArtifactRenderer`。
|
||
|
||
---
|
||
|
||
## 十、相关文档
|
||
|
||
- [前端开发.md](./前端开发.md) §25.4 — Canvas / AI 写作路由与组件总表
|
||
- [ai-writing-用户自带大纲-测试用例.md](./ai-writing-用户自带大纲-测试用例.md) — AI 写作业务流程测试(含右侧草稿层级校验)
|
||
|
||
---
|
||
|
||
## 十一、依赖版本(摘录)
|
||
|
||
以 [package.json](../package.json) 为准,编辑器相关主要为:
|
||
|
||
- `@tiptap/core`、`@tiptap/react`、`@tiptap/starter-kit`:`^3.23.4`
|
||
- `@tiptap/extension-bubble-menu`:已安装但未接入滑词实现
|
||
- `tiptap-markdown`:Markdown 扩展
|
||
|
||
升级 Tiptap 大版本前,请对照官方迁移指南,并重点回归:`WritingBubbleMenu` 选区坐标、`WritingParagraphMenu` 的 `posAtCoords`、以及 `AiHighlightExtension` 与 StarterKit 扩展名冲突(勿重复注册 `underline`)。
|