@zjlab-frontier/markdown 1.1.4 → 1.1.5

package/README.md

@@ -1,8 +1,9 @@
 # `@zjlab-frontier/markdown` 使用说明文档
 
 > **包名**：`@zjlab-frontier/markdown`  
-> **适用框架**：React（支持 React 16.8+、17.x、18.x）  
-> **功能亮点**：支持 **Mermaid 图表**、**LaTeX 数学公式（KaTeX）**、**代码高亮**、**GitHub 风格 Markdown（GFM）**、**自动换行**、**代码复制**、**长代码折叠**、**媒体自动识别** 等。
+> **适用框架**：React（支持 React 18+）  
+> **核心引擎**：`react-markdown` + `better-react-mathjax` (MathJax v3) + `mermaid`  
+> **功能亮点**：支持 **Mermaid 图表**、**LaTeX 数学公式（MathJax）**、**代码高亮**、**GitHub 风格 Markdown（GFM）**、**长代码折叠**、**一键复制**、**媒体自动识别** 等。
 
 ---
 
@@ -12,16 +13,16 @@
 npm install @zjlab-frontier/markdown
 ```
 
-> ⚠️ 注意：本组件为 **React 组件**，需确保项目中已安装 React（版本 ≥16.8）。
+> ⚠️ **前置依赖**：本项目依赖 `react` 和 `react-dom` (≥18.0.0)。
 
 ---
 
 ## 🚀 快速开始
 
-### 1. 引入组件与样式
+### 1. 引入组件
 
 ```tsx
-import ZJMarkdown from '@zjlab-frontier/markdown';
+import { ZJMarkdown } from '@zjlab-frontier/markdown';
 ```
 
 ### 2. 基本使用
@@ -31,94 +32,76 @@ function App() {
   const markdownContent = `
 # 欢迎使用 ZJLab Markdown
 
-这是一个支持 **Mermaid**、**LaTeX** 和 **代码高亮** 的 React Markdown 组件。
+这是一个功能强大的 React Markdown 组件。
 
-- ✅ 表格
-- ✅ 任务列表
-- ✅ 数学公式：$E = mc^2$
-- ✅ 代码块（带复制按钮）
-- ✅ 自动识别音视频链接
+- ✅ **数学公式**：$E = mc^2$ 或 \[ \sum_{i=1}^n i = \frac{n(n+1)}{2} \]
+- ✅ **Mermaid 图表**：流程图、时序图等
+- ✅ **代码增强**：自动识别语言、复制按钮、长代码折叠
+- ✅ **多媒体**：自动识别 mp3/mp4 链接
   `;
 
-  return <ZJMarkdown content={markdownContent} />;
+  return (
+    <div style={{ padding: 20 }}>
+      <ZJMarkdown 
+        content={markdownContent} 
+        fontSize={16} 
+      />
+    </div>
+  );
 }
 ```
 
 ---
 
-## 测试组件
-
-用来快速测试、布局、调试的组件，自带全面的 Markdown 测试内容
-
-### 1. 引入组件
-
-```tsx
-import { TestZJMarkdown } from '@zjlab-frontier/markdown';
-```
-
-### 2. 使用
-
-```tsx
-<TestZJMarkdown />
-```
-
----
-
 ## 🧩 功能详解
 
-### 1. **GitHub 风格 Markdown（GFM）支持**
-
-通过 `remark-gfm` 插件，完整支持：
-
-- 表格
-- 删除线 `~~text~~`
-- 任务列表 `- [x] done`
-- 自动链接（如 `https://example.com`）
-
-✅ 示例：
-
-```md
-| 语法 | 描述 |
-|------|------|
-| `**bold**` | 加粗 |
+### 1. **数学公式（MathJax v3）**
 
-- [x] 支持 GFM
-- [ ] 其他功能
-```
+组件内置 `better-react-mathjax`，支持强大的 LaTeX 数学公式渲染。
 
----
+#### ✅ 支持语法：
 
-### 2. **LaTeX 数学公式（KaTeX）**
+- **行内公式**：`$...$` 或 `\(...\)`
+- **块级公式**：`$$...$$` 或 `\[...\]`
+- **环境支持**：支持 `align`, `gather`, `matrix`, `cases` 等常用环境。
 
-支持两种语法：
+#### ⚙️ 预处理增强：
 
