展开 `/expand`

import { expandWikitext, WikitextExpandError } from "react-wikitext/expand";

/expand 在解析前展开受支持的模板与纯 wikitext 解析器函数。它加载解析器，不加载 React。展开是异步阶段。

签名

function expandWikitext(
  source: string,
  options: WikitextExpandOptions,
): Promise<WikitextExpandedDocument>;

interface WikitextExpandOptions {
  parser?: WikitextParser;
  pageName?: string;
  parseOptions?: Omit<WikitextParseOptions, "pageName">;
  resolveTemplate: WikitextTemplateResolver;
  maxDepth?: number;
  maxInvocations?: number;
  maxExpandedLength?: number;
  strict?: boolean;
  signal?: AbortSignal;
}

选项	默认值	说明
`parser`	默认解析器	可注入自定义解析器
`pageName`	—	原始页面名
`parseOptions`	—	原始与最终解析共用，`pageName` 由顶层字段提供
`resolveTemplate`	必填	模板源码解析函数
`maxDepth`	40	嵌套深度
`maxInvocations`	1,000	调用次数
`maxExpandedLength`	与原始页面长度上限相同（100,000）	展开后源码长度
`strict`	`false`	可恢复失败是否抛错
`signal`	—	取消信号

解析函数

本节把 resolveTemplate 回调称为解析函数。

interface WikitextTemplateRequest {
  title: string;
  pageName?: string;
  callerTitle?: string;
  invocation: WikitextRange;
  signal?: AbortSignal;
}

type WikitextTemplateResolver = (
  request: WikitextTemplateRequest,
) => string | null | undefined | Promise<string | null | undefined>;

null / undefined 表示模板不存在；空字符串是合法模板。
同一标题在一次展开中只解析一次；同一 title 必须返回稳定源码。
callerTitle 只作为上下文，不参与缓存键。
invocation 指向 original.source 中的顶层调用范围；嵌套请求复用所属顶层范围。
远程获取由解析函数完成；库不发起网络请求。

结果

interface WikitextExpandedDocument {
  original: WikitextDocument;
  document: WikitextDocument;
  expansion: WikitextExpansionInfo;
}

interface WikitextExpansionInfo {
  status: "complete" | "partial" | "fallback";
  records: readonly WikitextExpansionRecord[];
  diagnostics: readonly WikitextExpansionDiagnostic[];
}

interface WikitextExpansionRecord {
  kind: "template" | "parserFunction" | "argument";
  name: string;
  originalRange: WikitextRange;
  expandedRange: WikitextRange;
  status: "expanded" | "preserved";
}

original 是原始源码的解析快照。
document 是展开后源码的解析快照，可直接交给 prepareWikitext。
status：
- complete：全部调用已展开。
- partial：存在保留的调用或未解析依赖。
- fallback：最终源码解析失败，返回原始快照。
expansion.diagnostics 的坐标基于 original.source；document.diagnostics 合并最终解析诊断与换算后的展开诊断。

展开内容

支持模板嵌入与参数替换、include 标签、#if、#ifeq、#switch、#iferror、{{!}}、{{=}} 与隐式换行。

默认保留并产生诊断的调用：

#invoke 与 Lua。
subst 等嵌入修饰符。
#ifexist、#time 等依赖站点状态或外部运行环境的函数。

细节见模板展开指南。

预算与失败

单次调用超长：保留调用并记录 LENGTH_BUDGET_EXCEEDED。
连保留源码都超过 maxExpandedLength：抛 EXPANSION_TOO_LARGE。
strict: true 下预算超限：抛 EXPANSION_BUDGET_EXCEEDED。
默认模式下最终解析失败：退回原始有效快照，status: "fallback"。
取消时，Promise 以 WikitextExpandError 拒绝，错误码为 ABORTED，原始原因保存在 cause 中。

parseOptions.maxSourceLength、模板源码长度与 maxExpandedLength 分别生效；最终解析使用实际生效的 maxExpandedLength。

错误

class WikitextExpandError extends WikitextError {
  readonly templateTitle?: string;
  readonly range?: WikitextRange;
  constructor(
    code: WikitextExpandErrorCode,
    message: string,
    options?: { cause?: unknown; templateTitle?: string; range?: WikitextRange },
  );
}

常见错误码：

错误码	触发条件
`INVALID_EXPAND_OPTIONS`	选项不合法
`INCOMPATIBLE_PARSER`	注入的解析器不满足展开要求
`TEMPLATE_NOT_FOUND`	strict 模式下模板缺失
`TEMPLATE_RESOLVE_FAILED`	strict 模式下解析函数失败
`TEMPLATE_PARSE_FAILED`	strict 模式下模板源码解析失败
`TEMPLATE_LOOP`	strict 模式下检测到循环
`UNSUPPORTED_CALL`	strict 模式下遇到不支持的调用
`UNRESOLVED_DEPENDENCY`	strict 模式下依赖未解析
`EXPANSION_BUDGET_EXCEEDED`	strict 模式下预算超限
`EXPANSION_TOO_LARGE`	展开结果或保留源码超过长度上限
`FINAL_PARSE_FAILED`	strict 模式下最终解析失败
`ABORTED`	通过 `signal` 取消

与视图组合

import { expandWikitext } from "react-wikitext/expand";
import { prepareWikitext } from "react-wikitext/hast";
import { WikitextView } from "react-wikitext/view";

const expanded = await expandWikitext(source, { resolveTemplate });
const prepared = prepareWikitext(expanded.document);
const view = <WikitextView document={prepared} />;

展开后的文档已经是解析结果，不必再次解析。未展开而保留的调用仍按模板、函数或参数占位渲染。

#展开 /expand

#签名

#解析函数

#结果

#展开内容

#预算与失败

#错误

#与视图组合

展开 `/expand`

签名

解析函数

结果

展开内容

预算与失败

错误

与视图组合