Skip to content

构建产物介绍

Jump to bottom
阿菜 Cai edited this page Jan 28, 2026 · 13 revisions

打包产物与使用指南

简介

包名 作用
cherry-markdown.js 完整包，较大，包含 cherry 所有功能（工具栏、左侧编辑器、右侧预览器、所有插件）
cherry-markdown.esm.js 完整包 ESM 版本，与 .js 版本功能相同，推荐在现代项目中使用
cherry-markdown.core.js 核心包，相比完整包，只少了 mermaid 功能，包大小小了 50% 以上
（也可以通过命名导入 { core } 再手动注册 mermaid 插件）
cherry-markdown.core.esm.js 核心包 ESM 版本，与 .js 版本功能相同
cherry-markdown.engine.js 解析引擎包，可以理解为只提供了将 md 解析成 html 的 API，包含 mermaid 插件
cherry-markdown.engine.esm.js 解析引擎包 ESM 版本，与 .js 版本功能相同
cherry-markdown.engine.core.js 解析引擎包，提供了将 md 解析成 html 的 API，不包含 mermaid 插件
cherry-markdown.engine.core.esm.js 解析引擎包 ESM 版本，与 .js 版本功能相同
cherry-markdown.css 样式文件，包括了编辑区、工具栏、预览区等样式
cherry-markdown.markdown.css 预览区内的样式文件，会对 class="cherry-markdown" 元素里的 html 应用样式

推荐使用统一入口导入：

// 完整版
import Cherry from 'cherry-markdown';

// 核心版
import { core } from 'cherry-markdown';

// 引擎版
import { engine } from 'cherry-markdown';

// 单独导入插件
import { MermaidPlugin } from 'cherry-markdown';

构建产物表格

前缀 后缀 模块 语言版本 UI 核心引擎 大体积依赖 建议使用环境
cherry-markdown .js umd es5 ✅ ✅ ✅ Web
cherry-markdown .esm.js esm es2015 ✅ ✅ ✅ Web / Modern Build
cherry-markdown.core .js umd es5 ✅ ❌ ❌ Web
cherry-markdown.core .esm.js esm es2015 ✅ ❌ ❌ Web / Modern Build
cherry-markdown.engine .js umd es5 ❌ ✅ ✅ Web
cherry-markdown.engine .esm.js esm es2015 ❌ ✅ ✅ Web / Modern Build
cherry-markdown.engine.core .js umd es5 ❌ ❌ ❌ Web
cherry-markdown.engine.core .esm.js esm es2015 ❌ ❌ ❌ Web / Modern Build

注意事项

1. 自定义语法失效问题

有用户反馈只引入 cherry-markdown.engine.core.js 时，自定义语法失效，目前该问题还在排期修复中，如有使用自定义语法诉求时，还请先用 cherry-markdown.engine.js 或命名导入 { engine }。

2. 自动格式识别

package.json 配置了 exports 字段，可以自动识别使用环境并加载对应的文件格式：

"exports": {
  ".": {
    "import": "./dist/cherry-markdown.esm.js",   // ESM 环境
    "require": "./dist/cherry-markdown.js",      // UMD 环境
    "types": "./dist/types/index.d.ts"
  }
}

用户无需关心使用的是 ESM 还是 UMD，统一使用 import { xxx } from 'cherry-markdown' 即可。

引入 mermaid

cherry-markdown.js 默认包含了 mermaid（V9.4.3），如果业务方有自己版本的 mermaid，则可按以下方式引入自己版本的 mermaid：

在线 demo

https://tencent.github.io/cherry-markdown/examples/mermaid.html

方式一：定义 window.mermaid 属性

<!DOCTYPE html>
<html>
<head>
  <!-- 先加载自定义 mermaid -->
  <script src="https://cdn.com/mermaid/dist/mermaid.min.js"></script>
  <script type="module">
    import Cherry, { MermaidPlugin } from 'cherry-markdown';
    
    Cherry.usePlugin(MermaidPlugin, {
      mermaid: window.mermaid,
      mermaidAPI: window.mermaid, // 如果 mermaid 版本号 > 10.x，则重置 mermaidAPI 为 mermaid
    });
    
    new Cherry({ id: 'markdown-container' });
  </script>
