---
title: "如何将 Tiptap v1 升级到 v2"
description: "将您的 Tiptap v1 项目升级到版本 2。了解更改以及如何迁移您的项目。"
canonical_url: "https://tiptap.zhcndoc.com/guides/upgrade-tiptap-v1"
---

# 如何将 Tiptap v1 升级到 v2

将您的 Tiptap v1 项目升级到版本 2。了解更改以及如何迁移您的项目。

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

如果您仍在使用 Tiptap v1，您可以在 [这里](https://v1.tiptap.dev/) 找到文档，但我们强烈建议您升级到版本 2。

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

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

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

## 卸载 Tiptap v1

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

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

```bash
npm uninstall tiptap tiptap-commands tiptap-extensions tiptap-utils
```

## 安装 Tiptap v2

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

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

## 保持 Tiptap v2 更新

我们持续发布 Tiptap 的更新。

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

```bash
npm install -g npm-check
npm-check -u
```

## 显式注册 Document、Text 和 Paragraph 扩展

Tiptap 1 尝试通过默认设置 `useBuiltInExtensions: true` 隐藏一些必需的扩展。该设置已被删除，您需要导入所有扩展。确保显式导入至少以下扩展：[`Document`](https://tiptap.zhcndoc.com/editor/extensions/nodes/document.md)、[`Paragraph`](https://tiptap.zhcndoc.com/editor/extensions/nodes/paragraph.md) 和 [`Text`](https://tiptap.zhcndoc.com/editor/extensions/nodes/text.md)。

```js
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`](https://tiptap.zhcndoc.com/editor/extensions/functionality/dropcursor.md) 和 [`Gapcursor`](https://tiptap.zhcndoc.com/editor/extensions/functionality/gapcursor.md)。您可能想加载它们，但如果不想，仅需忽略此项。

## 大多数扩展的新名称

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

| 旧类型                   | 新类型              |
| --------------------- | ---------------- |
| ~~`bullet_list`~~     | `bulletList`     |
| ~~`code_block`~~      | `codeBlock`      |
| ~~`hard_break`~~      | `hardBreak`      |
| ~~`horizontal_rule`~~ | `horizontalRule` |
| ~~`list_item`~~       | `listItem`       |
| ~~`ordered_list`~~    | `orderedList`    |
| ~~`table_cell`~~      | `tableCell`      |
| ~~`table_header`~~    | `tableHeader`    |
| ~~`table_row`~~       | `tableRow`       |
| ~~`todo_list`~~       | `taskList`（新名称！） |
| ~~`todo_item`~~       | `taskItem`（新名称！） |

## 移除的方法

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

## 新的扩展 API

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

```js
import { Node } from '@tiptap/core'

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

在我们的指南中阅读关于 [构建自定义扩展的所有细节](https://tiptap.zhcndoc.com/editor/extensions/custom-extensions.md)。

## 重命名的设置和方法

[我们重命名了许多设置和方法](https://tiptap.zhcndoc.com/editor/api/editor.md)。希望您可以轻松迁移到新 API。以下是变更列表：

| 旧名称             | 新名称         |
| --------------- | ----------- |
| ~~`autoFocus`~~ | `autofocus` |

## 重命名的命令

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

| 旧命令                      | 新命令                       |
| ------------------------ | ------------------------- |
| `.redo()`                | `.redo()`（未变化）            |
| `.undo()`                | `.undo()`（未变化）            |
| ~~`.todo_list()`~~       | `.toggleTaskList()`（新名称！） |
| ~~`.blockquote()`~~      | `.toggleBlockquote()`     |
| ~~`.bold()`~~            | `.toggleBold()`           |
| ~~`.bullet_list()`~~     | `.toggleBulletList()`     |
| ~~`.code()`~~            | `.toggleCode()`           |
| ~~`.code_block()`~~      | `.toggleCodeBlock()`      |
| ~~`.hard_break()`~~      | `.setHardBreak()`         |
| ~~`.heading()`~~         | `.toggleHeading()`        |
| ~~`.horizontal_rule()`~~ | `.setHorizontalRule()`    |
| ~~`.italic()`~~          | `.toggleItalic()`         |
| ~~`.link()`~~            | `.toggleLink()`           |
| ~~`.ordered_list()`~~    | `.toggleOrderedList()`    |
| ~~`.paragraph()`~~       | `.setParagraph()`         |
| ~~`.strike()`~~          | `.toggleStrike()`         |
| ~~`.underline()`~~       | `.toggleUnderline()`      |
| …                        | …                         |

## MenuBar、BubbleMenu 和 FloatingMenu

请阅读专门的 [创建菜单指南](https://tiptap.zhcndoc.com/editor/getting-started/style-editor/custom-menus.md) 以迁移您的菜单。

## 命令现在可以链式调用

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

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

`.chain()` 用于开始一个新链，而 `.run()` 是实际执行链中所有命令所需的。有关 [新 Tiptap 命令](https://tiptap.zhcndoc.com/editor/api/commands.md) 的更多信息，请查阅我们的 API 文档。

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

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

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

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

## 事件回调参数更少

新的事件回调具有更少的参数。相同的内容现在可以通过 `this.` 获得。 [在这里阅读有关事件的更多信息。](https://tiptap.zhcndoc.com/editor/api/events.md)

## 协作编辑

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

在我们的指南中了解有关 [新的协作编辑体验](https://tiptap.zhcndoc.com/collaboration/getting-started/install.md) 的更多信息。

## 标记不再支持节点视图

对于标记，节点视图在 ProseMirror 中 [不被很好支持](https://discuss.prosemirror.net/t/there-is-a-bug-in-marks-nodeview/2722/2)。Tiptap 1 也存在 [相关问题](https://github.com/ueberdosis/tiptap/issues/613)。这就是我们在 Tiptap 2 中将其删除的原因。