mcpField
T
tiptap-editor

tiptap-editor

github.com/xiaolai开发878296 次安装今天更新
代码仓库

关于 tiptap-editor

为 vmark 开发提供 Tiptap API 使用模式的技能指南，帮助选择编辑器高级接口或直接使用 ProseMirror，并记录已知问题。

主要功能

  1. 01格式与块类型命令模式
  2. 02链式编辑命令用法
  3. 03ProseMirror 直接操作场景
  4. 04文档位置与块边界处理
  5. 05vmark 已知问题参考

适用场景

  1. 01实现文本格式和块类型变更
  2. 02组合多个编辑器操作
  3. 03处理文档遍历与光标位置

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/xiaolai/vmark --skill tiptap-editor

安装后在 Claude Code 中输入/tiptap-editor确认已加载。

附带文件references/examples.mdreferences/patterns.md

详细介绍

Tiptap 编辑器 API 模式

概述

本技能介绍 vmark 开发中正确的 Tiptap API 使用模式，帮助区分何时使用 Tiptap 高级 API，何时直接访问 ProseMirror。

何时使用 Tiptap API

始终优先使用 Tiptap API 进行以下操作：

  • 格式命令（粗体、斜体、下划线等）
  • 块类型更改（标题、段落、代码块）
  • 列表操作（项目符号、有序列表、切换、缩进／取消缩进）
  • 通过 Tiptap 表格扩展进行表格操作
  • 内容插入和替换
  • 编辑器状态查询（isActive、getAttributes）

应使用的 Tiptap 模式：

// Direct commands
editor.commands.toggleBold()
editor.commands.setHeading({ level: 2 })
editor.commands.setContent(doc, { emitUpdate: false })

// Chained commands (for multiple operations)
editor.chain().focus().setHeading({ level: 2 }).run()
editor.chain().focus().toggleMark("underline").run()

// State queries
editor.isActive("blockquote")
editor.isActive("heading", { level: 2 })
editor.getAttributes("link")

何时适合直接使用 ProseMirror

以下情况可直接使用 ProseMirror：

  • Markdown 转换层（proseMirrorToMdast.ts、mdastToProseMirror.ts）
  • 多光标／选区子类化（MultiSelection.ts）
  • 自定义节点视图
  • 底层事务操作
  • Schema 层级操作

vmark 中的已知问题

1. cursorHandlers.ts 块边界问题

src/hooks/mcpBridge/cursorHandlers.ts 使用 doc.textContent，这会将文档展平并丢失块边界。正确做法是使用 $pos 辅助方法：

// WRONG - loses block structure
const text = doc.textContent;

// RIGHT - respects block boundaries
const $pos = doc.resolve(from);
const currentNode = $pos.parent;
const blockStart = $pos.before($pos.depth);
const blockEnd = $pos.after($pos.depth);
2. 所见即所得编辑后的光标同步漂移

sourceLine 属性仅在初始解析时设置。通过所见即所得编辑添加或移除块后，行号将不再与源内容匹配。这是一个已知限制。

3. HtmlNodeView.ts 存储问题

src/plugins/markdownArtifacts/HtmlNodeView.ts 将光标信息写入了错误的存储区。

参考资料

  • references/patterns.md - 详细的 API 模式和 $pos 用法
  • references/examples.md - vmark 代码库中的实际代码示例

工作流

  1. 确定操作类型（格式、块、选区、遍历）
  2. 检查 Tiptap 是否提供内置命令
  3. 单次操作使用 editor.commands.xxx()
  4. 需要焦点或需要链式调用时，使用 editor.chain().focus().xxx().run()
  5. 遍历节点时，使用 doc.resolve(pos) 获取 $pos 辅助方法
  6. 查询状态时，使用 editor.isActive() 或 editor.getAttributes()

评论

支持 Markdown