# 编辑器 API

查询当前公开的创建选项、实例方法与增量事件。

类型签名从当前 MSFE 公共导出提取。初始化配置只在挂载时生效；之后通过实例方法修改状态。

## 创建函数

### createMsfeEditor

挂载前校验并取得源码；安装失败时，回滚所有已经建立的部分。
参数 options：编辑器挂载与扩展配置。
返回：可独立销毁的编辑器。

```ts
function createMsfeEditor(options: MsfeEditorOptions): MsfeEditor
```

## 创建选项

必须提供浏览器挂载元素 `parent`。`markdown`、`extensions`、`mode` 和宿主回调按需设置。

### MsfeEditorOptions

浏览器编辑器的创建选项；存储和文件解码由宿主应用负责。

```ts
export interface MsfeEditorOptions {
    readonly parent: HTMLElement;
    readonly markdown?: string;
    readonly documentId?: string;
    readonly mode?: MsfeMode;
    readonly readOnly?: boolean;
    readonly theme?: "light" | "dark";
    readonly extensions?: readonly AnyExtension[];
    readonly icons?: MsfeIconFactory;
    readonly codeLanguages?: readonly CodeLanguage[];
    readonly searchPanel?: ComponentViewRenderer<SearchPanelProps>;
    readonly componentHost?: MsfeComponentHost;
    readonly label?: string;
    readonly onChange?: (event: MsfeChangeEvent) => void;
    readonly onError?: (error: unknown) => void;
}
```

**parent** — 用于挂载一个 CodeMirror 视图的宿主元素。

**markdown** — 解码后的初始 Markdown 文本。

**documentId** — 可选的宿主文档标识；默认生成新的标识。

**mode** — 初始呈现模式，默认为 source。

**readOnly** — 显式设置 source / live 模式是否只读。

**theme** — 编辑器的初始配色主题。

**extensions** — 经过校验的功能扩展声明，仅作用于当前实例。

**icons** — 供折叠和搜索控件使用的共享设计图标渲染器。

**codeLanguages** — 按需加载的代码围栏语言目录；未指定或未知的语言保持纯文本。

**searchPanel** — 可选的搜索界面，挂载在现有框架及 Provider 宿主之下。

**componentHost** — 框架适配器提供的组件传送宿主；由使用方负责销毁。

**label** — 可编辑区域的无障碍名称。

**onChange** — 可选的源码增量变化监听器。

**onError** — 报告宿主监听器和 CodeMirror 插件产生的错误。

## 编辑器实例

`commands` 执行命令，`can()` 查询适用性，`chain()` 将多个操作组合为一次提交。命令不可用时检查返回值及 `lastCommandResult`。

### MsfeEditor

不依赖特定框架的 MSFE 实验性公共接口。

```ts
export interface MsfeEditor {
    readonly history: MsfeHistory;
    readonly scope: TaskScope;
    readonly documentScope: TaskScope;
    captureAnchor(range: MsfeSourceRange, policy?: RangePolicy): SourceAnchor;
    querySource(name: string, range?: MsfeSourceRange): SourceQuery;
    isActive(name: string, attrs?: Readonly<Record<string, unknown>>): boolean;
    getAttributes(name: string): Readonly<Record<string, unknown>> | null;
    getState<T>(slot: StateSlot<T>): T;
    subscribeState<T>(subscription: StateSubscription<T>): () => void;
    readonly commands: SingleCommands;
    readonly lastCommandResult: MsfeResult | undefined;
    readonly storage: Readonly<Record<string, unknown>>;
    readonly element: HTMLElement;
    readonly state: EditorState;
    readonly documentId: string;
    readonly revision: number;
    readonly mode: MsfeMode;
    readonly work: Readonly<MsfeWorkCounters>;
    getMarkdown(): string;
    captureTarget(): MsfeTarget;
    run(command: MsfeCommand, target?: MsfeTarget): MsfeResult;
    chain(target?: MsfeTarget): MsfeCommandChain;
    chain(commands: readonly MsfeCommand[], target?: MsfeTarget): MsfeResult;
    can(): CanCommands;
    can(command: MsfeCommand, target?: MsfeTarget): boolean;
    applyChanges(change: MsfeExternalChange): MsfeResult;
    replaceDocument(markdown: string, documentId: string): MsfeResult;
    setMode(mode: MsfeMode): void;
    setReadOnly(readOnly: boolean): void;
    setTheme(theme: "light" | "dark"): void;
    setSelection(selection: EditorSelection): void;
    updateViewState(update: MsfeViewStateUpdate): MsfeResult;
    scrollTo(position: number): void;
    focus(): void;
    undo(): boolean;
    redo(): boolean;
    onChange(listener: (event: MsfeChangeEvent) => void): () => void;
    destroy(): void;
}
```

**history** — 当前实例唯一的内容历史实现是否支持撤销、重做。

**scope** — 管理实例资源的编辑器生命周期作用域。

**documentScope** — 当前文档的生命周期作用域；即使宿主复用 documentId，换文档时也会替换此作用域。

