源码模型 API · Text Diagram

以下签名与说明从包的公开入口和 JSDoc 提取；中文说明与当前源码对账。Vue 组件接入见嵌入 Vue 工作台。

创建与读取

createTextDiagram

@quirekit/text-diagram

创建尚未保存的源码对象。id 为宿主标识；language 为初始语言；source 可选，省略时使用该语言的默认模板。返回 revision 为 0、preview 为 null 的规范对象。

function createTextDiagram(id: string, language?: TextDiagramLanguage, source?: string): TextDiagramEmbed

readTextDiagram

@quirekit/text-diagram

校验不可信的持久化输入 input，返回脱离原引用、不可变的规范源码对象。

function readTextDiagram(input: unknown): TextDiagramEmbed

serializeTextDiagram

@quirekit/text-diagram

校验并序列化 value，返回可用于原子基线比较的稳定字符串。

function serializeTextDiagram(value: TextDiagramEmbed): string

保存与围栏

prepareTextDiagramSave

@quirekit/text-diagram

从 original 基线、与源码绑定的 PNG 快照 snapshot 和纯文本 title 创建一次保存提案；返回新的完整修订，标题默认沿用原对象。

function prepareTextDiagramSave(original: TextDiagramEmbed, snapshot: TextDiagramRaster, title?: string): TextDiagramEmbed

textDiagramLanguage

@quirekit/text-diagram

解析代码围栏语言 input；返回支持的规范语言或 null，不按前缀猜测。

function textDiagramLanguage(input: string): TextDiagramLanguage | null

textDiagramMarkdown

@quirekit/text-diagram

接收规范语言 language 与精确源码 source；返回标准 Markdown 围栏，围栏长度确保不会被源码提前闭合。

function textDiagramMarkdown(language: TextDiagramLanguage, source: string): string

textDiagramTemplates

@quirekit/text-diagram

根据 locale 返回所有编辑器共用的真实本地引擎模板。语言只决定新模板中的文字，不翻译已有源码。

function textDiagramTemplates(locale?: string): readonly TextDiagramTemplate[]

公共数据类型

TextDiagramLanguage

@quirekit/text-diagram

内置的本地绘图语言。

export type TextDiagramLanguage = "mermaid" | "plantuml" | "dot";

TextDiagramSource

@quirekit/text-diagram

源码是唯一的可编辑权威；预览像素由源码派生。

export interface TextDiagramSource {
    readonly language: TextDiagramLanguage;
    readonly source: string;
    readonly revision: number;
}

成员	说明
`language`	明确的规范语法，不从源码内容推测。
`source`	精确 Unicode 源码，包含用户输入的空白。
`revision`	每次成功保存由宿主增加一次的修订号。

TextDiagramEmbed

@quirekit/text-diagram

结构化文档宿主持久化的带版本对象。

export interface TextDiagramEmbed {
    readonly type: "quirekit-text-diagram";
    readonly version: 1;
    readonly id: string;
    readonly title: string;
    readonly document: TextDiagramSource;
    readonly preview: TextDiagramPreview | null;
}

成员	说明
`type`	稳定的协议标识。
`version`	对象封装版本。
`id`	宿主对象的稳定标识。
`title`	用于无障碍命名的纯文本标题。
`document`	可编辑源码及其宿主修订号。
`preview`	对应精确源码的预览；尚未提交的新草稿可为 null。

TextDiagramPreview

@quirekit/text-diagram

可携带的静态图片，供文档正文和固定排版使用。

export interface TextDiagramPreview {
    readonly dataUrl: string;
    readonly width: number;
    readonly height: number;
}

成员	说明
`dataUrl`	自包含 PNG，不需要网络资源。
`width`	栅格图的固有宽度。
`height`	栅格图的固有高度。

TextDiagramSnapshot

@quirekit/text-diagram

与不可变源码快照绑定的 SVG。

export interface TextDiagramSnapshot {
    readonly language: TextDiagramLanguage;
    readonly source: string;
    readonly svg: string;
    readonly width: number;
    readonly height: number;
}

成员	说明
`language`	实际渲染的精确语法。
`source`	实际渲染的精确源码。
`svg`	经过净化的静态 SVG。
`width`	以 CSS 像素表示的自然宽度。
`height`	以 CSS 像素表示的自然高度。

TextDiagramRaster

@quirekit/text-diagram

冻结的源码及其栅格图；宿主必须将二者一起提交。

export interface TextDiagramRaster extends TextDiagramPreview {
    readonly language: TextDiagramLanguage;
    readonly source: string;
}

成员	说明
`language`	实际渲染的精确语法。
`source`	实际渲染的精确源码。
`dataUrl`	自包含 PNG，不需要网络资源。
`width`	栅格图的固有宽度。
`height`	栅格图的固有高度。

TextDiagramTemplate

@quirekit/text-diagram

以明确语法编写的真实可编辑模板。

export interface TextDiagramTemplate {
    readonly id: string;
    readonly label: string;
    readonly language: TextDiagramLanguage;
    readonly source: string;
}

成员	说明
`id`	稳定的模板标识。
`label`	请求语言中的显示名称。
`language`	绘图语法。
`source`	由实际渲染引擎消费的源码。

TextDiagramEditRequest

@quirekit/text-diagram

由宿主映射的编辑目标；界面不会直接写宿主文档。

export interface TextDiagramEditRequest {
    readonly document: TextDiagramEmbed;
    readonly commit: (document: TextDiagramEmbed) => TextDiagramCommitResult;
    readonly release: () => void;
}

成员	说明
`document`	脱离宿主可变引用的初始基线。
`commit`	接收包含完整源码与预览的 document 提案，返回同步的原子接受结果。
`release`	释放映射目标，不修改正文。

TextDiagramCommitResult

@quirekit/text-diagram

宿主对一次完整保存提案的原子接受结果。

export type TextDiagramCommitResult = "saved" | "conflict" | "readonly" | "missing";