更新记录

2.0.0（2026-11-08）

首个发布版本。l-markdown 主组件 + 8 个子组件（text-block / code / table / math / mermaid / webview / viewer / header）。

内容渲染

• Markdown 原文与预渲染 HTML 双入口，解析内核按平台自动选择
• 标题、段落、列表（含嵌套）、强调、行内代码、删除线、链接、图片、分割线
• 引用块，支持多层嵌套
• 代码块：18 门常用语言语法高亮、行号、按行数折叠、复制 / 下载 / 全屏；其余语言降级纯文本
• GFM 表格、Mermaid 图表（流程图 / 时序图 / 甘特图等），图片 / 代码双视图
• 数学公式：行内 $...$ / \(...\) 与块级 $$...$$ / \[...\]；公式字体从 cdnjs 加载，需联网，小程序需配置合法域名
• 脚注引用与回链

流式输出

• streaming 消息级标记，配合 renderInterval 节流（0 为自适应）
• 未闭合围栏的公式、图表、代码块显示源码占位，不误报错误
• 流式表格自动补分隔行，显示等高骨架
• 表格 / 代码块 / 图表 / 公式的复制、下载、全屏

交互

• 正文可选中复制、拖动光标自由选词
• 链接、图片、脚注点击事件；图片预览支持左右滑动
• 点击放大时内置全屏查看器
• 小程序端受 rich-text 限制，正文 / 表格内的链接、图片、脚注点击与图片预览不生效

主题与样式

• light / dark / auto 三主题，auto 跟随系统
• --l-md-* CSS 变量定制代码块、表格、头部、文本容器、Mermaid、公式占位与全屏查看器配色
• 移动端排版刻度：正文 16px / 1.7，标题 24~14px

性能与复用

• 渲染快照 snapshot / exportSnapshot()，历史消息重挂载免重复解析
• documentReady 与 blocksReady() 判断整篇内容是否稳定
• 代码块按行数折叠、未变块复用，降低流式重排开销
• 小程序端不注册 math / mermaid / webview 组件，控制主包体积

平台支持

• H5 / Web（uni-app 与 uni-app x）：全功能
• uni-app x App（Android / iOS / 鸿蒙）：公式走内置 MathJax，需在页面放置 <l-markdown-webview />
• 传统 uni-app App-Vue：公式、Mermaid 可用，无需代理；代码块高亮降级为纯文本
• 微信小程序等小程序：公式正常渲染；Mermaid 以纯文本代码块展示源码；三个组件不注册

依赖

lime-uasm-cmark（必需）、lime-style、lime-shared。

平台兼容性

uni-app(5.34)

uni-app x(5.34)

其他

name: lime-markdown Markdown 渲染组件 description: 跨端 Markdown 渲染组件，兼容 uni-app / uni-app-x，适配 AI 对话流式场景，支持代码高亮、表格、引用、Mermaid、数学公式。 tags:

• markdown
• 渲染
• 流式
• 代码高亮
• mermaid
• 公式 componentTag: l-markdown plugin: lime-markdown category: 业务组件 dependencies:
• lime-uasm-cmark
• lime-style

• lime-shared

lime-markdown

跨端 Markdown 渲染组件，兼容 uni-app 与 uni-app x。支持标题、列表、引用（含嵌套）、代码高亮、GFM 表格、Mermaid 图表、行内 / 块级数学公式，并针对 AI 对话的流式输出做了专门优化。

插件依赖：lime-uasm-cmark、lime-style、lime-shared

能力一览

安装方法

1. 在 uni-app 插件市场中搜索并导入 lime-markdown，会自动拉取以下依赖
2. 导入后重新编译项目
3. 在页面中使用 l-markdown 组件；也可先用 <lime-markdown /> 查看演示（见「快速预览」）

代码演示

基础用法

最小可用示例（Vue 3 / script setup）：

<template>
  <l-markdown :markdown="mdText" theme="auto" @link="onLink" @image="onImage" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { openMarkdownLink } from '@/uni_modules/lime-markdown'

const mdText = ref('# 标题\n\n正文 **加粗**、`行内代码`、[链接](https://uniapp.dcloud.net.cn/)')

function onLink(url: string): void {
  openMarkdownLink(url)
}
function onImage(src: string, alt: string): void {
  // 组件已自动调用 uni.previewImage（含全文图片列表），这里只做业务埋点
  console.log('preview', src, alt)
}
</script>

事件接入

完整事件接入（事件名均为小写，无连字符）：

<l-markdown
  :markdown="mdText"
  @link="onLink"
  @image="onImage"
  @footnote="onFootnote"
  @codecopy="onCodeCopy"
  @codedownload="onCodeDownload"
  @codefullscreen="onCodeFullscreen"
  @tablecopy="onTableCopy"
  @tabledownload="onTableDownload"
  @tablefullscreen="onTableFullscreen"
  @mermaidcopy="onMermaidCopy"
  @mermaiddownload="onMermaidDownload"
  @mermaidfullscreen="onMermaidFullscreen"