**captureAnchor** — 参数 range：需要跟踪的源码范围。
参数 policy：显式指定的位置映射策略。
返回：可取消、可随修改映射的操作意图。

**querySource** — 参数 name：语义扩展名称。
参数 range：有界查询范围，默认为当前所有选区。
返回：结合解析状态得到的源码匹配结果。

**isActive** — 参数 name：语义类型。
参数 attrs：可选的精确字段约束。
返回：是否每个选区都有匹配的语义归属。

**getAttributes** — 参数 name：语义类型。
返回：选中内容一致的字段值；值混合、不存在或语法尚未确认时返回 null。

**getState** — 参数 slot：已安装的事务状态槽。
返回：当前不可变的状态值。

**subscribeState** — 参数 subscription：包含相等性比较和观察者的有界状态选择器。
返回：取消订阅的回调。

**commands** — 已安装的类型化命令；运行时缺少对应功能时返回 not-installed。

**lastCommandResult** — 最近一次具名命令或命令链的诊断结果；can() 查询不会改变此值。

**storage** — 各扩展在当前实例中的存储，以唯一标识为键。

**element** — 已挂载的编辑器外层元素；正文 DOM 仍由 CodeMirror 管理。

**state** — 当前不可变的 CodeMirror 状态。

**documentId** — 当前宿主文档标识。

**revision** — 实例内单调递增的版本号；显式替换文档时也会递增。

**mode** — 当前实际呈现模式，不包含组合输入期间延后的切换请求。

**work** — 确定性工作量计数的快照。

**getMarkdown** — 返回：遵循所保留文件格式策略的 Markdown 文本。

**captureTarget** — 返回：携带版本和选区方向的操作目标。

**run** — 参数 command：无副作用的操作规划函数。
参数 target：可选的已捕获目标。
返回：修改结果。

**chain** — 无参数或仅传入 target 时：创建新的类型化原子命令链。
传入 commands 时：按顺序原子执行规划函数，可同时指定已捕获的 target，返回修改结果。

**can** — 无参数时：返回无副作用的类型化命令查询接口。
传入 command 时：查询规划函数对可选 target 的适用性，不提交事务。

**applyChanges** — 参数 change：携带版本信息的外部修改。
返回：接受或拒绝修改的结果。

**replaceDocument** — 参数 markdown：新文档源码。
参数 documentId：新的宿主文档标识。
返回：重置历史和选区的结果。

**setMode** — 参数 mode：请求的呈现模式；组合输入结束前会延后切换。

**setReadOnly** — 参数 readOnly：是否只读，与呈现模式独立。

**setTheme** — 参数 theme：配色主题；切换时保留视图和历史。

**setSelection** — 参数 selection：包含方向信息的源码选区范围。

**updateViewState** — 参数 update：不修改源码的效果以及可选的选区。
返回：只读状态下也可接受的更新结果，或生命周期及无效更新诊断。

**scrollTo** — 参数 position：需要滚动到可见区域的逻辑源码位置。

**focus** — 按宿主请求将焦点移至文档。

**undo** — 返回：是否成功撤销一次历史事件。

**redo** — 返回：是否成功重做一次历史事件。

**onChange** — 参数 listener：源码增量变化观察者。
返回：取消订阅的回调。

**destroy** — 释放视图插件、资源和监听器；可重复调用。

## 文档变化

事件保留增量修改与来源信息，不默认序列化整篇文档。观察者异常通过宿主错误回调报告。

### MsfeChangeEvent

已接受的源码变化事件，不会立即序列化整篇文档。

```ts
export interface MsfeChangeEvent {
    readonly documentId: string;
    readonly revision: number;
    readonly changes: ChangeSet;
    readonly selection: EditorSelection;
    readonly origin: string;
}
```

**documentId** — 宿主可见的文档标识。

**revision** — 本次修改被接受后的源码版本号。

**changes** — 从修改前源码到已接受源码的精确变化映射。

**selection** — 修改后包含方向信息的选区。

**origin** — 修改来源：用户输入、命令、历史操作或宿主提供的来源。

## 按任务查方法

| 任务 | 组合 | 示例 |
| --- | --- | --- |
| 保存当前文件 | getMarkdown + onChange | [顺序保存](/guide/saving) |
| 接收同文档外部修改 | applyChanges + documentId / revision | [外部更新](/guide/saving) |
| 换文件 | replaceDocument + 新文档资源 | [生命周期](/guide/lifecycle) |
| 构建格式工具栏 | can / isActive / getAttributes / subscribeState | [工具栏](/customization/toolbars) |
| 一次复合操作 | chain(...).run() | [命令](/guide/commands) |
| 弹窗完成后写入 | captureTarget 或 captureAnchor | [目标管理](/guide/selection) |
| 自定义临时阅读状态 | defineState + updateViewState | [事务状态](/guide/state) |
| 排查预览和命令 | onError / lastCommandResult / work | [诊断](/guide/debugging) |

选择器和查询尽量读取最小所需范围。实例销毁后不要继续调用旧方法或把旧 state 交给新实例。