pixui-markdown

基于 Pixui V5 引擎的 Markdown 预览组件，支持标准 Markdown 语法渲染。

特性

• 完整的 Markdown 语法支持（标题、段落、列表、表格、代码块、引用等）
• 代码语法高亮（JavaScript/TypeScript、Python、CSS、HTML/XML）
• 大文件分块异步渲染，避免 UI 阻塞
• rem 自适应布局，适配不同屏幕尺寸
• 可配置主题样式
• 纯 DOM API，不依赖任何 UI 框架
• 完整的 TypeScript 类型定义
• 支持 ESM 和 CJS 双格式

安装

npm install pixui-markdown

快速开始

提示：如果你的内容是流式传输，建议使用 方式三（仅使用解析器），以便在每次内容变化时自行控制解析与渲染时机，获得更好的性能和灵活性。

方式一：使用便捷 API（推荐）

import { createMarkdownViewer } from 'pixui-markdown';

// 创建 Markdown 预览实例，content 由使用方传入
const viewer = createMarkdownViewer({
  container: document.getElementById('app')!,
  content: '# Hello World\n\nThis is **bold** text.',
});

// 更新内容
viewer.update('# 新的标题\n\n新的内容...');

// 销毁实例（清理资源）
viewer.destroy();

方式二：分步使用（更灵活）

import {
  parseMarkdown,
  createRenderer,
  getMarkdownStyles,
  initRemAdapter,
} from 'pixui-markdown';

// 1. 初始化 rem 适配
initRemAdapter();

// 2. 注入样式
const styleEl = document.createElement('style');
styleEl.innerHTML = getMarkdownStyles();
document.head.appendChild(styleEl);

// 3. 解析 Markdown 为 AST
const ast = parseMarkdown('# Hello World\n\nThis is **bold** text.');

// 4. 创建渲染器并渲染
const renderer = createRenderer();
const container = document.getElementById('content')!;
renderer.render(ast, container);

// 5. 绑定链接点击事件
renderer.bindEvents(container);

方式三：Markdown 文本直接转 HTML

import { markdownToHtml } from 'pixui-markdown';

// 传入 Markdown 文本，直接返回 HTML 字符串
const html = markdownToHtml('# Hello\n\n**Bold** and *italic*');
console.log(html);
// 输出: <div class="md-heading md-h1">...</div><div class="md-paragraph">...</div>

API 文档

createMarkdownViewer(options)

创建 Markdown 预览实例，一键完成样式注入、解析、渲染。

参数：

| 参数 | 类型 | 必填 | 说明 | | -------------------- | ---------------------- | ---- | ---------------------------------- | | container | HTMLElement | ✅ | 目标容器元素 | | content | string | ✅ | Markdown 文本内容 | | styleConfig | StyleConfig | ❌ | 自定义样式配置 | | enableRemAdapter | boolean | ❌ | 是否启用 rem 适配（默认 true） | | chunkOptions | ChunkRenderOptions | ❌ | 分块渲染配置 | | className | string | ❌ | 自定义 CSS 类名 |

返回值： MarkdownViewerInstance

| 方法 | 说明 | | --------------------------- | ---------------------- | | update(content: string) | 更新 Markdown 内容 | | destroy() | 销毁实例，清理所有资源 | | getRenderer() | 获取底层渲染器实例 |

markdownToHtml(md)

将 Markdown 文本直接转换为 HTML 字符串（内部自动完成解析）。

import { markdownToHtml } from 'pixui-markdown';

const html = markdownToHtml('# Hello\n\n**Bold** text');
// 返回完整的 HTML 字符串

参数：

| 参数 | 类型 | 必填 | 说明 | | ------ | ---------- | ---- | ----------------- | | md | string | ✅ | Markdown 文本内容 |

返回值： string — 转换后的 HTML 字符串

parseMarkdown(src)

将 Markdown 文本解析为 AST 节点数组。

const ast: MarkdownNode[] = parseMarkdown(markdownText);

createRenderer()

创建 DOM 渲染器实例。

const renderer: RendererInstance = createRenderer();
renderer.render(ast, container);
renderer.bindEvents(container, scrollContainer);
renderer.clear(container);
renderer.unbindEvents(container);

getMarkdownStyles(config?)

获取 Markdown CSS 样式字符串。

// 使用默认样式
const css = getMarkdownStyles();

// 自定义主题
const css = getMarkdownStyles({
  textColor: '#333333',
  linkColor: '#1890ff',
  borderColor: '#e8e8e8',
  codeBlockBg: '#fafafa',
});

StyleConfig 配置项

| 属性 | 类型 | 默认值 | 说明 | | ------------------ | ---------- | ---------------------------- | -------------- | | textColor | string | #1f2328 | 主文本颜色 | | linkColor | string | #0969da | 链接颜色 | | borderColor | string | #d0d7de | 边框颜色 | | codeBlockBg | string | #f6f8fa | 代码块背景色 | | inlineCodeBg | string | rgba(175, 184, 193, 0.2) | 行内代码背景色 | | quoteColor | string | #656d76 | 引用文本颜色 | | baseFontSize | string | 0.4267rem | 基础字号 | | baseLineHeight | string | 0.6827rem | 基础行高 |

