# 实例与配置参考

查询 Classic 创建、更新、实例方法和界面控制器的全部公开字段。

本页用于查类型，入门步骤见[快速接入](/classic/quick-start)，选择配置与更新方式见[配置与生命周期](/classic/configuration)。类型从 `@quirekit/classic-editor` 公开导入；Vue 宿主的运行时创建使用 `/vue` 入口。

## 创建配置

`preset` 决定模型与默认能力，`plugins` 安装产品插件，`extensions` 追加正文扩展。`media` 与 `host` 是实例创建时的服务边界，不能通过更新配置替换。

### ClassicEditorOptions

`@quirekit/classic-editor` · AGPL-3.0-only

创建 Classic 产品实例的配置，包含模型、插件、界面与宿主服务。

```ts
export interface ClassicEditorOptions {
    readonly element?: HTMLElement | null | undefined;
    readonly document?: QuireEditorContent | undefined;
    readonly preset?: ClassicEditorPreset | undefined;
    readonly locale?: ClassicEditorLocale | undefined;
    readonly surfaceMode?: ClassicEditorSurfaceMode | undefined;
    readonly features?: ClassicEditorFeatureOptions | undefined;
    readonly plugins?: readonly ClassicEditorPlugin[] | undefined;
    readonly extensions?: readonly QuireAnyExtension[] | undefined;
    readonly editable?: boolean | undefined;
    readonly view?: ClassicEditorViewOptions | undefined;
    readonly canvasRuntime?: Readonly<Partial<CanvasMountedViewRuntimeOptions>> | undefined;
    readonly svgRuntime?: Readonly<Partial<SvgMountedViewRuntimeOptions>> | undefined;
    readonly theme?: QuireKitTheme | undefined;
    readonly shell?: ClassicEditorShellOptions | undefined;
    readonly ui?: ClassicEditorUiProfileOptions | undefined;
    readonly webFonts?: ClassicEditorWebFontOptions | false | undefined;
    readonly media?: ClassicEditorMediaServices | undefined;
    readonly host?: ClassicEditorHostServices | undefined;
}
```

**element** — 可选宿主元素；省略或传 null 创建未挂载实例。

**document** — 本次产品的初始规范内容，必须与预设 Schema 相容。

**preset** — 产品预设，默认使用 classicEditorPreset。

**locale** — 产品界面语言，默认为简体中文，不翻译已有正文。

**surfaceMode** — 创建时的产品界面受众模式，默认为面向用户的产品。

**features** — 在预设功能开关基础上逐字段覆盖。

**plugins** — 在预设插件之后安装的实例级产品插件。

**extensions** — 追加在预设之后的普通 Core 扩展。

**editable** — 是否允许用户编辑输入；程序命令还需应用写权限检查。

**view** — 产品渲染后端配置，默认 Canvas。

**canvasRuntime** — Canvas 运行配置覆盖；产品拥有的页面堆栈值仍优先。

**svgRuntime** — SVG 已挂载视图的运行配置覆盖。

**theme** — 完整 QuireKit 主题，优先于预设主题。

**shell** — 与预设合并的产品壳层布局与显隐配置。

**ui** — 动作界面的最终组成，按 surface 指定 contribution ID 列表。

**webFonts** — 外部字体库配置；传 false 关闭字体获取。

**media** — 实例级媒体注册与解析服务；省略时为内存仓储，持久化 JSON 的宿主需提供对应的持久媒体存储。

**host** — 创建时确定的宿主资源适配器；不能通过 update 替换。

## 更新配置

语言、只读和内置预设的主题更新保留编辑会话；结构配置仍重建 Core。`plugins` / `extensions` 替换实例数组，`features` / `shell` 等按字段合并；不能把数组更新理解为追加。具体规则见[配置说明](/classic/configuration)。

### ClassicEditorUpdateOptions

`@quirekit/classic-editor` · AGPL-3.0-only

