更新记录

1.0.0（2026-07-19）

首发：自研高性能原生 Markdown 渲染核心（CommonMark 解析 + 代码高亮自包含 + 数学 KaTeX 标记交前端 + GFM 表格/删除线/任务列表

平台兼容性

uni-app x(5.14)

nex-markdown —— 高性能 Markdown 渲染

自研高性能原生 Markdown 渲染核心（CommonMark 解析 + 代码高亮 + 数学 KaTeX 标记），提供 uni-app 可调的 JS API。 支持 App 端（Android / iOS） 与 H5 端（双端同一核心、同真值，见下「H5 端」）；小程序不支持。

同一份 utssdk 插件同时支持 uni-app x（uvue） 与 经典 uni-app（vue3），无需分叉。 文本进 / HTML 出：Markdown 文本进，渲染好的安全 HTML 出（自由函数型，无状态）。 无额外系统依赖。

渲染策略（混合）

• 代码高亮自包含：代码块由内置高亮引擎渲染成带内联色的 HTML，前端无需额外 CSS / JS 即可显示彩色代码。
• 数学交前端：数学公式输出 KaTeX 标记 <span class="math math-inline">\(…\)</span> / math-display $$…$$，前端需挂 KaTeX auto-render 才会渲染成公式（见下「前端配套」）。
• GFM 扩展默认全开：表格 / 删除线 / 任务列表 / 脚注。
• 默认安全：源里的 raw HTML 默认转义为文本（防 XSS）；allowRawHtml=true 才透传。

API

对外核心 API 是 renderMarkdown；renderMarkdownAsync 是其后台线程异步变体（同一渲染逻辑）。

类型

// 渲染选项（全部字段可选，未传走默认）
type MdOptions = {
  codeHighlight?: boolean; // 代码块高亮（默认 true）
  codeTheme?: string;      // 内置高亮主题名（默认 "InspiredGitHub"）
  math?: boolean;          // 输出 KaTeX 数学标记（默认 true）
  allowRawHtml?: boolean;  // raw HTML 是否透传（默认 false = 转义，安全）
};

// 渲染结果（字段 camelCase）
type MdResult = { html: string; costMs: number };

参数与错误

• markdown：Markdown 源文本；超 32 MiB → InvalidParam（防巨输入 OOM）。
• options.codeTheme：内置高亮主题名（如 InspiredGitHub / base16-ocean.dark / Solarized (dark) 等）；未知主题 → InvalidParam。
• 代码块未知语言：降级为纯文本高亮，仍含原文，不报错。
• 高亮引擎内部异常已全部兜住 → Render 错误（不闪退）。
• MdResult.costMs：只计「渲染段」处理耗时（毫秒）。
• 错误经原生层 MarkdownException(Kotlin) / MarkdownError(Swift) 抛出（InvalidParam / Render），UTS 侧透传，可 try/catch。

用法

import { renderMarkdown } from "@/uni_modules/nex-markdown";

// 全默认（代码高亮 + 数学标记 + GFM，raw HTML 转义）
const r = renderMarkdown("# 标题\n\n```js\nconsole.log('hi')\n```");
console.log(r.html, r.costMs);

// 自定义选项（只传想改的字段，其余走默认）
const r2 = renderMarkdown("勾股 $a^2+b^2=c^2$", { codeTheme: "base16-ocean.dark", allowRawHtml: false });

// 大文档异步渲染（后台线程，不卡 UI）
renderMarkdownAsync(bigMarkdown).then((res) => {
  // 把 res.html 塞进 web-view / rich-text
}).catch((e) => {
  console.error(e);
});

前端配套（显示渲染结果）

renderMarkdown 返回的是 HTML 字符串，由前端决定怎么显示：

• 代码高亮：HTML 里已带内联色，无需额外 CSS，直接显示即彩色。
• 数学公式：HTML 里是 KaTeX 标记，需在承载它的 web-view 页面挂 KaTeX + auto-render（renderMathInElement(document.body)），公式才会渲染。rich-text 组件不跑 JS，数学标记只会显示原样文本——要数学必须走 web-view。
• 快速预览：用 <rich-text :nodes="html"> 可在原生侧直接渲染基础标签（标题/表格/列表/删除线/代码块结构），但不跑 KaTeX（数学不成公式）。

H5 端

• H5 端与 App 端由同一自研核心驱动，渲染真值一致（代码高亮 / KaTeX 标记 / 安全转义全同；无需额外静态资源部署）。
• 全部 API（renderMarkdown / renderMarkdownAsync）均可用。
• costMs 在 H5 端以 Date.now() 计，语义同移动端。
• renderMarkdownAsync 在 H5 端仍在 JS 主线程渲染（浏览器无移动端的后台线程）。
• H5 端引擎初始化是异步的：建议应用启动时（仅 H5 分支）await ensureReady() 一次， 过早调用会抛「尚未就绪」错误。
• 体积注意：内置高亮语法/主题集较全，H5 端产物约 3 MB 量级、明显大于其他插件；体积敏感场景请先评估。

平台与调试边界

• app-android / app-ios / H5（web）；各家小程序不支持。
• Android 本地真机调试原生库需 HBuilderX ≥ 4.26（自定义调试基座），云打包不受此限。
• iOS 端原生库含 Swift，宿主原生工程需开启「支持 Swift」。
• 最终 App 打包由 HBuilderX / @dcloudio CLI 完成。

范围说明（MVP）

• 一期：renderMarkdown 文本进 HTML 出 + 代码高亮 + 数学标记 + GFM + raw HTML 安全转义。
• 二期：renderMarkdownToFile（文件进出）/ TOC 目录 / 自定义主题 / 更细粒度的 HTML 净化。