编辑器 API

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

创建函数

@quirekit/msfe-core

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

function createMsfeEditor(options: MsfeEditorOptions): MsfeEditor

创建选项

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

@quirekit/msfe-core

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

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。

@quirekit/msfe-core

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

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`	释放视图插件、资源和监听器；可重复调用。

文档变化

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

@quirekit/msfe-core

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

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	顺序保存
接收同文档外部修改	applyChanges + documentId / revision	外部更新
换文件	replaceDocument + 新文档资源	生命周期
构建格式工具栏	can / isActive / getAttributes / subscribeState	工具栏
一次复合操作	chain(...).run()	命令
弹窗完成后写入	captureTarget 或 captureAnchor	目标管理
自定义临时阅读状态	defineState + updateViewState	事务状态
排查预览和命令	onError / lastCommandResult / work	诊断

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