# Core API

从 @quirekit/core 的公开 TypeScript 导出生成。

API 签名来自当前源码，中文说明与 JSDoc 对账。先读[快速开始](/guide/quick-start)与[扩展模型](/concepts/extensions)，再查具体入口。`Editor` 的文档、选区、命令与生命周期属于同一实例。

公开入口使用 `Editor`、`Extension`、`Node`、`Mark`；生成签名保留源声明中的 `QuireEditor` 等类名，它们指向同一导出。

先按任务查 [Editor 用法](/api/editor)、[扩展合同](/api/extensions)、[View 参数](/api/view)或[产品 API](/classic/api)；本页保留完整源码签名。

## 编辑器

### Editor

`@quirekit/core` · MIT

协调编辑器状态、扩展与命令执行。实例持有规范文档，负责挂载、更新与销毁生命周期。

```ts
export class QuireEditor {
    readonly instanceId: string;
    options: EditorOptions;
    isInitialized: boolean;
    readonly extensionManager: QuireExtensionManager;
    readonly utils: QuireEditorUtils;
    readonly extensions: readonly QuireAnyExtension[];
    isCapturingTransaction: boolean;
    isFocused: boolean;
    readonly markdown: MarkdownManager;
    readonly docx: DocxManager<QuireJSONContent, QuireDocxMark, QuireJSONContent>;
    constructor(options?: QuireEditorOptions);
    get state(): QuireEditorState;
    createReadOnlySnapshot(options?: QuireEditorReadOnlySnapshotOptions): QuireEditor;
    get mountedView(): QuireMountedEditorView | undefined;
    get view(): QuireMountedEditorView;
    get editorProps(): QuireEditorProps;
    get schema(): Schema;
    get storage(): Readonly<Record<string, unknown>>;
    get isDestroyed(): boolean;
    get isEditable(): boolean;
    get isEmpty(): boolean;
    get commands(): SingleCommands;
    chain(): ChainedCommands;
    can(): CanCommands;
    $pos(pos: number): NodePos;
    get $doc(): NodePos;
    $node(selector: string, attributes?: Record<string, unknown>): NodePos | null;
    $nodes(selector: string, attributes?: Record<string, unknown>): NodePos[];
    on<EventName extends keyof QuireEditorEvents>(event: EventName, callback: (...args: [
        QuireEditorEvents[EventName]
    ] extends [
        void
    ] ? [
    ] : [
        payload: QuireEditorEvents[EventName]
    ]) => void): this;
    once<EventName extends keyof QuireEditorEvents>(event: EventName, callback: (...args: [
        QuireEditorEvents[EventName]
    ] extends [
        void
    ] ? [
    ] : [
        payload: QuireEditorEvents[EventName]
    ]) => void): this;
    off<EventName extends keyof QuireEditorEvents>(event: EventName, callback?: (...args: [
        QuireEditorEvents[EventName]
    ] extends [
        void
    ] ? [
    ] : [
        payload: QuireEditorEvents[EventName]
    ]) => void): this;
    emit<EventName extends keyof QuireEditorEvents>(event: EventName, ...args: [
        QuireEditorEvents[EventName]
    ] extends [
        void
    ] ? [
    ] : [
        payload: QuireEditorEvents[EventName]
    ]): this;
    someProp<PropName extends keyof QuireEditorProps, Result>(propName: PropName, f: (value: NonNullable<QuireEditorProps[PropName]>) => Result): Result | undefined;
    someProp<PropName extends keyof QuireEditorProps>(propName: PropName): NonNullable<QuireEditorProps[PropName]> | undefined;
    someProp<PropName extends keyof QuireEditorProps, Result>(propName: PropName, f?: (value: NonNullable<QuireEditorProps[PropName]>) => Result): Result | NonNullable<QuireEditorProps[PropName]> | undefined;
    setOptions(options?: Partial<QuireEditorOptions>): void;
    setEditable(editable: boolean, emitUpdate?: boolean): void;
    setEditorProps(editorProps: Partial<QuireEditorProps>): void;
    getJSON(): QuireJSONContent;
    getHTML(): string;
    getText(options?: QuireGetTextOptions): string;
    getMarkdown(): string;
    getAttributes(name: string): Record<string, unknown>;
    isActive(name: string, attributes?: Record<string, unknown>): boolean;
    registerPlugin(plugin: Plugin, handlePlugins?: (newPlugin: Plugin, plugins: Plugin[]) => Plugin[]): PMEditorState;
    unregisterPlugin(nameOrPluginKeyToRemove: string | PluginKey | Array<string | PluginKey>): PMEditorState | undefined;
    mount(options: QuireEditorMountOptions): QuireMountedEditorView;
    mount(element: NonNullable<EditorOptions["element"]>): QuireMountedEditorView;
    mount(optionsOrElement: QuireEditorMountOptions | NonNullable<EditorOptions["element"]>): QuireMountedEditorView;
    unmount(): void;
    changeMode(mode: QuireViewMode, options?: QuireEditorChangeModeOptions): QuireMountedEditorView;
    setContent(content: QuireEditorContent, options?: QuireSetContentOptions): void;
    dispatchTransaction(transaction: Transaction): void;
    captureTransaction(callback: () => void): Transaction | null;
    destroy(): void;
}
```

