For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/api/ast.md.
react-wikitext
  • 中文

      • AST /ast 

      import {
  AST_SCHEMA_VERSION,
  SYNTAX_SCHEMA_VERSION,
  RENDER_SCHEMA_VERSION,
  flattenNodes,
  findNodeById,
  findNodeAtOffset,
  getSourceText,
  toPlainText,
  isNodeType,
  getTemplateParameters,
  getFileParameters,
  normalizeSource,
  serializeWikitextDocument,
  restoreWikitextDocument,
} from "react-wikitext/ast";

      /ast 不加载解析器与 React，可以在服务端、Worker 或纯数据处理脚本中使用。

      节点基础

      interface WikitextNodeBase<TType extends string> {
  readonly type: TType;
  readonly id: string;
  readonly position?: WikitextPosition;
  readonly origin?: WikitextOrigin;
  readonly data?: Readonly<Record<string, unknown>>;
}
      • id 在单个快照内唯一，不保证跨编辑稳定。
      • position 的行列从 1 开始，offset 从 0 开始；生成节点会省略该字段。
      • origin 指向原始源码语法节点与范围。
      • data 用于自定义扩展数据。

      节点类型

      节点关键字段
      root / paragraph / strong / emphasischildren
      textvalue（已解码语义文本）
      headinglevel 1–6、children
      thematicBreak—
      linkkind: "internal" | "external" | "bareExternal"、target、可选 page / fragment、children
      filename、parameters、captionKind、attributes、可选 block、children
      listordered、children
      listItemchildren
      definitionList / definitionTerm / definitionDescriptionchildren
      table / tableRow / tableCellattributes；单元格另有 kind: "th" | "td"
      tableCaptionchildren
      templatename、displayName、可选 block、children（templateParameter）
      templateParametername、anonymous、可选 index、children
      parserFunctionname、可选 block、children
      argumentname、children（默认值）
      extensionname、attributes、selfClosing、block、可选 raw、children
      reference可选 name / group、attributes、可选 raw、children
      categorytarget、可选 sortKey
      behaviorSwitchname
      redirecttarget、可选 page / fragment
      htmlElementtag、attributes、selfClosing、block、可选 blocked、children
      codevalue、可选 language
      commentvalue
      unknownparserType、value、block、可选 reason

      扩展标签即使没有专门的默认展示，也使用 extension 节点并保留名称与内部原文，不会进入 unknown。

      自定义节点需要同时扩展 WikitextNodeMap 并在准备阶段注册转换函数；未注册转换函数的节点会产生诊断并降级为源码卡片。

      源码语法树

      retainSyntax: true 时，解析快照会包含 syntax：

      interface WikitextSyntaxNode {
  id: string; // 路径式 id，例如 "0.0.1"
  type: string; // 上游 token 类型
  range: WikitextRange; // [start, end)
  position: WikitextPosition;
  props: Readonly<Record<string, WikitextPrimitive>>;
  attributes: readonly WikitextSyntaxAttribute[];
  children: readonly WikitextSyntaxNode[];
}

      源码语法树供 playground、源码范围与源码映射使用；它不决定渲染结构。语义 AST 才是渲染输入。

      查询

      interface SourceDocumentLike {
  readonly source: string;
  readonly ast: WikitextRoot;
}
      函数行为
      flattenNodes(root)深度优先返回全部语义节点
      findNodeById(document, id)按 id 查找节点；找不到时返回 undefined
      findNodeAtOffset(document, offset, options?)返回包含该 offset 的最深节点；范围为 [start, end)；offset === source.length 返回根节点
      getSourceText(document, node)返回节点对应的 LF 源码片段
      toPlainText(node)返回已转换的语义文本，不再做实体解码
      isNodeType(node, type)泛型上下文中的类型收窄
      • 零长度节点默认不参与 findNodeAtOffset 的选择；可用 includeZeroLength 调整。
      • 生成内容没有 origin 时，getSourceText 返回空字符串。
      • 需要按 id 建索引时用 flattenNodes 自行生成 Map。
      • flattenNodes 与 findNodeById 的内部缓存在准备阶段重新编号后自动失效；插件在此之前持有的旧数组或 Map 不会被原地更新。
      • 查询转换后的节点时，必须使用渲染快照；不要用渲染快照里的 id 查原始解析快照。

      结构化辅助函数

      getTemplateParameters(node): WikitextParameter[]
getFileParameters(file): WikitextFileInfo

      getTemplateParameters 同时接受 template 与 parserFunction，返回参数节点、名称、是否匿名与从 1 开始的序号。

      getFileParameters 派生：

      • name、parameters、caption、captionNodes。
      • alt、link、lang、page、className、upright。
      • width / height（支持 200、200px、200x100px，最终显示时限制在 1–4096）。
      • format、alignment、verticalAlignment、border。

      说明文字优先取显式 caption=，否则取未命名说明；键名不会进入说明文本。

      源码归一化

      interface NormalizedSource {
  readonly source: string;
  readonly normalized: boolean;
  readonly originalLength: number;
}

const normalized = normalizeSource(raw, maxSourceLength);
      • 只做 CRLF / CR → LF，不改变其他字符。
      • DEFAULT_MAX_SOURCE_LENGTH 为 100,000；超过时抛 WikitextParseError("SOURCE_TOO_LONG")。
      • 所有坐标基于归一化后的 LF 源码；库不提供原源码的 offset 映射。

      序列化

      解析快照：

      const payload = serializeWikitextDocument(document);
const restored = restoreWikitextDocument(payload);

      渲染快照：

      import {
  serializeWikitextRenderDocument,
  restoreWikitextRenderDocument,
} from "react-wikitext/hast";

      恢复函数会校验结构版本、源码字符串、根节点、meta、headings、diagnostics 与 policy/labels 的完整形状，以及固定节点预算；渲染快照还会重新执行最终清洗与整理。快照内的 policy、labels 与 authorizedImages 属于可信边界，重新清洗只用于重建派生结构。不合法时抛：

      • 解析快照：WikitextError("INVALID_DOCUMENT")。
      • 渲染快照：WikitextError("INVALID_DOCUMENT")（与解析快照同一基类，不含 stage 字段）。

      版本常量

      常量当前值适用
      AST_SCHEMA_VERSION1语义 AST
      SYNTAX_SCHEMA_VERSION1源码语法树
      RENDER_SCHEMA_VERSION1渲染快照

      版本变化意味着快照结构不兼容；缓存或跨进程传输时应把版本写入缓存键。