解析 `/parse`

import {
  createWikiparser,
  parseWikitext,
  createWikitextParser,
  WikitextParseError,
  DEFAULT_MAX_SOURCE_LENGTH,
} from "react-wikitext/parse";

/parse 加载默认解析器（wikiparser-node@1.48.1 浏览器包），不加载 React。解析是同步的。

parseWikitext

const document = parseWikitext(source, {
  pageName: "Example",
  retainSyntax: false,
});

使用默认配置的共享解析器，适合一次性解析或简单场景。

createWikiparser

const parser = createWikiparser({
  config: MEDIAWIKI_CONFIG,
  defaults: { pageName: "Example" },
});

const document = parser.parse(source, { maxSourceLength: 50_000 });

默认配置为 MEDIAWIKI_CONFIG，来源是 wikiparser-node@1.48.1 的站点配置快照。
配置在工厂创建时深拷贝并归一化；之后修改原对象不会影响解析器。
更换配置需要创建新的解析器。
库不导出最小配置；需要自定义时以默认配置为基础复制并调整字段。

解析选项

interface WikitextParseOptions {
  pageName?: string;
  maxSourceLength?: number; // 默认 100_000
  maxSyntaxNodes?: number; // 默认 50_000
  maxSemanticNodes?: number; // 默认 50_000
  maxDepth?: number; // 默认 1_000
  retainSyntax?: boolean; // 默认 false
}

选项	说明
`pageName`	页面上下文（例如模板或魔术字中的页面名）；库不自动生成
`maxSourceLength`	LF 归一化后的源码长度上限
`maxSyntaxNodes`	源码语法树节点上限
`maxSemanticNodes`	语义 AST 节点上限
`maxDepth`	语法树深度上限
`retainSyntax`	是否在文档中保留源码语法树

有效预算按“单次解析选项 → 创建时 defaults → 共享默认值”合并。解析前统一把 CRLF / CR 归一化为 LF，预算在归一化后检查。

retainSyntax 会显著增加内存与构建成本，只在需要源码坐标或 playground 语法树时开启。

返回的文档

interface WikitextDocument {
  source: string;
  ast: WikitextRoot;
  syntax?: WikitextSyntaxRoot;
  meta: WikitextDocumentMeta;
  diagnostics: WikitextDiagnostic[];
}

meta 包含：

parser / parserVersion。
pageName。
astSchemaVersion 与可选的 syntaxSchemaVersion。
sourceNormalized、originalLength、retainSyntax。

同一份源码使用不同配置或 pageName 时，可能得到不同的 AST；它们属于解析输入，不属于渲染选项。

自定义适配器

createWikitextParser 不加载默认 IIFE，适合接入其他解析器：

import { createWikitextParser, type WikitextParserAdapter } from "react-wikitext/parse";

const adapter: WikitextParserAdapter = {
  name: "my-parser",
  version: "1.0.0",
  parse(source, context) {
    // 必须返回符合 WikitextSyntaxRoot 的普通对象；
    // range 基于 LF 归一化后的源码，行列从 1 开始，offset 从 0 开始。
    return buildSyntaxRoot(source, context);
  },
};

const parser = createWikitextParser(adapter, {
  defaults: { pageName: "Example" },
});

适配器只把输入转换为源码语法树；归一化、预算合并、语义 AST 构建、诊断与 meta 由工厂完成。
context.limits 提供有效的 maxSyntaxNodes 与 maxDepth，适配器可以据此提前停止。
适配器返回后，工厂仍会校验结构、源码范围与预算。
适配器的 name / version 会写入文档 meta。

错误

class WikitextParseError extends WikitextError {
  constructor(
    code:
      | "SOURCE_TOO_LONG"
      | "SOURCE_TOO_COMPLEX"
      | "INVALID_CONFIG"
      | "PARSE_FAILED"
      | "PARSER_UNAVAILABLE",
    message: string,
    options?: { cause?: unknown },
  );
}

错误码	触发条件
`SOURCE_TOO_LONG`	归一化后的源码超过长度预算
`SOURCE_TOO_COMPLEX`	节点数或深度超过预算
`INVALID_CONFIG`	站点配置缺少必需字段
`PARSE_FAILED`	上游解析或语义构建失败
`PARSER_UNAVAILABLE`	默认 IIFE 未初始化全局解析器

节点数与深度上限属于内部防护阈值，只在触发错误时在 error.message 中给出实际生效值，不作为常量导出。

#解析 /parse

#parseWikitext

#createWikiparser

#解析选项

#返回的文档

#自定义适配器

#错误

#相关