## 扩展定义

### Extension

`@quirekit/core` · MIT

兼容 Tiptap 扩展模型的行为扩展基类，用于配置、命令、快捷键、插件与生命周期贡献。

```ts
export class Extension<Options extends object = object, Storage extends object = object> extends Extendable<Options, Storage, QuireExtensionConfig<Options, Storage>> implements QuireExtension<Options, Storage> {
    override type: QuireExtensionKind;
    constructor(config: QuireExtensionConfig<Options, Storage>, configuredOptions?: Partial<Options>);
    static create<Options extends object = object, Storage extends object = object>(config: QuireExtensionConfigInput<Options, Storage>): Extension<Options, Storage>;
    get kind(): QuireExtensionKind;
    get priority(): number | undefined;
    get keyboardShortcutPriority(): number | undefined;
    get topNodeName(): string | undefined;
    get commands(): AnyCommands | undefined;
    get keyboardShortcuts(): QuireKeyboardShortcutMap | undefined;
    get inputRules(): QuireInputRuleList;
    get pasteRules(): QuirePasteRuleList;
    get nodes(): QuireNodeSpecMap;
    get marks(): QuireMarkSpecMap;
    get plugins(): QuirePluginList;
    get canvasTextStyle(): QuireNodeCanvasTextStyleMap | undefined;
    get htmlSerializationTransforms(): QuireNodeHTMLSerializationTransformMap | undefined;
    get markdownSerializationTransforms(): QuireNodeMarkdownSerializationTransformMap | undefined;
    get layoutProviders(): readonly QuireLayoutProviderEntry[];
    get documentProfiles(): readonly QuireDocumentProfileEntry[];
    get selectionAdapters(): readonly QuireSelectionAdapterEntry[];
    get viewAdapters(): readonly QuireViewAdapter[];
    get viewEventHandlers(): QuireExtensionViewEventHandlerMap | undefined;
    get extensions(): readonly QuireAnyExtension[];
    get onBeforeCreate(): QuireExtensionBeforeCreateHook<Options, Storage> | undefined;
    get onCreate(): QuireExtensionCreateHook<Options, Storage> | undefined;
    get onUpdate(): QuireExtensionUpdateHook<Options, Storage> | undefined;
    get onDestroy(): QuireExtensionDestroyHook<Options, Storage> | undefined;
    get onFocus(): QuireExtensionFocusHook<Options, Storage> | undefined;
    get onBlur(): QuireExtensionBlurHook<Options, Storage> | undefined;
    get dispatchTransaction(): QuireExtensionDispatchTransactionHook<Options, Storage> | undefined;
    get transformPastedHTML(): QuireTransformPastedHTMLHook<Options, Storage> | undefined;
    get markdownTokenName(): string | undefined;
    get parseMarkdown(): QuireMarkdownConfigFields["parseMarkdown"] | undefined;
    get renderMarkdown(): QuireMarkdownConfigFields["renderMarkdown"] | undefined;
    get markdownTokenizer(): MarkdownTokenizer | undefined;
    get markdownOptions(): QuireMarkdownOptions | undefined;
    get attributes(): readonly QuireSchemaAttributeContribution[];
    override configure(options?: Partial<Options>): Extension<Options, Storage>;
    override extend<ExtendedOptions extends object = Options, ExtendedStorage extends object = Storage>(extension?: Partial<QuireExtensionConfig<ExtendedOptions, ExtendedStorage>>): Extension<ExtendedOptions, ExtendedStorage>;
}
```

