# 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
(流式只读 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` 的 `` | **未使用** | 两套菜单均采用: 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`)。