# Editor：状态、命令与生命周期

按开发任务查参数、返回值、状态形状与生命周期副作用。

先通过[完整产品工程](/build)理解这些方法如何共同工作。本页解释实际调用语义；完整源码签名在 [Core API](/api/core)。

## 创建与状态

`new Editor(options)` 同时确定 Schema、命令与创建期扩展。常用 options 是 `extensions`、`content`、`editable`、`element`、`mode`。在 SSR 阶段不传 DOM；需要视图时先安装对应 adapter，再显式挂载。更换不相容的 Schema 应创建新会话并迁移内容，不能靠 `setOptions({ extensions })` 热换整套模型。

```ts
const editor = new Editor({ extensions, content, editable: true })
const view = editor.mount({ element, mode: 'canvas', id: 'main' })
const pm = editor.state.pm
const { from, to } = pm.selection
const document = editor.state.doc
```

外部 `editor.state` 是 QuireKit 状态包装，原生 PM 状态在 `.pm`。raw command 回调里的 `state` 则是共享事务支持的 PM facade，可直接读 `state.selection`；不要把两种上下文混用。

创建选项、内容替换参数与全部事件的字段见[配置与事件参考](/api/options)；位置、光标和节点选区见[选区概念](/concepts/selection)。

### QuireEditorState

`@quirekit/core` · MIT

Core 持有的当前状态快照；pm 是原生 ProseMirror 状态，持久化正文应显式使用 getJSON()。

```ts
export interface QuireEditorState {
    readonly pm: PMEditorState;
    readonly doc: PMNode;
    readonly schema: Schema;
    readonly extensions: readonly QuireAnyExtension[];
    readonly storage: Readonly<Record<string, unknown>>;
}
```

**pm** — 当前原生 ProseMirror EditorState。

**doc** — 当前不可变 ProseMirror 文档。

**schema** — 当前文档使用的 Schema。

**extensions** — 按执行顺序排列的已安装扩展。

**storage** — 以扩展名称为键的实例存储。

## 读写方法

| 方法 | 输入 → 返回 | 使用与副作用 |
| --- | --- | --- |
| `getJSON()` | 无 → 规范 JSON | 保存、下载、转换时显式序列化，不用于每次输入的控件刷新 |
| `getHTML()` | 无 → HTML 字符串 | 由当前扩展的 serializer 决定；不包含分页 Canvas 的像素 |
| `getText(options?)` | 文本序列化选项 → string | 纯文本，可指定块间分隔符与节点序列化器 |
| `getMarkdown()` | 无 → string | 由已安装的 Markdown 转换规则决定 |
| `commands.setContent(content, options)` | 相容内容与解析/事件选项 → boolean | 普通正文替换，不负责更新完整文档顶层属性 |
| `commands.replaceDocument(content, options)` | 完整文档 → boolean | 文件恢复；连同顶层属性替换，选择回到开头，以 import origin/non-history 提交 |
| `commands.insertContent(content)` | 文字/HTML/JSON → boolean | 在当前选区插入，保留命令/历史语义 |
| `isActive(name, attrs?)` | Node/Mark 名与条件 → boolean | 只读格式查询，不代表可执行或已保存 |
| `setEditable(value, emitUpdate?)` | boolean → void | 更新编辑策略，默认可发 update；宿主仍须更新自身权限控件 |
| `setOptions(options)` | 部分 options → void | 更新实例选项；不要借此假定扩展重新编译或持久内容已迁移 |

`setContent` / `replaceDocument` 的非法内容策略应显式配置，恢复前仍需[独立校验](/guide/content)。`getHTML()` 需要 DOM document，服务端不能直接假定可用。命令 handled、真实 doc 变化与保存成功是三个不同结果。

## 命令的三种执行模式

```ts
editor.commands.toggleBold()                  // 立即执行
editor.chain().focus().toggleBold().run()      // 共享事务，run 提交
editor.can().toggleBold()                     // dry run，不 dispatch
editor.can().chain().toggleBold().run()        // dry-run chain
```

自定义 raw command 只修改提供的 `tr`，需要时检查 `dispatch`；不得在 `can()` 触发网络、弹窗或写真实状态。返回 false 不应被 UI 解读为成功。

`can()` 不是权限检查，`setEditable(false)` 也不会禁止所有程序命令。`run()` 返回 false 不会自动撤销其他链式步骤；具体边界见[命令与事务](/concepts/commands)。

### CommandProps

`@quirekit/core` · MIT

raw command 接收的共享事务上下文。can() 下没有 dispatch，不得触发外部副作用。

```ts
export type CommandProps = {
    readonly editor: QuireEditor;
    readonly tr: Transaction;
    readonly commands: SingleCommands;
    readonly can: () => CanCommands;
    readonly chain: () => ChainedCommands;
    readonly state: PMEditorState;
    readonly view: QuireMountedEditorView;
    readonly dispatch: ((transaction?: Transaction) => void) | undefined;
};
```

## 挂载与退出

| 方法 | 返回 | 生命周期 |
| --- | --- | --- |
| `mount({ element, mode, id?, editable? })` | mounted view | 首次为主视图，再次为额外视图，额外视图默认只读 |
| `mount(element)` | mounted view | 兼容简写选择 `html`，不等于原生 `dom`；产品教程使用显式对象 |
| `changeMode(mode, options?)` | 替换后的主视图 | 保留 Core 文档与历史，需要提前注册该模式 |
| `unmount()` | void | 释放主视图和额外视图，保留 Core 状态 |
| `destroy()` | void | 最终销毁；之后不能继续发命令或挂载 |

### QuireEditorMountOptions

`@quirekit/core` · MIT

挂载一个编辑器视图所需的宿主、模式与编辑权限。

```ts
export interface QuireEditorMountOptions {
    readonly element: HTMLElement;
    readonly mode: QuireViewMode;
    readonly id?: string;
    readonly editable?: boolean | undefined;
    readonly ownerDocument?: Document | undefined;
}
```

**element** — 宿主提供的视图挂载容器。

**mode** — 已注册的视图模式。

**id** — 可选的稳定视图身份，用于诊断。

**editable** — 额外视图是否可编辑共享状态。第一个视图是主视图，遵循编辑器级权限；额外视图默认只读。额外可编辑视图在拥有焦点时同步更新，其他视图在输入事务之外刷新。

**ownerDocument** — 创建子元素所用的 DOM Document。

### QuireEditorChangeModeOptions

`@quirekit/core` · MIT

替换主视图后端时的身份与 DOM 文档选项。

```ts
export interface QuireEditorChangeModeOptions {
    readonly id?: string;
    readonly ownerDocument?: Document | undefined;
}
```

**id** — 替换后主视图的可选稳定身份。

**ownerDocument** — 创建子元素所用的 DOM Document。

## 事件订阅

`on('transaction', listener)` 在事务接受后观察规范状态；`update` 用于内容变化，`selectionUpdate` 用于选区，`focus/blur` 只在需要焦点事实时订阅。始终用相同函数引用 `off`，并在销毁前释放宿主订阅。默认示例只用 transaction 做一次有界控件投影，另有保存状态通知。

### QuireEditorTransactionEvent

`@quirekit/core` · MIT

事务及附加事务应用完成后的事件载荷。

```ts
export interface QuireEditorTransactionEvent extends QuireEditorEventPayload {
    readonly transaction: Transaction;
    readonly appendedTransactions: Transaction[];
}
```

**transaction** — 最初应用的事务。

**appendedTransactions** — ProseMirror 插件追加的事务。

**editor** — 触发该事件的编辑器实例。

实际事件处理、dirty 与并发保存见[session 完整实现](/build/commands)。