@tuya-miniapp/rjs-markmap

在浏览器里把 Markdown 渲染成可交互的思维导图（markmap）。安装后直接 import 使用，无需额外拷贝静态资源或配置脚本地址。

适用场景与限制

• 仅浏览器：依赖 window / document，请勿在 Node SSR 中直接调用。
• ESM：请在支持 import 的脚本中使用（例如 <script type="module"> 或打包工具入口）。
• 使用 file:// 打开本地 HTML 时，模块加载常受浏览器策略限制，建议使用本地静态服务。

安装

npm install @tuya-miniapp/rjs-markmap

快速开始

准备一个占满或固定高度的容器（思维导图为 SVG，建议给容器明确高度，例如 height: 100vh）：

<div id="map" style="width: 100%; height: 100vh"></div>
<script type="module">
  import { createMarkmap } from '@tuya-miniapp/rjs-markmap';

  await createMarkmap({
    mount: '#map',
    markdown: ['# 主题', '## 分支 A', '- 要点 1', '## 分支 B', '- 要点 2'].join('\n'),
    theme: 'light',
  });
</script>

在 Vite / Webpack 等工程中用法相同：安装包后从包名 import 即可，无需把 vendor 拷到 public。

分步调用

需要更细控制时，可先等待引擎就绪，再单独设主题、渲染：

import {
  loadMarkmap,
  applyMarkmapTheme,
  renderMarkmap,
} from '@tuya-miniapp/rjs-markmap';

await loadMarkmap();
applyMarkmapTheme({ mount: '#map', theme: 'dark' });
await renderMarkmap({
  mount: '#map',
  markdown: '# 标题\n## 小节\n- 列表项',
});

renderMarkmap 内部也会确保已 loadMarkmap，因此多次渲染时可直接调用 renderMarkmap。

API 说明

loadMarkmap()

• 作用：等待 markmap 初始化完成。
• 返回：Promise<void>。
• 说明：多次调用返回同一 Promise，不会重复初始化。

renderMarkmap(options)

• 作用：在指定容器内根据 Markdown 绘制思维导图。
• 参数：
  • mount：string（CSS 选择器）或 HTMLElement，节点需已在文档中。
  • markdown：string，Markdown 正文。
• 返回：Promise<void>（内部会 await loadMarkmap()）。

applyMarkmapTheme(options)

• 作用：设置容器背景与文字颜色（浅 / 深）。
• 参数：
  • mount：同上。
  • theme：'light' | 'dark'，默认 'light'。

waitMarkmapRenderStable(options?)

• 作用：轮询根节点 svg.markmap 的 getBBox()，在尺寸连续若干次几乎不变时认为布局稳定；适合截图、导出前等待。
• 参数（均可选）：
  • maxAttempts：最大轮询次数，默认 50。
  • stableRequired：连续稳定次数，默认 3。
  • intervalMs：间隔毫秒，默认 100。
• 返回：Promise<'complete' | 'timeout'>。

createMarkmap(options)

• 作用：依次执行 loadMarkmap、可选 applyMarkmapTheme、renderMarkmap，可选再 waitMarkmapRenderStable。
• 参数：
  • mount、markdown：必填。
  • theme：可选，'light' | 'dark'。
  • waitStable：可选，默认 false；为 true 时在渲染后等待布局稳定。
• 返回：若 waitStable === true，返回 waitMarkmapRenderStable 的结果；否则为 Promise<void>。

本地演示

用任意静态服务打开页面即可（不建议直接 file:// 双击打开）：

npx serve .

若 Markdown 中含数学公式等高级能力，底层 markmap 可能按需请求额外资源（如 KaTeX），属 markmap 自身行为。

许可

• 本仓库中的封装源码：MIT（见 package.json）。
• vendor 内联的第三方脚本（markmap、d3 等）：以各文件头许可证为准。