Classic 产品更新选项。语言、只读及内置预设主题更新保留会话；结构配置重建 Core，未传正文时保留当前内容。

```ts
export interface ClassicEditorUpdateOptions {
    readonly document?: QuireEditorContent | undefined;
    readonly preset?: ClassicEditorPreset | undefined;
    readonly locale?: ClassicEditorLocale | undefined;
    readonly features?: ClassicEditorFeatureOptions | undefined;
    readonly plugins?: readonly ClassicEditorPlugin[] | undefined;
    readonly extensions?: readonly QuireAnyExtension[] | undefined;
    readonly editable?: boolean | undefined;
    readonly view?: ClassicEditorViewOptions | undefined;
    readonly canvasRuntime?: Readonly<Partial<CanvasMountedViewRuntimeOptions>> | undefined;
    readonly svgRuntime?: Readonly<Partial<SvgMountedViewRuntimeOptions>> | undefined;
    readonly theme?: QuireKitTheme | undefined;
    readonly shell?: ClassicEditorShellOptions | undefined;
    readonly ui?: ClassicEditorUiProfileOptions | undefined;
    readonly webFonts?: ClassicEditorWebFontOptions | false | undefined;
}
```

**document** — 替换正文；省略时保留当前内容。

**preset** — 替换产品预设；新正文必须与其 Schema 相容。

**locale** — 更新界面语言。

**features** — 与当前功能开关逐字段合并。

**plugins** — 替换实例级产品插件数组，而非追加。

**extensions** — 替换实例级 Core 扩展数组，而非追加。

**editable** — 更新用户输入的可编辑状态。

**view** — 与当前产品后端设置合并。

**canvasRuntime** — 与当前 Canvas 运行选项浅合并。

**svgRuntime** — 与当前 SVG 运行选项浅合并。

**theme** — 使用新的完整主题替换当前实例主题。

**shell** — 与当前壳层选项逐字段合并。

**ui** — 按 surface 更新最终项目组成；items 为替换列表。

**webFonts** — 替换外部字体库策略，或传 false 关闭。

## 产品实例

在 `update()`、`unmount()` 之后重新读取 `instance.editor`。不要缓存旧 Core 继续发命令。`getJSON()` 返回规范内容；产品名称、宿主文档 ID、媒体字节和存储确认由应用分别管理。

### ClassicEditorInstance

`@quirekit/classic-editor` · AGPL-3.0-only

createClassicEditor 返回的产品实例，负责挂载、配置、文件服务和最终销毁。

```ts
export interface ClassicEditorInstance {
    readonly isMounted: boolean;
    readonly isDestroyed: boolean;
    readonly editor: QuireEditor | undefined;
    readonly root: HTMLElement | undefined;
    readonly features: ClassicEditorResolvedFeatures;
    readonly locale: ClassicEditorLocale;
    readonly documentName: string;
    readonly backend: ClassicEditorViewBackend;
    readonly registry: ClassicEditorRegistrySnapshot;
    readonly ui: ClassicEditorUiController;
    readonly documentFontStatus: ClassicEditorDocumentFontStatus;
    readPageLayout?(document: PMNode): readonly ClassicEditorPageLayout[] | null;
    readonly fontLibrary: ClassicEditorFontLibrary | undefined;
    readonly media: ClassicEditorMediaServices;
    readonly hostResources: ClassicEditorHostResourceController;
    readonly tasks: ClassicEditorTaskFeedbackController;
    readonly resourceTasks: ClassicEditorHostResourceTaskController;
    setDocumentName(name: string): void;
    mount(element: HTMLElement): void;
    unmount(): void;
    update(options: ClassicEditorUpdateOptions): void;
    isContributionAvailable(behavior: ClassicEditorBehavior, payload?: unknown): boolean;
    canExecuteContribution(behavior: ClassicEditorBehavior, payload?: unknown): boolean;
    executeContribution(behavior: ClassicEditorBehavior, payload?: unknown, trigger?: ClassicEditorBehaviorTrigger): boolean | Promise<boolean>;
    refreshProductUi(): void;
    createReadOnlySnapshot(document: PMNode): QuireEditor;
    importDocument(serviceId: string, input: ClassicEditorImportArtifact, options?: ClassicEditorImportOptions): Promise<void>;
    exportDocument(serviceId: string): Promise<ClassicEditorExportArtifact>;
    getJSON(): QuireJSONContent;
    destroy(): void;
}
```

