# 与 Tiptap 的关系

沿用熟悉的 Core API，明确包身份与视图适配边界。

QuireKit 基于 Tiptap Core 的代码和扩展模型进行扩展开发，并保留相应许可证声明。它不是运行时安装 `@tiptap/core` 后的简单包装：Core 与 ProseMirror 包在 `@quirekit` 下统一维护，视图可显式接入。

## 可以沿用的概念

`new Editor()`、`Extension.create()`、`Node.create()`、`Mark.create()`、`.configure()`、`.extend()`、`editor.commands`、`editor.chain()`、`editor.can()`、输入规则、快捷键、存储与生命周期钩子保持熟悉的编写方式。

## 常用同名命令

| 用途 | 命令入口 | 前提 |
| --- | --- | --- |
| 读写内容 | `getJSON()`、`getHTML()`、`commands.setContent()`、`insertContent()`、`clearContent()` | 内容符合当前 Schema |
| 选区与焦点 | `focus()`、`blur()`、`setTextSelection()`、`setNodeSelection()`、`selectAll()` | 已挂载的视图与有效文档位置 |
| 标记与属性 | `setMark()`、`toggleMark()`、`unsetMark()`、`updateAttributes()` | 目标 Node / Mark 已注册 |
| 常用格式 | `toggleBold()`、`toggleItalic()`、`toggleHeading()`、`toggleBulletList()` | 对应扩展或 StarterKit |
| 历史 | `undo()`、`redo()` | 已注册历史扩展 |

除 `getJSON()` / `getHTML()` 外，表中命令均从 `editor.commands` 或 `editor.chain()` 访问。
这是常用迁移入口，不是所有生态包的兼容清单；参数与返回值以当前公开类型为准。

## 迁移对照

| Tiptap 项目 | QuireKit 项目 | 核查重点 |
| --- | --- | --- |
| `@tiptap/core` | `@quirekit/core` | 使用当前公开类型检查 |
| `@tiptap/starter-kit` | `@quirekit/starter-kit` | 逐项核对配置和已安装扩展 |
| `@tiptap/pm/*` / `prosemirror-*` | 对应 `@quirekit/pm-*` 或 `@quirekit/pm` | 一个实例使用同一份 PM 身份 |
| 默认 DOM 挂载 | 显式 `DomViewExtension` 和 `mode: 'dom'` | Canvas 等后端需要各自呈现能力 |
| Tiptap Vue / React 包装组件 | 宿主创建、挂载和销毁 Core | 不假定现有包装器无改动可用 |

API 高度一致不等于所有生态插件都能直接运行。依赖 DOM NodeView、浏览器几何、私有字段或原生 DOM 选区的插件，迁到 Canvas/SVG 时需要对应的视图实现；第三方包还要检查许可与依赖身份。

## 一个迁移后的扩展

这是本网站示例自己的快捷键扩展，不是内置插件。它使用同一命令表，加粗仍进入编辑器历史。

### core/shortcuts.ts

```ts
import { Extension } from "@quirekit/core";

/** A host-authored behavior extension using the same typed command registry as the toolbar. */
export const writingShortcuts = Extension.create({
  name: "writingShortcuts",
  /** @returns A keyboard binding that participates in the editor's existing history. */
  addKeyboardShortcuts() {
    return { "Mod-Shift-b": () => this.editor?.commands.toggleBold() ?? false };
  },
});

```

[快速开始](/guide/quick-start)运行了这个扩展；[扩展模型](/concepts/extensions)继续解释节点、标记与行为的差别。

## 产品开发时的状态与替换差异

外部原生 PM 状态通过 `editor.state.pm` 读取；raw command 回调的 `state` 仍是 PM facade。文件恢复使用 QuireKit 的 `replaceDocument()` 连同顶层属性替换；`setContent()` 保留普通内容替换语义。具体输入、返回和生命周期见 [Editor API](/api/editor)。