#链接与图片

库默认不映射站点路由，也不加载图片。链接与媒体地址由宿主决定；库只做校验、清洗与渲染。

#链接

#默认行为

外链只允许 http:、https:、mailto:；无法安全解析的地址降级为被拦截的可读文本。绝对 HTTP(S) / mailto 外链默认带 target="_blank" 与 rel="nofollow noopener noreferrer"。

#resolveLink

import type { WikitextLinkResolver } from "react-wikitext/hast";

const resolveLink: WikitextLinkResolver = (request) => {
  if (request.kind === "internal") {
    const page = request.page ?? request.target.replace(/^:/u, "");
    return {
      href: `/wiki/${encodeURIComponent(page)}${request.fragment ? `#${request.fragment}` : ""}`,
      target: "_self",
    };
  }
  return undefined;
};

返回值语义：

request 提供 kind、target，内部链接还可能有 page 与 fragment。context 提供原始解析快照 document、当前工作树 ast 与当前节点 node。

下面的示例为内部链接提供站内地址，外链沿用默认处理：

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

export default function Demo() {
  return (
    <Wikitext
      source="参见 [[Wikitext|本库]] 与 [https://example.com 示例站点]。"
      lang="zh-CN"
      prepareOptions={{
        resolveLink: (request) =>
          request.kind === "internal"
            ? { href: "/zh/guide/quick-start", target: "_self" }
            : undefined,
      }}
    />
  );
}

#外部链接策略

• policy.allowRelativeLinks 默认为 true，允许解析函数返回相对地址。
• policy.externalLinkTarget 默认 "_blank"；设为 null 时外链不写 target。
• 相对链接在 _blank 下会加上 noopener noreferrer；最终整理会删除非法的 target 与未知的 rel 值。

#图片

#默认行为

文件节点默认渲染为带说明的占位。没有 resolveImage 时不会生成 <img>，库也不会请求任何图片地址。

#resolveImage

import type { WikitextImageResolver } from "react-wikitext/hast";

const resolveImage: WikitextImageResolver = (request) => ({
  src: `https://cdn.example.com/wiki/${encodeURIComponent(request.name)}`,
  alt: request.alt ?? request.name,
  ...(request.width === undefined ? {} : { width: request.width }),
  ...(request.height === undefined ? {} : { height: request.height }),
});

• 返回 null 保持占位；返回对象才授权图片资源。
• src 只允许 http: / https:；需要相对图片时显式设置 policy.allowRelativeImages: true。
• request 提供 name、parameters、解析出的 width / height、alt 与 caption。
• 宽高最终限制在 1–4096；解析函数返回的值优先。
• 生成的 <img> 固定带 loading="lazy" 与 decoding="async"，alt 缺省使用文件名。

#文件说明与链接

• 说明优先取显式 caption=，否则取未命名说明；说明中的链接、模板占位会递归渲染。
• 文件参数 link= 经 sanitizeHref 后生成链接；class= 作为附加类名。
• 行内文件使用 <span>，块级文件使用 <figure>；外层保留 mw-default-size、mw-halign-* 等兼容类名。

#授权与安全

准备阶段会记录解析函数实际返回并通过校验的图片地址。最终整理时：

• 未授权的 <img> 会被删除；有 alt 时保留文本，并产生 UNAUTHORIZED_IMAGE 诊断。resolver 产物使用 authorizedImages，源码 HTML 使用 policy.allowSourceImages，插件产物使用 policy.allowPluginImages。
• 插件不能通过插入任意 <img> 绕过默认不出图策略。
• URL 在写入属性前会先进行实体解码、去除控制字符，再按协议白名单校验。

需要预先处理 URL 时，可以使用 /hast 导出的 sanitizeHref、sanitizeImageUrl 与 sanitizedAttributesToProps。库在最终阶段仍会再次校验。

#策略与组件

如果只需要调整默认策略，不需要接入解析函数：

<Wikitext
  source={source}
  prepareOptions={{
    policy: {
      externalLinkTarget: null,
    },
  }}
/>

policy 与默认值做单层浅合并；extraTags、stripTags 是整体替换，不会追加。需要保留默认数组时以 DEFAULT_PREPARE_POLICY 为基准展开。

链接与文件的最终外观可以通过 HTML 组件或语义组件 自定义。自定义组件属于可信代码，输出不再经过库清洗。