**isMounted** — 当前是否拥有已挂载的产品壳层与 Core。

**isDestroyed** — 是否已完成最终销毁。

**editor** — 当前挂载的 Core；未挂载时为 undefined，更新重挂载后需要重新读取。

**root** — 当前产品根元素；未挂载时为 undefined。

**features** — 当前解析后的产品功能开关。

**locale** — 当前界面语言。

**documentName** — 产品显示与导出使用的文档名称，独立于正文 JSON。

**backend** — 当前使用的渲染后端。

**registry** — 已安装产品能力的规范注册表。

**ui** — 管理非正文界面状态的类型化控制器。

**documentFontStatus** — 当前宿主正文的逻辑字体与实际渲染字体状态。

**readPageLayout** — 读取 document 所属最新排版的每页正文范围与使用空间；排版尚未就绪或属于旧文档时返回 null。

**fontLibrary** — 已挂载的外部字体库；未挂载时为 undefined。

**media** — 实例级媒体注册、身份分配与解析服务。

**hostResources** — 跨重新挂载保留的宿主资源协调器。

**tasks** — 跨重新挂载保留的任务反馈控制器。

**resourceTasks** — 跨重新挂载保留的并发资源工作流控制器。

**setDocumentName** — 更新产品名称而不改正文；name 为空时恢复当前语言的未命名标题。

**mount** — 挂载或重新挂载到 element；重新挂载创建新的 Core。

**unmount** — 释放壳层、Core 与 View，保留正文供后续重新挂载。

**update** — 更新配置。单独修改语言、只读和内置预设主题会保留会话；结构配置会重建 Core/View，之后重新读取 editor。

**isContributionAvailable** — 用 behavior 与可选 payload 查询一个直接绑定的旧式 contribution 行为是否存在；新功能使用 typed action。

**canExecuteContribution** — 用 behavior 与可选 payload 查询该 contribution 行为能否处理；不等同应用授权。

**executeContribution** — 执行直接绑定的 contribution 行为，接受 payload 和 trigger 并刷新界面；返回同步或异步 handled 结果。

**refreshProductUi** — 外部非正文状态变化后重新计算产品界面。

**createReadOnlySnapshot** — 为同 Schema 的 document 创建隔离预览 Core；返回未挂载、由调用方拥有的实例，关闭预览时销毁。

**importDocument** — 通过 serviceId 导入 input，并可在 options 中传 signal 取消准备。服务经同步 commit 提交；过期、取消或不可编辑时拒绝，返回异步完成。

**exportDocument** — 通过 serviceId 导出文件，返回包含字节或文本、文件名与 MIME 的产物。

**getJSON** — 显式读取当前规范 JSON；不包含独立产品名称或图片字节。

**destroy** — 最终销毁实例；可重复调用，销毁后不再使用。

## 界面控制器

缩放、标尺与侧栏使用 `instance.ui` 更新，保持当前文档和历史。`subscribe()` 返回释放函数，页面退出时调用。面板 ID 对应已安装的 sidebar contribution；此接口不会自动创建缺失面板。

### ClassicEditorUiController

`@quirekit/classic-editor` · AGPL-3.0-only

产品临时界面状态的控制器，调整缩放、标尺与侧栏而不改写正文。

