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

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

创建与状态

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

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；不要把两种上下文混用。

创建选项、内容替换参数与全部事件的字段见配置与事件参考；位置、光标和节点选区见选区概念。

@quirekit/core

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

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 的非法内容策略应显式配置，恢复前仍需独立校验。getHTML() 需要 DOM document，服务端不能直接假定可用。命令 handled、真实 doc 变化与保存成功是三个不同结果。

命令的三种执行模式

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 不会自动撤销其他链式步骤；具体边界见命令与事务。

@quirekit/core

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

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	最终销毁；之后不能继续发命令或挂载

@quirekit/core

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

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。

@quirekit/core

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

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

成员	说明
`id`	替换后主视图的可选稳定身份。
`ownerDocument`	创建子元素所用的 DOM Document。

事件订阅

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

@quirekit/core

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

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

成员	说明
`transaction`	最初应用的事务。
`appendedTransactions`	ProseMirror 插件追加的事务。
`editor`	触发该事件的编辑器实例。

实际事件处理、dirty 与并发保存见session 完整实现。