-- 行内公式：`$...$` 或 `\(...\)`
-- 块级公式：`$$...$$` 或 `\[...\]`
+组件内置了 **LaTeX 预处理逻辑**，解决了 Markdown 转义字符（如 `\` 和 `_`）与 LaTeX 语法冲突的问题。
 
-> ⚠️ 注意：组件内部会自动将 `\(...\)` 和 `\[...\]` 转换为 `$...$` 和 `$$...$$`，确保 KaTeX 正确渲染。
+- 自动保护 `\\` 换行符
+- 自动处理 `\ce{...}` (化学式) 和 `\boxed{...}`
+- 兼容 `\begin{align}...\end{align}` 等环境写法
 
-✅ 示例：
+**示例：**
 
-```md
+```latex
 爱因斯坦质能方程：$E = mc^2$
 
 高斯积分：
 $$
-\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
+\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} 
 $$
-```
 
-> 📌 **样式说明**：已自动引入 `katex/dist/katex.min.css`，无需手动引入。
+矩阵：
+\[
+\begin{pmatrix}
+ a & b \\
+c & d
+\end{pmatrix}
+\]
+```
 
 ---
 
-### 3. **Mermaid 图表渲染**
 
-在代码块中标注语言为 `mermaid` 即可自动渲染图表：
+### 2. **Mermaid 图表渲染**
 
-✅ 示例：
+在代码块中标注语言为 `mermaid` 即可自动渲染图表。
 
-````
+**示例：**
+
+````markdown
 ```mermaid
 graph TD
   A[Start] --> B{Is it?}