```ts
export interface ClassicEditorUiController {
    readonly state: ClassicEditorUiState;
    setZoom(percent: number): void;
    setZoomMode(mode: ClassicEditorZoomMode): void;
    setRulerVisible(visible: boolean): void;
    setInvisibleCharactersVisible(visible: boolean): void;
    setHiddenTextVisible(visible: boolean): void;
    subscribe(listener: ClassicEditorUiStateListener): () => void;
    setSidebarVisible(side: "left" | "right", visible: boolean): void;
    toggleSidebar(side: "left" | "right"): void;
    openSidebarPanel(side: "left" | "right", panelId: string, options?: ClassicEditorSidebarOpenOptions): void;
    closeSidebar(side: "left" | "right"): void;
    setSemanticSnapshot(snapshot: ClassicEditorUiSemanticSnapshot): void;
}
```

**state** — 当前不可变的产品 UI 状态。

**setZoom** — 设置固定缩放百分比，有限数值限制在 25–400，并退出自动适应，不改正文历史。

**setZoomMode** — 设置 mode 为自动适应策略或手动缩放，不改正文历史。

**setRulerVisible** — 按 visible 显隐标尺，不重建文档视图。

**setInvisibleCharactersVisible** — 按 visible 显隐非打印字符提示，不改正文历史。

**setHiddenTextVisible** — 按 visible 切换隐藏文字检查视图，独立于文档格式与历史。

**subscribe** — 注册 listener，接收每个新的 UI 快照；返回移除监听的释放函数。

**setSidebarVisible** — 按 side 和 visible 设置指定侧栏的显隐。

**toggleSidebar** — 切换 side 指定侧栏的显隐。

**openSidebarPanel** — 打开 side 的已安装 panelId，options 可指定面板内语义目标。

**closeSidebar** — 关闭 side 指定的侧栏，保留其已选面板。

**setSemanticSnapshot** — 用 snapshot 替换共享的不可变选区、目标、动作与几何语义。

## 导入取消与提交

宿主通过 signal 取消准备过程。自定义服务必须在 `context.commit()` 内执行一次同步的文档命令；失效目标会在写入前被拒绝。调用示例与迁移说明见[文件操作](/classic/files)。

### ClassicEditorImportOptions

`@quirekit/classic-editor` · AGPL-3.0-only

宿主打开文档时可提供的取消选项。

```ts
export interface ClassicEditorImportOptions {
    readonly signal?: AbortSignal | undefined;
}
```

**signal** — 取消尚未提交的准备过程；该操作后续的 commit 会被拒绝，已接受的提交不会被撤销。

### ClassicEditorImportContext

`@quirekit/classic-editor` · AGPL-3.0-only

实例为文档导入服务提供的最终写入边界。解析完成后必须经 commit 同步提交。

```ts
export interface ClassicEditorImportContext extends ClassicEditorServiceContext {
    readonly signal: AbortSignal;
    commit(write: () => boolean): void;
}
```

**signal** — 操作、目标会话或宿主请求失效时中止的 signal。

**commit** — 复核原始目标后执行一次同步正文命令。write 只有在命令被接受后才返回 true；不能传异步回调。

**blockInsertion** — 仅捕获块插入呈现器时临时提供的目标。

**instance** — 拥有本次服务的产品实例。

**editor** — 本次捕获的已挂载 Core，写入前由 commit 再次确认。

**root** — 产品根元素。

**workspaceToolbarHost** — 壳层拥有的标尺旁工具宿主；无壳或自定义壳可能不提供。

**ownerDocument** — 创建贡献 DOM 的浏览器 Document。

**theme** — 当前不可变主题快照；兼容手写旧上下文时可缺省。

**features** — 已解析的功能开关。

**locale** — 已解析的界面语言。

**backend** — 当前渲染后端。

**ui** — 非正文界面状态的类型化控制器。

## 预设呈现更新

本上下文只用于刷新已有会话的呈现，不能替代安装新扩展或更改模型。宿主显式颜色覆盖仍应优先。

### ClassicEditorPresetPresentationContext

`@quirekit/classic-editor` · AGPL-3.0-only

预设刷新呈现时接收的现有编辑会话与配置。