### Node

`@quirekit/core` · MIT

兼容 Tiptap 扩展模型的节点基类，定义文档结构、属性以及相应行为与序列化。

```ts
export class Node<Options extends object = object, Storage extends object = object> extends Extendable<Options, Storage, QuireNodeConfig<Options, Storage>> implements QuireExtension<Options, Storage> {
    override type: QuireExtensionKind;
    constructor(config: QuireNodeConfigInput<Options, Storage>);
    get kind(): QuireExtensionKind;
    get priority(): number | undefined;
    get keyboardShortcutPriority(): number | undefined;
    get topNodeName(): string | undefined;
    get commands(): AnyCommands | undefined;
    get keyboardShortcuts(): QuireKeyboardShortcutMap | undefined;
    get inputRules(): QuireInputRuleList;
    get pasteRules(): QuirePasteRuleList;
    get extensions(): readonly QuireAnyExtension[];
    get nodes(): QuireNodeSpecMap;
    get marks(): QuireMarkSpecMap;
    get plugins(): QuirePluginList;
    get canvasTextStyle(): QuireNodeCanvasTextStyleMap | undefined;
    get layoutProviders(): readonly QuireLayoutProviderEntry[];
    get documentProfiles(): readonly QuireDocumentProfileEntry[];
    get selectionAdapters(): readonly QuireSelectionAdapterEntry[];
    get viewEventHandlers(): QuireExtensionViewEventHandlerMap | undefined;
    get onBeforeCreate(): QuireExtensionBeforeCreateHook<Options, Storage> | undefined;
    get onCreate(): QuireExtensionCreateHook<Options, Storage> | undefined;
    get onUpdate(): QuireExtensionUpdateHook<Options, Storage> | undefined;
    get onDestroy(): QuireExtensionDestroyHook<Options, Storage> | undefined;
    get onFocus(): QuireExtensionFocusHook<Options, Storage> | undefined;
    get onBlur(): QuireExtensionBlurHook<Options, Storage> | undefined;
    get dispatchTransaction(): QuireExtensionDispatchTransactionHook<Options, Storage> | undefined;
    get transformPastedHTML(): QuireTransformPastedHTMLHook<Options, Storage> | undefined;
    get markdownTokenName(): string | undefined;
    get parseMarkdown(): QuireMarkdownConfigFields["parseMarkdown"] | undefined;
    get renderMarkdown(): QuireMarkdownConfigFields["renderMarkdown"] | undefined;
    get markdownTokenizer(): MarkdownTokenizer | undefined;
    get markdownOptions(): QuireMarkdownOptions | undefined;
    get attributes(): readonly QuireSchemaAttributeContribution[];
    static create<Options extends object = object, Storage extends object = object>(config: QuireNodeConfigInput<Options, Storage>): Node<Options, Storage>;
    static create<Options extends object = object, Storage extends object = object>(config: NodeConfig<Options, Storage> | (() => NodeConfig<Options, Storage>)): Node<Options, Storage>;
    static create<Options extends object = object, Storage extends object = object>(config: QuireNodeConfigInput<Options, Storage> | NodeConfig<Options, Storage> | (() => NodeConfig<Options, Storage>)): Node<Options, Storage>;
    override configure(options?: Partial<Options>): Node<Options, Storage>;
    override extend<ExtendedOptions extends object = Options, ExtendedStorage extends object = Storage>(config?: Partial<QuireNodeConfig<ExtendedOptions, ExtendedStorage>>): Node<ExtendedOptions, ExtendedStorage>;
    override extend<ExtendedOptions extends object = Options, ExtendedStorage extends object = Storage, ExtendedConfig extends QuireExtendableConfig<ExtendedOptions, ExtendedStorage> = QuireExtendableConfig<ExtendedOptions, ExtendedStorage>>(config?: Partial<ExtendedConfig>): Node<ExtendedOptions, ExtendedStorage>;
}
```

### Mark

`@quirekit/core` · MIT

兼容 Tiptap 扩展模型的标记基类，定义行内文字格式、属性及相应行为与序列化。