/>

上例中的处理函数按业务自行实现，各事件参数见下方「l-markdown Events」表。

代码块语言

括号内为可直接书写的别名；uts / arkts 复用 TypeScript，vue / wxml 复用 XML，wxss 复用 CSS。

为控制小程序包体，rust / csharp / objectivec / kotlin / php / dart / lua 默认不打包。这些语言仍可写进代码块，只是降级为纯文本；需要高亮时把它们加入 components/l-markdown-code/build-hljs.js 的 languages 数组并重跑该脚本。

App 端公式与图表

只有 uni-app x 的 App 原生端（Android / iOS / 鸿蒙）需要在页面根部放一次代理组件：

<template>
  <l-markdown-webview />
  <l-markdown :markdown="mdText" />
</template>

页面没有公式 / 图表时它不创建底层 web-view；首次需要时才创建，空闲 5 分钟自动释放。未放置时 x 端公式显示源码、图表显示降级提示。

Web（uni-app 与 uni-app x）和传统 uni-app 的 App-Vue 不需要放置该组件，公式与图表开箱即用。

流式输出

只给「当前正在增长的那条消息」传 streaming，历史消息保持 false：

<template>
  <l-markdown
    v-for="(msg, idx) in messages"
    :key="msg.id"
    :markdown="msg.body"
    :snapshot="msg.snapshot || ''"
    :streaming="isStreaming && idx === messages.length - 1"
  />
</template>

streaming 影响三处：表格显示等高骨架、代码块末行跳过高亮、块序列末尾预留占位以减少流式闪烁。renderInterval 控制节流间隔（默认 200ms，设 0 为按上一帧实耗自适应）。

历史消息快照

定稿后导出快照，下次挂载传 snapshot 即可跳过解析：

方式一，从组件实例导出（推荐）：

import { ref, watch, nextTick } from 'vue'

const mdRef = ref<{ documentReady: boolean; exportSnapshot(): string } | null>(null)
const isStreaming = ref(false)
const messages = ref<Array<{ id: string; body: string; snapshot: string }>>([])

watch(isStreaming, async (v) => {
  if (v) return
  await nextTick()
  const last = messages.value[messages.value.length - 1]
  if (last && mdRef.value?.documentReady) {
    last.snapshot = mdRef.value.exportSnapshot()
  }
})

方式二，宿主已持有块序列时直接序列化：

import { blocksReady, serializeSnapshot, restoreSnapshot } from '@/uni_modules/lime-markdown'

// 用 Parameters 取出块数组类型，无需导入内部类型
type Blocks = Parameters<typeof serializeSnapshot>[0]

function saveSnapshot(blocks: Blocks): string {
  return blocksReady(blocks) ? serializeSnapshot(blocks) : ''
}
function loadSnapshot(snap: string): Blocks | null {
  return restoreSnapshot(snap) // null 表示版本不匹配，正常解析即可
}

快照只消费一次，streaming 期间不生效，可跨主题、跨宽度复用。

API 文档

l-markdown Props

🎯 内容与主题

⚙️ 解析与流式

🎨 样式与无障碍

l-markdown Events

link / image / footnote 仅小程序端不触发；其它端（Web / App-Vue / uni-app x App）均正常，点击图片可弹出预览。详见「平台差异与限制」。

l-markdown 实例方法

插件入口公共方法

import {
  // 代理注册（扩展非 Web 端的图表 / 公式渲染器）
  registerMermaidProxy, getMermaidProxy, registerMathProxy, getMathProxy,
  // 链接与跳转
  openMarkdownLink, linkScheme,
  // 块就绪判断
  blocksReady, pendingBlockCount, markCompleteness,
  // 渲染快照
  serializeSnapshot, restoreSnapshot, SNAPSHOT_VERSION,
  // 主题 / 代码工具
  resolveTheme, getExtByLanguage, getCodeFileName, copyCode, downloadCode
} from '@/uni_modules/lime-markdown'

类型导出：MermaidRenderer、MathProxyRenderer、MathRenderResult、LinkScheme。

l-markdown-code Props

Events：copy（代码文本）、download（文件名）、fullscreen（true）

l-markdown-table Props

Events：copy（表格 HTML）、download（文件名）、fullscreen（true）、link（链接地址）、image（图片地址）

l-markdown-math Props

小程序端不可用：小程序不注册本组件，单独放置不会渲染公式。请通过 l-markdown 的 $$...$$ / $...$ 语法使用，行内与块级公式会自动渲染。

l-markdown-mermaid Props

小程序端不可用：小程序不注册本组件，Mermaid 源码以纯文本代码块展示。

Events：copy（源码）、download（文件名）、fullscreen（true）

l-markdown-viewer Props

Events：close