```ts
export interface ClassicEditorPresetPresentationContext {
    readonly editor: QuireEditor;
    readonly theme: QuireKitTheme;
    readonly locale: ClassicEditorLocale;
    readonly canvasRuntime: Readonly<Partial<CanvasMountedViewRuntimeOptions>>;
    readonly svgRuntime: Readonly<Partial<SvgMountedViewRuntimeOptions>>;
}
```

**editor** — 必须保留 Schema、命令与历史的当前 Core。

**theme** — 当前完整产品主题。

**locale** — 当前界面语言。

**canvasRuntime** — 宿主的 Canvas 显式覆盖，优先于主题默认值。

**svgRuntime** — 宿主的 SVG 显式覆盖，优先于主题默认值。

## 媒体与字体

接入流程见[持久媒体](/classic/media)与[字体](/classic/fonts)。二进制资源、浏览器字体和文档逻辑身份分别管理。

### ClassicEditorMediaServices

`@quirekit/classic-editor` · AGPL-3.0-only

一个 Classic 实例及其挂载视图共享的媒体服务。

```ts
export interface ClassicEditorMediaServices {
    readonly sink: QuireMediaAssetSink;
    readonly registrar?: QuireMediaAssetRegistrar | undefined;
    readonly resolver: QuireMediaAssetResolver;
    createAssetId(kind: QuireMediaAssetKind): string;
}
```

**sink** — 插入正文前同步登记完整媒体字节的接口。

**registrar** — 为可能失败的操作提供 accept/rollback lease 的登记接口。

**resolver** — 注入各挂载后端的媒体解析接口。

**createAssetId** — 为 kind 对应的媒体分配非空、在底层资源库内唯一的稳定 ID。

### ClassicEditorWebFontOptions

`@quirekit/classic-editor` · AGPL-3.0-only

宿主为外部字体库提供的策略与来源配置。

```ts
export interface ClassicEditorWebFontOptions {
    readonly families: readonly ClassicEditorWebFontFamily[];
    readonly mountedFamilies?: readonly ClassicEditorMountedFontFamily[] | undefined;
    readonly sources?: readonly ClassicEditorWebFontSource[] | undefined;
    readonly persistence?: ClassicEditorFontLibraryPersistence | undefined;
    readonly catalogs: readonly QuireWebFontCatalog[];
    readonly cache?: QuireWebFontCache | undefined;
    readonly fetch?: QuireWebFontFetch | undefined;
    readonly maxAssetBytes?: number | undefined;
    readonly maxConcurrentAssets?: number | undefined;
}
```

**families** — 明确向用户公开可下载的字体元数据。

**mountedFamilies** — 应用样式已经注册的精确 CSS 字体。

**sources** — 字体中心展示的可搜索来源适配器。

**persistence** — 可选的本地字体中心状态存储。

**catalogs** — 宿主启用的有序 manifest 解析目录。

**cache** — 可选的持久字节缓存。

**fetch** — 可选的字体资产获取实现。

**maxAssetBytes** — 单份来源资产允许的最大字节数。

**maxConcurrentAssets** — 同时获取的字体资产数量上限。

### ClassicEditorFontLibrary

`@quirekit/classic-editor` · AGPL-3.0-only

挂载后用于显式安装和管理外部字体的产品接口。