语法高亮

import { highlight, registerLanguage, getSupportedLanguages } from 'pixui-markdown';

// 获取支持的语言列表
const languages = getSupportedLanguages();
// ['js', 'javascript', 'ts', 'typescript', 'jsx', 'tsx', 'py', 'python', 'css', 'less', 'scss', 'html', 'xml', 'svg']

// 对代码进行高亮
const segments = highlight('const x = 42;', 'javascript');
// [{ text: 'const', className: 'hl-keyword' }, { text: ' x = ', className: undefined }, ...]

// 注册自定义语言
registerLanguage('go', [
  [/(\/\/[^\n]*)/g, 'hl-comment'],
  [/\b(func|var|const|type|struct|interface|return|if|else|for|range|package|import)\b/g, 'hl-keyword'],
]);

分块渲染

import { ChunkRenderer, calcDynamicChunkSize, LARGE_DOC_THRESHOLD } from 'pixui-markdown';

const chunkRenderer = new ChunkRenderer();

chunkRenderer.start(ast, container, renderer, {
  chunkSize: 10,
  chunkInterval: 16,
  onProgress: (rendered, total) => {
    console.log(`渲染进度: ${rendered}/${total}`);
  },
  onComplete: () => {
    console.log('渲染完成');
  },
  onPerfReport: (report) => {
    console.log(`总耗时: ${report.totalMs}ms`);
  },
});

// 取消渲染
chunkRenderer.cancel();

rem 适配

import { initRemAdapter, destroyRemAdapter, pxToRem, getRemScale } from 'pixui-markdown';

// 初始化（基准宽度 375px，1rem = 37.5px）
initRemAdapter();

// px 转 rem
const remValue = pxToRem(16); // "0.4267rem"

// 获取当前缩放比例
const scale = getRemScale();

// 销毁
destroyRemAdapter();

支持的 Markdown 语法

| 语法 | 支持状态 | 说明 | | ------------ | -------- | ------------------------------------------ | | 标题 (h1-h6) | ✅ | # ~ ###### | | 段落 | ✅ | 空行分隔 | | 加粗 | ✅ | **text** / __text__ | | 斜体 | ✅ | *text* / _text_（使用 skewX 模拟） | | 粗斜体 | ✅ | ***text*** | | 删除线 | ✅ | ~~text~~ | | 行内代码 | ✅ | `code` | | 代码块 | ✅ | 围栏代码块，支持语法高亮 | | 引用 | ✅ | > text | | 无序列表 | ✅ | - / * / +，支持嵌套 | | 有序列表 | ✅ | 1. 2. 3.，支持嵌套 | | 任务列表 | ✅ | - [x] / - [ ] | | 表格 | ✅ | GFM 表格，Flex 布局模拟 | | 链接 | ✅ | [text](url) | | 图片 | ✅ | ![alt](url) | | 水平线 | ✅ | --- / *** / ___ | | 换行 | ✅ | 行尾双空格 /<br> |

已知问题与限制

1. Emoji不支持,组件在解析阶段自动移除 Emoji 字符
2. text标签内嵌标签需要设置粗体或倾斜，需要字体支持，字体里有倾斜的样式
3. 在pixui点击链接打开外链不生效 例如：https://example.com
4. 不支持超长文本渲染

Pixui V5 兼容说明

本组件专为 Pixui V5 引擎设计，已处理以下兼容问题：

• 所有文本内容使用 <text> 标签包裹（Pixui 仅 <text> / <pre> 支持富文本排版）
• 行内代码和链接使用独立 <div> 盒子（Pixui 的 <text> 不渲染子节点的盒模型属性）
• 列表标记使用 Unicode 字符手动实现（Pixui 不支持 list-style-type）
• 任务列表复选框使用 <div> + CSS 模拟（Pixui 不支持 <input type="checkbox">）
• 表格使用 Flex 布局模拟（Pixui 不支持 display: table）
• 滚动容器使用 overflow: scroll（Pixui 的 overflow: auto 等同于 visible）
• 斜体使用 transform: skewX(-12deg) 模拟（Pixui 的 <text> 内不支持 font-style: italic）
• Emoji 字符自动过滤（避免渲染异常）

项目结构

packages/pixui-markdown/
├── src/
│   ├── index.ts            # 统一入口，导出所有模块和便捷 API
│   ├── parser.ts           # Markdown 解析器（Markdown → AST）
│   ├── renderer.ts         # DOM 渲染器（AST → Pixui DOM）
│   ├── styles.ts           # CSS 样式系统（可配置主题）
│   ├── highlighter.ts      # 代码语法高亮（纯正则，可扩展）
│   ├── chunk-renderer.ts   # 分块异步渲染调度器
│   └── rem-adapter.ts      # rem 布局自适应适配
├── package.json
├── tsconfig.json
├── tsconfig.esm.json
├── tsconfig.cjs.json
├── tsconfig.types.json
└── README.md

构建

cd packages/pixui-markdown
npm install
npm run build

构建产物：

dist/
├── esm/     # ES Module 格式
├── cjs/     # CommonJS 格式
└── types/   # TypeScript 类型声明

License

MIT