l-markdown-header Props

Events：action（按钮类型）　Slots：tabs（中间区域）

l-markdown-webview Props

仅 uni-app x 的 App 原生端需要，页面放一次即可。

l-markdown-text-block（内部组件）

由主组件内部使用，一般不直接引用。Props：html（块 HTML）、theme（light / dark，默认 light）、mathCode（块级公式源码，仅小程序生效）、streaming（默认 false）。Events：itemclick。

主题定制

theme 支持 light / dark / auto（跟随系统）。配色可通过 CSS 变量覆盖，变量名统一为 --l-md-<name>；下表每个变量都可单独设置、互不影响：

深色主题会覆写上述部分变量，定制时建议同时检查 .l-markdown--dark 下的取值。正文标题色、链接色、引用色、分割线色由内联样式固定，不提供 CSS 变量。

使用示例

方式一：父级或页面根节点设置（推荐）

CSS 变量可继承，在父级容器或页面根节点上设置，即可覆盖组件内卡片、代码块、表格等容器的配色。

<view class="md-wrapper">
  <l-markdown :markdown="mdText" />
</view>

<style>
.md-wrapper {
  --l-md-card-radius: 8px;
  --l-md-richtext-font-size: 15px;
  --l-md-code-bg: #f6f8fa;
}
</style>

方式二：通过 lStyle 在单个实例上设置

<l-markdown :markdown="mdText" :lStyle="{ '--l-md-code-bg': '#1e1e1e' }" />

⚠️ 样式作用域

自定义类名走 lClass、内联变量走 :lStyle，或统一写在父级容器上；正文标题 / 链接 / 引用 / 分割线颜色由内联样式固定，CSS 变量改不到。深色定制还需检查 .l-markdown--dark 下的覆写值。

平台差异与限制

补充限制：

• 小程序不注册 l-markdown-math / l-markdown-mermaid / l-markdown-webview，单独放置这三个组件不会渲染内容；这是为了控制主包体积。
• 小程序端不支持的点击仅限正文 / 表格内的链接、图片、脚注；代码块 / 表格 / Mermaid 头部的复制 / 下载 / 全屏 / 折叠按钮，以及长按选词、微信原生图片长按菜单均可正常使用。
• 若小程序端需要链接或图片交互，请在正文之外自行提供入口。
• 公式引擎在 Web / App-Vue / 小程序为 KaTeX，仅 uni-app x 的 App 原生端为 MathJax；\require{...} 等 MathJax 扩展宏在 KaTeX 下不支持。
• 下载能力：H5 走浏览器下载，App 写入用户目录，其它端提示不支持。
• 多实例可同页并存，样式默认隔离。

注意事项

• 公式字体走 CDN，必须联网；小程序需在后台配置 cdnjs.cloudflare.com 合法域名，App-Vue 离线会退化字体。
• snapshot 只消费一次，streaming 期间不生效；restoreSnapshot() 返回 null 表示版本不匹配，此时正常解析即可。
• 长代码或强流式场景可传 :line-numbers="false" 减少节点数；表格折叠行数由 maxRows 控制。
• 需要扩展代码高亮语言时，修改 components/l-markdown-code/build-hljs.js 的 languages 数组并重跑脚本，产物 lib/hljs-core.js 由脚本生成，请勿手改。
• 链接需带 http(s) / mailto: / tel: 协议，相对路径不触发 link；组件只抛事件、不接管导航，请用 openMarkdownLink() 或自行实现跳转。文档内锚点与脚注回链不走 link。
• image 事件触发前组件已调用 uni.previewImage（含全文图片列表，支持左右滑动），宿主不要重复调用，否则会把列表覆盖成单张。
• 脚注写法：正文写 [^1]、文末写 [^1]: 正文 定义；点击引用触发 footnote，回链「↩」不触发。
• 正文与引用块可选中复制、可拖动光标自由选词；App 端原生选择菜单会优先消费长按手势，建议只在自己发出的消息上弹菜单。
• 引用支持多层嵌套，但引用块内的 ul/li、pre、表格面板暂不带灰底。
• 行内公式覆盖上下标、分式、根号、希腊字母、常用运算符；不认识的命令或括号不配平时退回行内代码显示源码。
• 深色定制请同时检查 --l-md-* 变量在 .l-markdown--dark 下的覆写值；正文标题 / 链接 / 引用 / 分割线颜色不提供变量覆盖。

快速预览

导入插件后，可以直接使用以下标签查看完整演示：

<!-- 代码位于 uni_modules/lime-markdown/components/lime-markdown -->
<lime-markdown />

插件标签说明

文档链接

• 插件市场 - lime-markdown
• lime-uasm-cmark 解析引擎
• lime-style 主题变量

支持与赞赏

如果你觉得本插件解决了你的问题，可以考虑支持作者：

支付宝赞助	微信赞助

欢迎反馈与贡献。