#快速开始

本页把一段 wikitext 渲染到页面上。管线、快照与入口的取舍见工作原理。

#环境要求

• React >=18.2 <20（peer dependency）。
• 构建或服务端运行需要 Node >=18.18。
• 支持 ESM 与 CJS；Vite 与 webpack 5 的消费者构建已有测试覆盖。
• 运行时不依赖 Wikimedia、字体 CDN 或外部 API。

#安装

pnpm add react-wikitext@alpha

当前版本通过 alpha dist-tag 分发，安装命令需要显式指定通道；稳定版发布后可以直接使用 pnpm add react-wikitext。页面样式单独引入一次：

import "react-wikitext/styles.css";

::::note npm 包只包含 dist/、NOTICE 与 THIRD_PARTY_LICENSES。从源码构建与本地调试流程见贡献指南。 ::::

#最小示例

根入口的 Wikitext 组件一次完成解析、准备与渲染。引入一次样式文件即可：

import { Wikitext } from "react-wikitext";
import "react-wikitext/styles.css";

const source = `== 你好，wikitext ==
这是一段 '''wikitext'''，包含 [[内部链接|链接]] 和 ''斜体''。

* 第一项
* 第二项`;

export default function Article() {
  return <Wikitext source={source} lang="zh-CN" />;
}

Wikitext 渲染出的根节点是 div.wtr-view。lang 与 dir 会写入容器属性，用于排版与辅助技术。

::::warning Wikitext 与 WikitextView 依赖 React Context，只能在客户端组件中运行。根入口与 /view 的产物顶部已经带有 "use client" 指令，在 Next.js App Router 中直接使用即可；服务端只调用 /parse、/hast 等无 React 入口，链路见服务端准备 + 客户端渲染。 ::::

#你会看到什么

默认管线按下面的规则展示内容：

• 标题、段落、粗体、斜体、列表、定义列表、表格、代码块与参考文献正常渲染。
• 内部链接默认是无法导航的文本；需要地址时通过 resolveLink 返回。
• 外链使用源码中的安全 URL，并带 target="_blank" 与 rel="nofollow noopener noreferrer"。
• 模板、解析器函数与文件尚未求值时显示明确的占位，不推断内容。
• 图片默认只显示占位；只有 resolveImage 返回并通过校验的地址才会生成 <img loading="lazy">。
• 同页标题达到 4 个时自动生成目录；分类汇总到文末底栏。
• 未知结构降级为源码卡片，不会导致整页渲染失败。

逐项状态见支持矩阵，细节见渲染行为。

#下一步

• 工作原理：为什么解析与准备要分开，什么时候用 /view。
• 基本用法：显式管线、异步插件与组件覆盖。
• 链接与图片：接入站内路由与媒体服务。
• 服务端与框架：服务端准备、序列化与 hydration。
• 故障排查：占位、报错与常见配置问题。
• 入口总览：每个子路径导出的内容。