# Vue 与扩展 API

从公开 TypeScript 导出生成的签名与逐项说明。

`QuireMarkdown` 的属性见下方 `QuireMarkdownProps`，唯一事件为 `error(failure: MarkdownReadingError)`。

## 公开合同

### QuireMarkdownProps

`@quirekit/incremark/vue` · MIT

Vue 阅读组件，接受普通文本、流式文本或已有解析快照。

```ts
export interface QuireMarkdownProps extends MarkdownRenderOptions {
    readonly content?: string;
    readonly state?: EditorState;
    readonly identity?: string;
    readonly status?: MarkdownStatus;
    readonly options?: MarkdownOptions;
    readonly locale?: MarkdownLocale;
    readonly ssr?: "semantic" | "source";
}
```

**content** — 完整 Markdown 字符串，流式时为已接收的完整前缀。

**state** — 高级调用方提供的已接受快照，与 content 互斥。

**identity** — 消息或文档身份，独立于文本；变化时释放旧会话及资源。

**status** — 仅表示传输状态，结束和停止保留全部源码。

**options** — 本次会话稳定的源码扩展配置；重新配置时替换对象。

**locale** — 复制、任务和折叠控件使用的语言。

**ssr** — 默认 semantic 输出语义 HTML；source 延迟解析并先显示转义源码。

**cache** — 是否复用完整块投影，MarkdownRenderer 默认开启；关闭后解析仍增量进行。

**components** — 叠加到内置阅读默认值上的局部语义组件替换。

**html** — 显式启用经过净化的 HTML；默认 false 保留源码。

**renderNode** — 可信产品适配器；自定义源码通常使用 withMarkdownReading。

**renderNodeKey** — 返回覆盖适配器对未改变块之外的读取和外部状态的身份值；缺省保守重投影。

### MarkdownComponents

`@quirekit/incremark/vue` · MIT

阅读实例内的语义标签替换表；应用组件属于可信代码。

```ts
export type MarkdownComponents = Readonly<Partial<Record<string, Component | string>>>;
```

### MarkdownNodeInfo

`@quirekit/incremark/vue` · MIT

自定义框架组件收到的原生源码元数据。

```ts
interface MarkdownNodeInfo {
    readonly type: string;
    readonly from: number;
    readonly to: number;
}
```

**type** — 规范 Lezer 语法节点名。

**from** — 捕获的规范化源码范围起点，UTF-16 偏移，包含边界。

**to** — 捕获的规范化源码范围终点，UTF-16 偏移，不含边界。

### MarkdownHtmlOptions

`@quirekit/incremark/vue` · MIT

在固定 HTML 净化规则之上追加限制；不能开启可执行标签。

```ts
interface MarkdownHtmlOptions {
    readonly styles?: "safe";
    readonly allowedElements?: readonly string[];
    readonly allowLink?: (url: string) => boolean;
    readonly allowImage?: (url: string) => boolean;
}
```

**styles** — 显式开启不含资源加载的固定 CSS 子集；缺省删除 style 属性，style 标签仍禁止。

**allowedElements** — 净化标签的可选子集；不允许的包装标签被解包。

**allowLink** — 输入为已净化的目的地址，返回宿主是否允许该 HTML 链接。

**allowImage** — 输入为已净化的图片地址，返回宿主是否允许加载。

### MarkdownRenderOptions

`@quirekit/incremark/vue` · MIT

不改变源码解析的渲染配置。

```ts
export interface MarkdownRenderOptions {
    readonly cache?: boolean;
    readonly components?: MarkdownComponents;
    readonly html?: boolean | MarkdownHtmlOptions;
    readonly renderNode?: MarkdownNodeRenderer;
    readonly renderNodeKey?: (state: EditorState) => unknown;
}
```

**cache** — 是否复用完整块投影，MarkdownRenderer 默认开启；关闭后解析仍增量进行。

**components** — 叠加到内置阅读默认值上的局部语义组件替换。

**html** — 显式启用经过净化的 HTML；默认 false 保留源码。

**renderNode** — 可信产品适配器；自定义源码通常使用 withMarkdownReading。

**renderNodeKey** — 返回覆盖适配器对未改变块之外的读取和外部状态的身份值；缺省保守重投影。

### MarkdownReadingContext

`@quirekit/incremark/vue` · MIT

只读、经过验证的 Vue 阅读输入，提供源码范围内的递归 helper。

```ts
export interface MarkdownReadingContext<Attrs extends object = Readonly<Record<string, unknown>>> extends CoreContext<VNodeChild, Attrs> {
}
```