@@ -127,169 +110,57 @@ graph TD
 ```
 ````
 
-> 🔒 **安全机制**：
-> - 若 Mermaid 渲染失败（如语法错误），组件将 **静默失败**（不显示原始代码，避免泄露敏感内容）。
-> - 图表容器带有 `no-dark` 类，防止深色主题干扰 Mermaid 默认配色。
-
-> 🖱️ **交互**：点击图表可触发 `viewSvgInNewWindow()`（当前为预留功能，实际未启用弹窗，但保留点击事件扩展点）。
-
----
-
-### 4. **代码高亮与增强功能**
-
-#### ✅ 支持特性：
-
-- 自动识别语言（基于 `language-xxx` class）
-- 显示语言标签（如 “javascript”）
-- 一键复制代码（右上角复制按钮）
-- 长代码块自动折叠（>400px 高度）
-- 纯文本类代码自动换行（如 `text`, `md`, `latex` 等）
-
-#### ✅ 支持自动换行的语言：
-
-```txt
-"", "md", "markdown", "text", "txt", "plaintext", "tex", "latex"
-```
-
-#### ✅ 复制按钮样式：
-
-- 使用 `.copy-code-button` 类，可通过 CSS 自定义图标。
-
 ---
 
-### 5. **媒体自动识别**
-
-组件会自动将特定后缀的链接转换为 `<audio>` 或 `<video>` 元素：
-
-#### 音频格式（自动转为 `<audio controls>`）：
-- `.aac`, `.mp3`, `.opus`, `.wav`
-
-#### 视频格式（自动转为 `<video controls>`）：
-- `.3gp`, `.3g2`, `.webm`, `.ogv`, `.mpeg`, `.mp4`, `.avi`
-
-✅ 示例：
-
-```md
-听一段音乐：https://example.com/song.mp3
-
-看一个视频：https://example.com/demo.mp4
-```
-
----
-
-### 6. **HTML 安全过滤（防 XSS）**
-
-组件对输入内容进行 **双重安全处理**：
 
-1. **转义危险字符**：`<`, `>`, `/`, `=` → 对应 HTML 实体
-2. **智能跳过**：
-   - 所有代码块（行内 `` `...` `` 和块级 ```...```）
-   - LaTeX 公式（`$...$`, `$$...$$`）
+### 3. **代码块增强**
 
-> ✅ 保证公式和代码内容不被破坏，同时防止 XSS 攻击。
+- **语言标注**：显示语言类型（如 `typescript`）。
+- **一键复制**：提供复制按钮。
+- **自动折叠**：高度超过 **400px** 自动折叠。
+- **自动换行**：对文本类语言（`text`, `md`, `latex`）强制换行。
 
 ---
 
-### 7. **文本方向与段落**
-
-- 所有 `<p>` 标签自动添加 `dir="auto"`，支持多语言自动排版。
-- 所有换行符（单个 `\n`）自动转为 `<br>`（通过 `remark-breaks`）。
-
----
-
-## 🎨 自定义样式
-
-### 1. **全局样式类**
-
-组件根元素自动应用：
 
-```html
-<div class="markdown-body">...</div>
-```
-
-> `.markdown-body` 采用 **GitHub 风格样式**（基于 `github-markdown-css` 理念定制）。
-
-### 2. **自定义字体与字号**
-
-通过 props 控制：
-
-```tsx
-<ZJMarkdown
-  content={content}
-  fontSize={18}          // 默认 16
-  fontFamily="'Inter', sans-serif"
-/>
-```
-
-### 3. **覆盖内置样式**
-
-可通过 CSS 覆盖以下关键类：
+### 4. **GitHub 风格 Markdown (GFM)**
 
-| 类名 | 用途 |
-|------|------|
-| `.markdown-body` | 整体容器 |
-| `.mermaid` | Mermaid 图表容器 |
-| `.copy-code-button` | 代码复制按钮 |
-| `.show-hide-button` | 代码折叠按钮 |
-| `.no-dark` | 防止深色主题干扰 Mermaid |
+集成 `remark-gfm`，支持表格、任务列表、删除线等。
 
 ---
 
-## 🛠️ API 说明
 
-### `ZJMarkdown` Props
-
-| 属性 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `content` | `string` | **必需** | Markdown 源字符串 |
-| `fontSize` | `number` | `16` | 字体大小（单位：px） |
-| `fontFamily` | `string` | `"inherit"` | 字体族 |
-| `onContextMenu` | `React.MouseEventHandler` | - | 右键菜单事件 |
-| `onDoubleClickCapture` | `React.MouseEventHandler` | - | 双击捕获事件 |
-| 其他 `div` 原生属性 | - | - | 如 `className`, `style` 等（透传至根 `div`） |
+### 5. **媒体自动识别**
 
-> ⚠️ 注意：`content` 中的 HTML 标签会被 **安全过滤**，仅保留必要结构。
+- **音频** (`.mp3`, `.wav` 等) → `<audio controls>`
+- **视频** (`.mp4`, `.webm` 等) → `<video controls>`
 
 ---
 
-## 🧪 注意事项与限制
-
-1. **Mermaid 渲染异步性**：
-   - 首次渲染可能因 debounce 延迟（600ms）导致短暂显示原始代码。
-   - 组件已做兼容处理，尽量减少此现象。
+## 🎨 样式与自定义
 
-2. **KaTeX 公式转义**：
-   - 不要混用 `\(...\)` 和 `$...$`，建议统一使用 `$...$`。
-   - 公式内避免使用 `<`, `>` 等符号，或使用 `\lt`, `\gt` 替代。
+组件根元素默认带有 `.markdown-body` 类。
 
-3. **代码折叠逻辑**：
-   - 仅当代码块高度 > 400px 时显示“查看全部”按钮。
-   - 折叠状态下，代码块最大高度为 400px，`overflow-y: hidden`。
+### Props 属性
 
-4. **性能优化**：
-   - 内部使用 `React.memo`，仅当 `content` 变化时重渲染。
-   - 建议对大型文档做分页或懒加载。
+| 属性名 | 类型 | 默认值 | 说明 |
+|:---|:---|:---|:---|
+| `content` | `string` | **必填** | Markdown 源码字符串 |
+| `fontSize` | `number` | `16` | 正文字体大小 (px) |
+| `fontFamily` | `string` | `'inherit'` | 字体设置 |
+| `style` | `CSSProperties` | - | 自定义根元素样式 |
 
 ---
 
-## 📜 许可证
+## 🛠️ 开发与构建
 
-MIT License
+```bash
+npm run build        # 构建产物
+npm run build:types  # 生成类型定义
+```
 
 ---
 
-## 🙏 致谢
-
-本组件基于以下优秀开源库构建：
-
-- [`react-markdown`](https://github.com/remarkjs/react-markdown)
-- [`rehype-highlight`](https://github.com/rehypejs/rehype-highlight)
-- [`rehype-katex`](https://github.com/remarkjs/remark-math)
-- [`mermaid`](https://mermaid.js.org/)
-- [`katex`](https://katex.org/)
-- [`clsx`](https://github.com/lukeed/clsx)
-- [`use-debounce`](https://github.com/xnimorz/use-debounce)
-
----
+## 📝 License
 
-> ✅ 本说明文档完整覆盖 `@zjlab-frontier/markdown@1.0.6` 所有功能，无省略，可直接用于团队协作或用户文档。
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zjlab-frontier/markdown",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "Framework-agnostic Markdown component with support for Mermaid, KaTeX, and code highlighting. Core library is React-free; React adapter available optionally.",
   "main": "dist/index.umd.js",
   "types": "dist/index.d.ts",