如何将 Tiptap v1 升级到 v2

首先，Tiptap v1 不再受到支持，也不会收到进一步的更新。

如果您仍在使用 Tiptap v1，您可以在 这里 找到文档，但我们强烈建议您升级到版本 2。

是的，将您最喜欢的文本编辑器升级到新 API 是一项烦琐的工作，但我们确保您有足够的理由升级到最新版本。

• 在您的 IDE 中的自动补全（感谢 TypeScript）
• 超过 100 页的出色文档和 100 多个交互示例
• 积极开发，新功能正在制作中，每周发布新版本
• 大量新扩展
• 经过良好测试的代码库

新的 API 对您来说会非常熟悉，但确实有很多变化。为了使升级稍微容易一些，这里是您需要知道的所有信息：

卸载 Tiptap v1

整个包结构发生了变化，我们甚至迁移到了另一个 npm 命名空间，因此您需要在升级到 Tiptap 2 之前完全删除旧版本。

否则您会遇到异常，例如“看起来加载了多个版本的 prosemirror-model”。

npm uninstall tiptap tiptap-commands tiptap-extensions tiptap-utils

安装 Tiptap v2

一旦您卸载了旧版本的 Tiptap，安装新的 Vue 2 包、ProseMirror 库和启动包：

npm install @tiptap/vue-2 @tiptap/pm @tiptap/starter-kit

保持 Tiptap v2 更新

我们持续发布 Tiptap 的更新。

不幸的是，对于 npm，没有集成工具可以轻松更新您的依赖项，但您可以使用 npm-check 包：

npm install -g npm-check
npm-check -u

显式注册 Document、Text 和 Paragraph 扩展

Tiptap 1 尝试通过默认设置 useBuiltInExtensions: true 隐藏一些必需的扩展。该设置已被删除，您需要导入所有扩展。确保显式导入至少以下扩展：Document、Paragraph 和 Text。

import Document from '@tiptap/extension-document'
import Paragraph from '@tiptap/extension-paragraph'
import Text from '@tiptap/extension-text'

new Editor({
  extensions: [
    Document,
    Paragraph,
    Text,
    // 您的所有其他扩展
  ],
})

我们还删除了一些设置：dropCursor、enableDropCursor 和 enableGapCursor。这些现在是单独的扩展：Dropcursor 和 Gapcursor。您可能想加载它们，但如果不想，仅需忽略此项。

大多数扩展的新名称

我们切换到了 lowerCamelCase，因此有很多类型名称发生了变化。如果您将内容存储为 JSON，您需要遍历并重命名它们。对此表示歉意。

移除的方法

我们删除了 .state() 方法。放心，它仍然可以通过 editor.state 使用。

新的扩展 API

如果您为项目构建了一些自定义扩展，您需要重写它们以适应新的 API。放心，您可以保留很多工作。schema、commands、keys、inputRules 和 pasteRules 的功能与之前相同。只是注册它们的方法不同。

import { Node } from '@tiptap/core'

const CustomExtension = Node.create({
  name: 'custom_extension',
  addOptions() {
    …
  },
  addAttributes() {
    …
  },
  parseHTML() {
    …
  },
  renderHTML({ node, HTMLAttributes }) {
    …
  },
  addCommands() {
    …
  },
  addKeyboardShortcuts() {
    …
  },
  addInputRules() {
    …
  },
  // 还有更多 …
})

在我们的指南中阅读关于 构建自定义扩展的所有细节。

重命名的设置和方法

我们重命名了许多设置和方法。希望您可以轻松迁移到新 API。以下是变更列表：

重命名的命令

所有新扩展都有特定的命令来设置、取消和切换样式。因此，.bold() 现在变为 .toggleBold()。此外，我们切换到了 lowerCamelCase，以下是一些示例。哦，我们将 todo_list 重命名为 taskList，对此表示歉意。

MenuBar、BubbleMenu 和 FloatingMenu

请阅读专门的 创建菜单指南 以迁移您的菜单。

命令现在可以链式调用

大多数命令现在可以组合成一个调用。在大多数情况下，这比单独的函数调用要更简短。以下是一个使选定文本加粗的示例：

editor.chain().focus().toggleBold().run()

.chain() 用于开始一个新链，而 .run() 是实际执行链中所有命令所需的。有关 新 Tiptap 命令 的更多信息，请查阅我们的 API 文档。

.focus() 不再在每个命令上调用

我们曾试图通过 Tiptap 1 隐藏 .focus() 命令，并在每个命令上执行。这在特定用例中导致了问题，您想运行一个命令，但又不想聚焦编辑器。

在 Tiptap v2 中，您必须显式调用 focus()，并且可能在许多地方想这样做。以下是一个示例：

editor.chain().focus().toggleBold().run()

事件回调参数更少

新的事件回调具有更少的参数。相同的内容现在可以通过 this. 获得。 在这里阅读有关事件的更多信息。

协作编辑

用于协作编辑的参考实现现在使用 Y.js。这是完全不同的事情。您仍然可以使用 Tiptap 1 扩展，但请您自行将其调整为新的扩展 API。如果您这样做了，请记得与我们分享，以便我们从这里链接到它！

在我们的指南中了解有关 新的协作编辑体验 的更多信息。

标记不再支持节点视图

对于标记，节点视图在 ProseMirror 中 不被很好支持。Tiptap 1 也存在 相关问题。这就是我们在 Tiptap 2 中将其删除的原因。