Vue 与扩展 API · QuireKit Markdown

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

公开合同

QuireMarkdownProps

@quirekit/incremark/vue

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

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

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

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

MarkdownNodeInfo

@quirekit/incremark/vue

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

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

成员	说明
`type`	规范 Lezer 语法节点名。
`from`	捕获的规范化源码范围起点，UTF-16 偏移，包含边界。
`to`	捕获的规范化源码范围终点，UTF-16 偏移，不含边界。

MarkdownHtmlOptions

@quirekit/incremark/vue

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

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

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

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

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

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

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

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

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

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

MarkdownCacheLimits

@quirekit/incremark/vue

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

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

成员	说明
`maxBlocks`	最多保留的完整顶层块数，默认 2048；0 禁用保留。
`maxSourceUnits`	保留块源码范围总和上限，默认 2,000,000 UTF-16 单元，不是堆字节预算。

MarkdownRenderWork

@quirekit/incremark/vue

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

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

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

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

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

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