实例与配置参考

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

创建配置

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

@quirekit/classic-editor

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

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 等按字段合并；不能把数组更新理解为追加。具体规则见配置说明。

@quirekit/classic-editor

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

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、媒体字节和存储确认由应用分别管理。

@quirekit/classic-editor

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

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；此接口不会自动创建缺失面板。

@quirekit/classic-editor

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

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() 内执行一次同步的文档命令；失效目标会在写入前被拒绝。调用示例与迁移说明见文件操作。

@quirekit/classic-editor

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

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

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

@quirekit/classic-editor

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

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`	非正文界面状态的类型化控制器。

预设呈现更新

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

@quirekit/classic-editor

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

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 显式覆盖，优先于主题默认值。

媒体与字体

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

@quirekit/classic-editor

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

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。

@quirekit/classic-editor

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

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`	同时获取的字体资产数量上限。

@quirekit/classic-editor

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

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，浏览器注册与布局失效完成后返回。

@quirekit/classic-editor

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

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

成员	说明
`requestedFamily`	规范正文与字体控件保留的逻辑字体。
`renderedFamily`	进入通用字形回退前选定的具体字体；未解析时可为空。
`status`	当前异步可用性状态。
`source`	提供实际渲染字体的候选来源。