```ts
export class Mark<Options extends object = object, Storage extends object = object> extends Extendable<Options, Storage, QuireMarkConfig<Options, Storage>> implements QuireExtension<Options, Storage> {
    override type: QuireExtensionKind;
    constructor(config: QuireMarkConfigInput<Options, Storage>);
    get kind(): QuireExtensionKind;
    get priority(): number | undefined;
    get keyboardShortcutPriority(): number | undefined;
    get topNodeName(): string | undefined;
    get commands(): AnyCommands | undefined;
    get keyboardShortcuts(): QuireKeyboardShortcutMap | undefined;
    get inputRules(): QuireInputRuleList;
    get pasteRules(): QuirePasteRuleList;
    get extensions(): readonly QuireAnyExtension[];
    get nodes(): QuireNodeSpecMap;
    get marks(): QuireMarkSpecMap;
    get plugins(): QuirePluginList;
    get canvasStyle(): QuireMarkCanvasStyleMap | undefined;
    get viewEventHandlers(): QuireExtensionViewEventHandlerMap | undefined;
    get onBeforeCreate(): QuireExtensionBeforeCreateHook<Options, Storage> | undefined;
    get onCreate(): QuireExtensionCreateHook<Options, Storage> | undefined;
    get onUpdate(): QuireExtensionUpdateHook<Options, Storage> | undefined;
    get onDestroy(): QuireExtensionDestroyHook<Options, Storage> | undefined;
    get onFocus(): QuireExtensionFocusHook<Options, Storage> | undefined;
    get onBlur(): QuireExtensionBlurHook<Options, Storage> | undefined;
    get dispatchTransaction(): QuireExtensionDispatchTransactionHook<Options, Storage> | undefined;
    get transformPastedHTML(): QuireTransformPastedHTMLHook<Options, Storage> | undefined;
    get markdownTokenName(): string | undefined;
    get parseMarkdown(): QuireMarkdownConfigFields["parseMarkdown"] | undefined;
    get renderMarkdown(): QuireMarkdownConfigFields["renderMarkdown"] | undefined;
    get markdownTokenizer(): MarkdownTokenizer | undefined;
    get markdownOptions(): QuireMarkdownOptions | undefined;
    get attributes(): readonly QuireSchemaAttributeContribution[];
    static create<Options extends object = object, Storage extends object = object>(config: QuireMarkConfigInput<Options, Storage>): Mark<Options, Storage>;
    static create<Options extends object = object, Storage extends object = object>(config: MarkConfig<Options, Storage> | (() => MarkConfig<Options, Storage>)): Mark<Options, Storage>;
    static create<Options extends object = object, Storage extends object = object>(config: QuireMarkConfigInput<Options, Storage> | MarkConfig<Options, Storage> | (() => MarkConfig<Options, Storage>)): Mark<Options, Storage>;
    override configure(options?: Partial<Options>): Mark<Options, Storage>;
    override extend<ExtendedOptions extends object = Options, ExtendedStorage extends object = Storage>(config?: Partial<QuireMarkConfig<ExtendedOptions, ExtendedStorage>>): Mark<ExtendedOptions, ExtendedStorage>;
    override extend<ExtendedOptions extends object = Options, ExtendedStorage extends object = Storage, ExtendedConfig extends QuireExtendableConfig<ExtendedOptions, ExtendedStorage> = QuireExtendableConfig<ExtendedOptions, ExtendedStorage>>(config?: Partial<ExtendedConfig>): Mark<ExtendedOptions, ExtendedStorage>;
}
```

## 命令描述与属性

### defineCommand

`@quirekit/core` · MIT

为命令声明面向 Agent 的描述，同时保留 addCommands 所需的命令工厂。definition 提供描述与执行工厂，返回携带冻结描述的命令工厂；命令按名称合并或覆盖时，描述仍跟随对应实现。

```ts
function defineCommand<Run extends CommandSpec>(definition: QuireCommandDefinition<Run>): Run
```

### mergeAttributes

`@quirekit/core` · MIT

从左向右合并 HTML 属性：class 去重，style 按 CSS 属性合并，其余属性由后值覆盖。objects 为待合并对象，返回合并后的属性对象。

```ts
function mergeAttributes(...objects: readonly (Readonly<Record<string, unknown>> | null | undefined)[]): Record<string, unknown>
```