**name** — 已安装的语义 owner 名称。

**attrs** — 由源码 codec 读取并验证的只读字段。

**node** — 当前快照确认的语法节点，使用 UTF-16 源码偏移。

**document** — 只读规范源码与共享引用解析能力。

**locale** — 复制、任务和折叠控件使用的语言。

**renderInline** — 渲染该节点范围内的行内内容，from/to 不得切断子节点；无效范围抛出 RangeError。

**renderBlocks** — 渲染语义子块；omitted 指定省略的直接语法标记。

### MarkdownReadingDefinition

`@quirekit/incremark/vue` · MIT

附加到现有 source extension 的 Vue 呈现。

```ts
export interface MarkdownReadingDefinition<Attrs extends object = Readonly<Record<string, unknown>>, Resource = unknown> extends CoreDefinition<VNodeChild, Attrs, Resource> {
}
```

**cacheKey** — 返回涵盖 codec/render/load 在节点外读取与外部状态的身份值；常量声明仅局部读取，省略则禁用包含块的复用。

**load** — 接收捕获的上下文和取消信号，返回资源租约；替换或卸载时取消，迟到资源会释放，SSR 不调用。

**render** — 接收验证后的上下文与已接受资源，返回可信 Vue 节点；返回 undefined 保留精确源码。

### withMarkdownReading

`@quirekit/incremark/vue` · MIT

为配置完成的源码扩展添加快照阅读能力，保留编辑行为。extension 是已配置的 Node、Mark 或源码描述，definition 提供可信渲染和可取消资源加载；返回沿用语义 codec 与生命周期的可安装 MSFE 定义。

```ts
function withMarkdownReading<Attrs extends object = Readonly<Record<string, unknown>>, Resource = unknown>(extension: AnyExtension, definition: MarkdownReadingDefinition<Attrs, Resource>): AnyExtension
```

### MarkdownCacheLimits

`@quirekit/incremark/vue` · MIT

每个阅读器的保留预算，超额回退到普通投影。

```ts
interface MarkdownCacheLimits {
    readonly maxBlocks?: number;
    readonly maxSourceUnits?: number;
}
```

**maxBlocks** — 最多保留的完整顶层块数，默认 2048；0 禁用保留。

**maxSourceUnits** — 保留块源码范围总和上限，默认 2,000,000 UTF-16 单元，不是堆字节预算。

### MarkdownRenderWork

`@quirekit/incremark/vue` · MIT

最近一次投影的实际工作量，不包含解析、DOM diff 或绘制。

```ts
interface MarkdownRenderWork {
    visitedBlocks: number;
    reusedBlocks: number;
    projectedNodes: number;
    dependencyNodes: number;
    semanticChecks: number;
    cachedBlocks: number;
    cachedSourceUnits: number;
}
```

**visitedBlocks** — 访问的顶层候选块数。

**reusedBlocks** — 复用上次 Vue 输出的候选块数。

**projectedNodes** — 实际投影的节点分派数，含延迟的自定义子节点。

**dependencyNodes** — 建立新依赖摘要时遍历的语法节点数。

**semanticChecks** — 缓存命中时检查的引用、脚注及自定义 key 值数。

**cachedBlocks** — 当前投影后保留的块数。

**cachedSourceUnits** — 保留块源码跨度的 UTF-16 单元总和。

## 高级投影

### MarkdownRenderer

`@quirekit/incremark/vue` · MIT

Vue 阅读缓存；所有复用依据、预算和准备/提交合同由公共内核持有。

```ts
export class MarkdownRenderer extends CoreRenderer<VNodeChild> {
    constructor(limits?: MarkdownCacheLimits);
    override get work(): Readonly<MarkdownRenderWork>;
    override clear(): void;
    override prepare(state: EditorState, locale: MarkdownLocale, prefix?: string, onError?: (error: MarkdownReadingError) => void, options?: MarkdownRenderOptions): MarkdownRenderFrame<VNodeChild>;
    override render(state: EditorState, locale: MarkdownLocale, prefix?: string, onError?: (error: MarkdownReadingError) => void, options?: MarkdownRenderOptions): VNodeChild;
}
```

### renderMarkdown

`@quirekit/incremark/vue` · MIT

从已接受的源码快照生成完整 Vue 投影；locale 控制语言，prefix 隔离导航，onError 隔离错误，options 配置呈现。

```ts
function renderMarkdown(state: EditorState, locale: MarkdownLocale, prefix?: string, onError?: (error: MarkdownReadingError) => void, options?: MarkdownRenderOptions): VNodeChild
```