```ts
export interface ClassicEditorFontLibrary {
    readonly families: readonly ClassicEditorWebFontFamily[];
    readonly sources: readonly ClassicEditorWebFontSource[];
    readonly importedFamilies: readonly ClassicEditorImportedWebFontFamily[];
    readonly mountedFamilies: readonly ClassicEditorMountedFontFamily[];
    readonly recentFamilies: readonly string[];
    rememberRecentFamily(family: string): void;
    getInstallations(): readonly QuireWebFontInstallation[];
    subscribe(listener: () => void): () => void;
    getSourceSettings(sourceId: string): ClassicEditorWebFontSourceSettings;
    configureSource(sourceId: string, settings: ClassicEditorWebFontSourceSettings): void;
    search(sourceId: string, query: string, subsets?: readonly string[]): Promise<readonly ClassicEditorWebFontFamily[]>;
    browse?(sourceId: string, query: string, limit: number, cursor?: string, subsets?: readonly string[]): Promise<ClassicEditorWebFontCatalogPage>;
    inspectCustomSource?(descriptorUrl: string): Promise<ClassicEditorCustomWebFontSourceRecord>;
    enableCustomSource?(record: ClassicEditorCustomWebFontSourceRecord): void;
    inspectStylesheetSource?(url: string, name?: string): Promise<ClassicEditorStylesheetFontSourceRecord>;
    enableStylesheetSource?(record: ClassicEditorStylesheetFontSourceRecord): void;
    removeCustomSource?(sourceId: string): void;
    previewFamily(family: ClassicEditorWebFontFamily): Promise<void>;
    importFamily(family: ClassicEditorWebFontFamily, download?: boolean): Promise<void>;
    removeFamily(family: ClassicEditorWebFontFamily | string): Promise<void>;
    getStatus(family: string): QuireWebFontStatus;
    install(family: string): Promise<void>;
}
```

**families** — 当前挂载中宿主公开的字体元数据。

**sources** — 当前可搜索的字体来源。

**importedFamilies** — 本浏览器产品中显式导入的字体。

**mountedFamilies** — 应用样式已经注册的字体。

**recentFamilies** — 最近使用的可见字体，从新到旧排列。

**rememberRecentFamily** — 将精确 family 记录为当前来源下的最近字体选择。

**getInstallations** — 返回按就绪顺序排列的只读安装快照；包括字节、本地或注册结果，仅本地记录不含可嵌入字节。

**subscribe** — 监听来源、导入和加载状态。listener 刷新产品界面，返回解除订阅函数。

**getSourceSettings** — 按 sourceId 读取当前来源的本地配置。

**configureSource** — 保存 sourceId 对应来源的完整 settings。

**search** — 使用 sourceId、query 与可选 subsets 搜索来源，返回字体元数据。

**browse** — 按来源、查询、limit、cursor 与可选 subsets 读取有界目录页；空 query 表示浏览全部。

**inspectCustomSource** — 检查 HTTPS descriptorUrl，返回可持久化的验证记录，不启用来源。

**enableCustomSource** — 启用已经验证的 record。

**inspectStylesheetSource** — 读取 url 对应的静态 font-face CSS，可提供 name；返回已校验快照，不下载字体或启用来源，支持 localhost。

**enableStylesheetSource** — 启用或更新已验证的静态目录 record。

**removeCustomSource** — 移除 sourceId 对应的自定义来源，保留已导入字体。

**previewFamily** — 下载并注册 family 供明确预览；可填充字节缓存，但不写入已导入字体记录。完成后浏览器可渲染真实字体。

**importFamily** — 显式导入来源 family；download 决定是否立即下载和注册。

**removeFamily** — 移除指定 family 记录或旧字体名及其缓存字节。

**getStatus** — 读取精确 family 对应的不可变加载状态。

**install** — 在用户或宿主明确操作后安装已公开的 family，浏览器注册与布局失效完成后返回。

### ClassicEditorDocumentFontStatus

`@quirekit/classic-editor` · AGPL-3.0-only

当前正文逻辑字体和实际渲染字体的产品状态。

```ts
export interface ClassicEditorDocumentFontStatus {
    readonly requestedFamily: string | null;
    readonly renderedFamily: string | null;
    readonly status: ClassicEditorDocumentFontStatusKind;
    readonly source: QuireFontSubstitutionCandidateSource | null;
}
```

**requestedFamily** — 规范正文与字体控件保留的逻辑字体。

**renderedFamily** — 进入通用字形回退前选定的具体字体；未解析时可为空。

**status** — 当前异步可用性状态。

**source** — 提供实际渲染字体的候选来源。