</head>
<body>
  <div id="markdown-container"></div>
</body>
</html>

方式二：同步引入 mermaid 并传值给 Cherry

import Cherry, { MermaidPlugin } from 'cherry-markdown';
import mermaid from 'mermaid';

Cherry.usePlugin(MermaidPlugin, { mermaid });
new Cherry({ id: 'markdown-container' });

方式三：异步引入 mermaid 并传值给 Cherry

import Cherry, { MermaidPlugin } from 'cherry-markdown';

(async () => {
  const mermaid = await import('mermaid');
  Cherry.usePlugin(MermaidPlugin, { mermaid });
  
  new Cherry({ id: 'markdown-container' });
})();

注意

从 mermaid v10.0.0 开始，渲染逻辑由之前的同步渲染改成了异步渲染，afterChange 或者 afterInit 事件后，mermaid 代码块会先渲染为占位符，然后异步渲染并替换。

如需在异步渲染结束后获取内容，可以按以下方式：

const cherryInstance = new Cherry({
  id: 'markdown-container',
  value: `
    \`\`\`mermaid
    graph LR
        A[公司] -->| 下班 | B(菜市场)
        B --> C{看见<br>卖西瓜的}
        C -->|Yes| D[买一个包子]
        C -->|No| E[买一斤包子]
    \`\`\`
  `,
  callback: {
    afterAsyncRender: (md, html) => {
      // md 是 markdown 源码，html 是渲染结果
    }
  }
});

引入 echarts

import Cherry, { EChartsTablePlugin } from 'cherry-markdown';
import echarts from 'echarts';

Cherry.usePlugin(EChartsTablePlugin, { echarts });
new Cherry({ id: 'markdown-container' });

主要变更说明

导入方式变更

旧版导入 新版导入
import cherry from 'cherry-markdown' import Cherry from 'cherry-markdown'
import cherryCore from 'cherry-markdown/cherry-markdown.core' import { core } from 'cherry-markdown'
import cherryEngine from 'cherry-markdown/cherry-markdown.engine.core' import { engine } from 'cherry-markdown'
import mermaidPlugin from 'cherry-markdown/dist/addons/cherry-code-block-mermaid-plugin' import { MermaidPlugin } from 'cherry-markdown'
import echartsPlugin from 'cherry-markdown/dist/addons/advance/cherry-table-echarts-plugin' import { EChartsTablePlugin } from 'cherry-markdown'

新特性

  1. ✅ 统一入口导入：推荐使用 import { core, engine, MermaidPlugin } from 'cherry-markdown'
  2. ✅ ESM 格式支持：新增 .esm.js 文件，适用于现代打包工具
  3. ✅ 自动格式识别：package.json exports 配置自动识别 ESM/UMD 格式
  4. ✅ 插件命名导出：所有插件都可以通过命名导入获取
  5. ✅ 保持向后兼容：传统子路径导入方式仍然可用
  6. ⚠️ 移除 min 文件：不再生成 .min.js 文件
  7. ✅ 仅支持 ESM 和 UMD：不再生成 CommonJS 格式文件

可导出内容

1. 主要类和实例

import {
  Cherry,          // 默认导出：完整版，包含所有插件
  core,            // 核心版：不含插件，最小体积
  engine           // 引擎版：包含 Mermaid 插件，无 UI
} from 'cherry-markdown';

2. Hook 基类

import {
  SyntaxHookBase,   // 语法 Hook 基类，用于自定义语法
  MenuHookBase      // 菜单 Hook 基类，用于自定义菜单
} from 'cherry-markdown';

3. 插件类

import {
  MermaidPlugin,            // Mermaid 图表渲染插件
  PlantUMLPlugin,          // PlantUML 图表渲染插件
  EChartsTablePlugin,       // ECharts 表格图表插件
  TapdCheckListPlugin,      // TAPD 检查清单插件
  TapdHtmlTagPlugin,       // TAPD HTML 块插件
  TapdTablePlugin          // TAPD 表格插件
} from 'cherry-markdown';

总结

现在 Cherry Markdown 提供了统一的导入入口，所有功能都可以通过 import { xxx } from 'cherry-markdown' 获取，无需记住不同的子路径。同时保留了向后兼容性，支持传统的子路径导入方式。

Clone this wiki locally