> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 解析 `/parse`

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

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

## parseWikitext

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

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

## createWikiparser

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

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

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

## 解析选项

```ts
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 语法树时开启。

## 返回的文档

```ts
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，适合接入其他解析器：

```ts
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。

## 错误

```ts
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` 中给出实际生效值，不作为常量导出。

## 相关

- 解析结果的查询、序列化与 AST 节点类型见 [`/ast`](/zh/api/ast.md)。
- 配置常量见 [`/configs`](/zh/api/configs.md)。
- 需要缓存，或需要避免阻塞主线程时，把解析放到 Worker 中执行，序列化后传回主线程。