ds-markdown 1.0.0-beta.1 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (20) hide show
  1. package/README.md +335 -512
  2. package/README.zh.md +938 -0
  3. package/es/Markdown/index.d.ts +1 -1
  4. package/es/MarkdownCMD/index.d.ts +1 -1
  5. package/es/components/CodeComponent/BlockWrap/index.d.ts +1 -1
  6. package/es/components/CodeComponent/index.d.ts +1 -1
  7. package/es/components/TableComponent/index.d.ts +1 -1
  8. package/es/components/ui/IconButton/index.d.ts +1 -1
  9. package/es/components/ui/Segmented/index.d.ts +1 -1
  10. package/es/components/ui/SuccessButton/index.d.ts +1 -1
  11. package/es/context/ConfigProvider/index.d.ts +2 -2
  12. package/es/context/MarkdownProvider.d.ts +1 -1
  13. package/es/context/MarkdownThemeProvider.d.ts +1 -1
  14. package/es/defined/index.d.ts +1 -1
  15. package/es/i18n/index.d.ts +6 -6
  16. package/es/index.d.ts +18 -18
  17. package/es/plugins/index.d.ts +2 -2
  18. package/es/utils/compiler.d.ts +1 -1
  19. package/package.json +3 -4
  20. package/README.en.md +0 -753
package/README.md CHANGED
@@ -1,10 +1,14 @@
1
1
  # ds-markdown
2
2
 
3
- > 🚀 高性能 React Markdown 打字动画组件，完美复刻 DeepSeek 聊天界面效果
3
+ <p align="center">
4
+ <img src="./assets/images/favicon.png" alt="ds-markdown logo" width="120" />
5
+ </p>
4
6
 
5
- **🇨🇳 中文 | [🇺🇸 English](./README.en.md)**
7
+ > 🚀 React Markdown typing animation component for modern chat interface effects
6
8
 
7
- 一个专为现代 AI 应用设计的 React 组件，提供流畅的实时打字动画和完整的 Markdown 渲染能力。
9
+ **🇺🇸 English | [🇨🇳 中文](./README.md)**
10
+
11
+ A React component designed specifically for modern AI applications, providing smooth real-time typing animations and complete Markdown rendering capabilities.
8
12
 
9
13
  [![npm version](https://img.shields.io/npm/v/ds-markdown)](https://www.npmjs.com/package/ds-markdown)
10
14
  [![npm downloads](https://img.shields.io/npm/dm/ds-markdown.svg)](https://www.npmjs.com/package/ds-markdown)
@@ -12,107 +16,135 @@
12
16
  [![React](https://img.shields.io/badge/React-18.0.0+-blue)](https://react.dev)
13
17
  [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
14
18
 
15
- - [使用文档](https://onshinpei.github.io/ds-markdown/)
16
- - 使用示例
17
- - [基本用法](https://stackblitz.com/edit/vitejs-vite-ddfw8avb?file=src%2FApp.tsx)
18
- - [流式数据用法](https://stackblitz.com/edit/vitejs-vite-2ri8kex3?file=src%2FApp.tsx)
19
- - [mermaid图表](https://stackblitz.com/edit/vitejs-vite-iqbyta3j?file=index.html)
20
- - [数学公式demo1](https://stackblitz.com/edit/vitejs-vite-iqbyta3j?file=index.html)
21
- - [数学公式demo2](https://stackblitz.com/edit/vitejs-vite-xk9lxagc?file=src%2FApp.tsx)
19
+ - [Documentation](https://onshinpei.github.io/ds-markdown/)
20
+ - Usage Examples
21
+ - [Basic Usage](https://stackblitz.com/~/github.com/onshinpei/ds-markdown-base-en?file=src/App.tsx)
22
+ - [Streaming Data Usage](https://stackblitz.com/edit/vitejs-vite-2ri8kex3?file=src%2FApp.tsx)
23
+ - [Mermaid Charts](https://stackblitz.com/edit/vitejs-vite-iqbyta3j?file=index.html)
24
+ - [Math Formulas Demo 1](https://stackblitz.com/edit/vitejs-vite-iqbyta3j?file=index.html)
25
+ - [Math Formulas Demo 2](https://stackblitz.com/edit/vitejs-vite-xk9lxagc?file=src%2FApp.tsx)
22
26
 
23
- 如果你想要一个纯净的`react markdown` 打字组件，可以使用[react-markdown-typer](https://github.com/onshinpei/react-markdown-typer)
27
+ If you want a clean `react markdown` typing component, you can use [react-markdown-typer](https://github.com/onshinpei/react-markdown-typer)
24
28
 
25
29
  ---
26
30
 
27
- ## ❓ 为什么要用 ds-markdown？
31
+ ## ❓ Why use ds-markdown?
28
32
 
29
- ### 🎯 **解决的核心问题**
33
+ ### 🎯 **Core Problems Solved**
30
34
 
31
- - **流式数据打字卡顿问题**
32
- 传统打字机组件在处理 AI 后端流式数据时，由于每个 chunk 包含多个字符，会出现卡顿、跳字等问题。ds-markdown 智能拆分每个 chunk，确保每个字符都流畅打字。
35
+ - **Streaming Data Typing Stuttering Issues**
36
+ Traditional typewriter components experience stuttering and character jumping when processing AI backend streaming data, as each chunk contains multiple characters. ds-markdown intelligently splits each chunk to ensure smooth typing for every character.
33
37
 
34
- - **Markdown 渲染与打字动画割裂**
35
- 大多数打字机组件只支持纯文本，无法在打字过程中实时渲染 Markdown 语法、数学公式、图表等富媒体内容。
38
+ - **Markdown Rendering and Typing Animation Disconnection**
39
+ Most typewriter components only support plain text and cannot render Markdown syntax, mathematical formulas, charts, and other rich media content in real-time during typing.
36
40
 
37
- ### 🚀 **带来的价值**
41
+ ### 🚀 **Value Delivered**
38
42
 
39
- - **提升用户沉浸感**
40
- 提供专业级 AI 聊天体验，让用户感受到真实的 AI 交互过程，极大提升产品专业度和用户满意度。
43
+ - **Enhanced User Immersion**
44
+ Provides professional-level AI chat experience, allowing users to feel authentic AI interaction processes, greatly improving product professionalism and user satisfaction.
41
45
 
42
- - **开箱即用，降低开发复杂度**
43
- 完整的解决方案，无需额外配置即可支持流式数据、Markdown 渲染、数学公式、图表等复杂功能。
46
+ - **Out-of-the-box, Reduces Development Complexity**
47
+ Complete solution that requires no additional configuration to support streaming data, Markdown rendering, mathematical formulas, charts, and other complex features.
44
48
 
45
- - **适配多种应用场景**
46
- 从 AI 聊天机器人到教育内容展示，从技术文档到产品演示，一个组件满足多种需求。
49
+ - **Adapts to Multiple Application Scenarios**
50
+ From AI chatbots to educational content display, from technical documentation to product demos, one component meets multiple needs.
47
51
 
48
52
  ---
49
53
 
50
- ## 目录
51
-
52
- - [核心特性](#-核心特性)
53
- - [快速安装](#-快速安装)
54
- - [5分钟上手](#-5分钟上手)
55
- - [基础用法](#基础用法)
56
- - [禁用打字动画](#禁用打字动画)
57
- - [数学公式支持](#数学公式支持)
58
- - [AI 对话场景](#ai-对话场景)
59
- - [代码块功能 🆕](#代码块功能-)
60
- - [Mermaid图表支持](#mermaid图表支持)
61
- - [完整 API 文档](#-完整-api-文档)
62
- - [插件系统](#-插件系统)
63
- - [内置插件](#内置插件)
64
- - [KaTeX 数学公式插件](#katex-数学公式插件)
65
- - [Mermaid 图表插件 🆕](#mermaid-图表插件-)
66
- - [自定义插件](#自定义插件)
67
- - [多语言配置](#多语言配置)
68
- - [实战示例](#-实战示例)
69
- - [最佳实践](#-最佳实践)
70
-
71
- ## ✨ 核心特性
72
-
73
- ### 🤖 **AI 对话场景**
74
-
75
- - 专业级 AI 聊天响应效果，媲美主流 AI 平台体验
76
- - 支持思考过程 (`thinking`) 和回答内容 (`answer`) 双模式
77
- - 流式数据完美适配，零延迟响应用户输入
78
-
79
- ### 📊 **内容展示场景**
80
-
81
- - 完整 Markdown 语法支持，包括代码高亮、表格、列表等
82
- - 数学公式渲染 (KaTeX)，支持 `$...$` 和 `\[...\]` 语法
83
- - Mermaid 图表支持，包括流程图、序列图、甘特图、类图等 🆕
84
- - 支持亮色/暗色主题，适配不同产品风格
85
- - 插件化架构，支持 remark/rehype 插件扩展
86
-
87
- ### 🎨 **UI组件系统** 🆕
88
-
89
- - 代码块、图表增强功能：复制、下载、语言等
90
- - 内置丰富的UI组件：Button、IconButton、ToolTip、Segmented等
91
- - 完整的交互体验和无障碍支持
92
-
93
- ### 🔧 **开发体验**
94
-
95
- - 丰富的命令式API：`start`、`stop`、`resume`、`restart` 等
96
- - 支持打字中断与继续，灵活控制动画状态
97
- - 支持打字关闭与开启，满足不同场景需求
98
- - 完整的TypeScript类型支持
99
-
100
- ### 🎬 **流畅动画**
101
-
102
- - 双模式定时器优化，支持`requestAnimationFrame`和`setTimeout`模式
103
- - 高频打字支持（`requestAnimationFrame`模式下打字间隔最低可接近于`0ms`）
104
- - 帧同步渲染，与浏览器刷新完美配合
105
- - 智能字符批量处理，视觉效果更自然
106
- - **动态速度控制** 🆕：根据剩余字符数量自动调整打字速度，流式数据场景下提供更自然的阅读体验
107
-
108
- ### ⚡ **性能优化**
109
-
110
- - 轻量级设计，体积小、性能优
111
- - 核心依赖 [react-markdown](https://github.com/remarkjs/react-markdown)，无重量级依赖
54
+ ## Table of Contents
55
+
56
+ - [ds-markdown](#ds-markdown)
57
+ - [❓ Why use ds-markdown?](#-why-use-ds-markdown)
58
+ - [🎯 **Core Problems Solved**](#-core-problems-solved)
59
+ - [🚀 **Value Delivered**](#-value-delivered)
60
+ - [Table of Contents](#table-of-contents)
61
+ - [✨ Core Features](#-core-features)
62
+ - [🤖 **AI Chat Scenarios**](#-ai-chat-scenarios)
63
+ - [📊 **Content Display Scenarios**](#-content-display-scenarios)
64
+ - [🎨 **UI Component System 🆕**](#-ui-component-system-)
65
+ - [🔧 **Development Experience**](#-development-experience)
66
+ - [🎬 **Smooth Animation**](#-smooth-animation)
67
+ - [⚡ **Performance Optimization**](#-performance-optimization)
68
+ - [📦 Quick Installation](#-quick-installation)
69
+ - [Using via ESM CDN](#using-via-esm-cdn)
70
+ - [🚀 5-Minute Quick Start](#-5-minute-quick-start)
71
+ - [Basic Usage](#basic-usage)
72
+ - [Disable Typing Animation](#disable-typing-animation)
73
+ - [Mathematical Formula Support](#mathematical-formula-support)
74
+ - [AI Chat Scenarios](#ai-chat-scenarios)
75
+ - [Code Block Features 🆕](#code-block-features-)
76
+ - [Mermaid Chart Support](#mermaid-chart-support)
77
+ - [📚 Complete API Documentation](#-complete-api-documentation)
78
+ - [Default export DsMarkdown and MarkdownCMD props](#default-export-dsmarkdown-and-markdowncmd-props)
79
+ - [IBeforeTypedChar](#ibeforetypedchar)
80
+ - [ITypedChar](#itypedchar)
81
+ - [IMarkdownMath](#imarkdownmath)
82
+ - [IMarkdownCode 🆕](#imarkdowncode-)
83
+ - [IMarkdownPlugin](#imarkdownplugin)
84
+ - [Component Exposed Methods](#component-exposed-methods)
85
+ - [Default export DsMarkdown](#default-export-dsmarkdown)
86
+ - [MarkdownCMD Exposed Methods](#markdowncmd-exposed-methods)
87
+ - [🔌 Plugin System](#-plugin-system)
88
+ - [Built-in Plugins](#built-in-plugins)
89
+ - [KaTeX Mathematical Formula Plugin](#katex-mathematical-formula-plugin)
90
+ - [Mermaid Chart Plugin 🆕](#mermaid-chart-plugin-)
91
+ - [Custom Plugins](#custom-plugins)
92
+ - [🎨 UI Component System 🆕](#-ui-component-system--1)
93
+ - [Core Components](#core-components)
94
+ - [Style Customization](#style-customization)
95
+ - [Multi-language Configuration](#multi-language-configuration)
96
+ - [💡 Practical Examples](#-practical-examples)
97
+ - [📝 AI Streaming Chat](#-ai-streaming-chat)
98
+ - [🔧 Best Practices](#-best-practices)
99
+ - [1. Performance Optimization](#1-performance-optimization)
100
+ - [2. Streaming Data Processing](#2-streaming-data-processing)
101
+ - [3. Mathematical Formula Optimization](#3-mathematical-formula-optimization)
102
+ - [4. Mermaid Chart Best Practices 🆕](#4-mermaid-chart-best-practices-)
103
+
104
+ ## ✨ Core Features
105
+
106
+ ### 🤖 **AI Chat Scenarios**
107
+
108
+ - Professional-level AI chat response effects, comparable to mainstream AI platform experiences
109
+ - Supports thinking process (`thinking`) and answer content `answer`) dual modes
110
+ - Perfect streaming data adaptation with zero-delay response to user input
111
+
112
+ ### 📊 **Content Display Scenarios**
113
+
114
+ - Complete Markdown syntax support, including code highlighting, tables, lists, etc.
115
+ - Mathematical formula rendering (KaTeX), supporting `$...$` and `\[...\]` syntax
116
+ - Mermaid chart support, including flowcharts, sequence diagrams, Gantt charts, class diagrams, etc. 🆕
117
+ - Supports light/dark themes, adapting to different product styles
118
+ - Plugin architecture supporting remark/rehype plugin extensions
119
+
120
+ ### 🎨 **UI Component System 🆕**
121
+
122
+ - Code block and chart enhancement features: copy, download, language, etc.
123
+ - Built-in rich UI components: Button, IconButton, ToolTip, Segmented, etc.
124
+ - Complete interactive experience and accessibility support
125
+
126
+ ### 🔧 **Development Experience**
127
+
128
+ - Rich imperative API: `start`, `stop`, `resume`, `restart`, etc.
129
+ - Supports typing interruption and continuation, flexible control of animation states
130
+ - Supports typing on/off, meeting different scenario requirements
131
+ - Complete TypeScript type support
132
+
133
+ ### 🎬 **Smooth Animation**
134
+
135
+ - Dual-mode timer optimization, supporting `requestAnimationFrame` and `setTimeout` modes
136
+ - High-frequency typing support (typing interval can be as low as close to `0ms` in `requestAnimationFrame` mode)
137
+ - Frame-synchronized rendering, perfectly coordinated with browser refresh
138
+ - Intelligent character batch processing for more natural visual effects
139
+
140
+ ### ⚡ **Performance Optimization**
141
+
142
+ - Lightweight design, small size and excellent performance
143
+ - Core dependency [react-markdown](https://github.com/remarkjs/react-markdown), no heavyweight dependencies
112
144
 
113
145
  ---
114
146
 
115
- ## 📦 快速安装
147
+ ## 📦 Quick Installation
116
148
 
117
149
  ```bash
118
150
  # npm
@@ -125,11 +157,30 @@ yarn add ds-markdown
125
157
  pnpm add ds-markdown
126
158
  ```
127
159
 
128
- ## 🚀 5分钟上手
160
+ ### Using via ESM CDN
161
+
162
+ No installation required, use directly in the browser:
163
+
164
+ [DEMO](https://stackblitz.com/edit/stackblitz-starters-7vcclcw7?file=index.html)
165
+
166
+ ```html
167
+ <!-- Import styles, required -->
168
+ <link rel="stylesheet" href="https://esm.sh/ds-markdown/dist/style.css" />
169
+
170
+ <!-- Import KaTeX math formula styles, only import if needed -->
171
+ <link rel="stylesheet" href="https://esm.sh/ds-markdown/dist/katex.css" />
172
+
173
+ <!-- Import component -->
174
+ <script type="module">
175
+ import Markdown from 'https://esm.sh/ds-markdown';
176
+ </script>
177
+ ```
178
+
179
+ ## 🚀 5-Minute Quick Start
129
180
 
130
- > ✅ v1.0+版本开始，无需再手动 `import 'ds-markdown/style.css'`，组件会自动注入所需的基础样式。
181
+ > ✅ Starting from v1.0+, you no longer need to manually import `ds-markdown/style.css`; the component automatically injects the required base styles.
131
182
 
132
- ### 基础用法
183
+ ### Basic Usage
133
184
 
134
185
  [DEMO](https://stackblitz.com/edit/vitejs-vite-z94syu8j?file=src%2FApp.tsx)
135
186
 
@@ -139,13 +190,13 @@ import DsMarkdown from 'ds-markdown';
139
190
  function App() {
140
191
  return (
141
192
  <DsMarkdown interval={20} answerType="answer">
142
- # Hello ds-markdown 这是一个**高性能**的打字动画组件！ ## 特性 - ⚡ 零延迟流式处理 - 🎬 流畅打字动画 - 🎯 完美语法支持
193
+ # Hello ds-markdown This is a **high-performance** typing animation component! ## Features - ⚡ Zero-delay streaming processing - 🎬 Smooth typing animation - 🎯 Perfect syntax support
143
194
  </DsMarkdown>
144
195
  );
145
196
  }
146
197
  ```
147
198
 
148
- ### 禁用打字动画
199
+ ### Disable Typing Animation
149
200
 
150
201
  ```tsx
151
202
  import DsMarkdown from 'ds-markdown';
@@ -155,36 +206,38 @@ function StaticDemo() {
155
206
 
156
207
  return (
157
208
  <div>
158
- <button onClick={() => setDisableTyping(!disableTyping)}>{disableTyping ? '开启' : '关闭'}打字机效果</button>
209
+ <button onClick={() => setDisableTyping(!disableTyping)}>{disableTyping ? 'Enable' : 'Disable'} Typewriter Effect</button>
159
210
 
160
211
  <DsMarkdown interval={20} answerType="answer" disableTyping={disableTyping}>
161
- # 静态展示模式 当 `disableTyping` 为 `true` 时，内容会立即全部显示，无打字动画效果。 这在某些场景下非常有用： - 📄 静态文档展示 - 🔄 切换显示模式 - ⚡ 快速预览内容
212
+ # Static Display Mode When `disableTyping` is `true`, content will be displayed immediately without typing animation effects. This is very useful in certain scenarios: - 📄 Static document
213
+ display - 🔄 Switching display modes - ⚡ Quick content preview
162
214
  </DsMarkdown>
163
215
  </div>
164
216
  );
165
217
  }
166
218
  ```
167
219
 
168
- ### 数学公式支持
220
+ ### Mathematical Formula Support
169
221
 
170
222
  ```tsx
171
223
  import DsMarkdown from 'ds-markdown';
172
- // 如果需要展示公式，则需要引入公式转换插件
224
+ // If you need to display formulas, you need to import the formula conversion plugin
173
225
  import { katexPlugin } from 'ds-markdown/plugins';
174
226
  import 'ds-markdown/style.css';
175
- // 如果需要展示公式，则需要引入数学公式样式
227
+ // If you need to display formulas, you need to import math formula styles
176
228
  import 'ds-markdown/katex.css';
177
229
 
178
230
  function MathDemo() {
179
231
  return (
180
232
  <DsMarkdown interval={20} answerType="answer" plugins={[katexPlugin]} math={{ splitSymbol: 'dollar' }}>
181
- # 勾股定理 在直角三角形中，斜边的平方等于两条直角边的平方和： $a^2 + b^2 = c^2$ 其中： - $a$ 和 $b$ 是直角边 - $c$ 是斜边 对于经典的"勾三股四弦五"： $c = \sqrt{3 ^ (2 + 4) ^ 2} = \sqrt{25} = 5$
233
+ # Pythagorean Theorem In a right triangle, the square of the hypotenuse equals the sum of the squares of the two legs: $a^2 + b^2 = c^2$ Where: - $a$ and $b$ are the legs - $c$ is the hypotenuse
234
+ For the classic "3-4-5 triangle": $c = \sqrt{3 ^ (2 + 4) ^ 2} = \sqrt{25} = 5$
182
235
  </DsMarkdown>
183
236
  );
184
237
  }
185
238
  ```
186
239
 
187
- ### AI 对话场景
240
+ ### AI Chat Scenarios
188
241
 
189
242
  ```tsx
190
243
  function ChatDemo() {
@@ -192,25 +245,25 @@ function ChatDemo() {
192
245
  const [answer, setAnswer] = useState('');
193
246
 
194
247
  const handleAsk = () => {
195
- setThinking('🤔 正在思考您的问题...');
248
+ setThinking('🤔 Thinking about your question...');
196
249
 
197
250
  setTimeout(() => {
198
- setAnswer(`# 关于 React 19
251
+ setAnswer(`# About React 19
199
252
 
200
- React 19 带来了许多激动人心的新特性：
253
+ React 19 brings many exciting new features:
201
254
 
202
- ## 🚀 主要更新
203
- 1. **React Compiler** - 自动优化性能
204
- 2. **Actions** - 简化表单处理
205
- 3. **Document Metadata** - 内置 SEO 支持
255
+ ## 🚀 Major Updates
256
+ 1. **React Compiler** - Automatic performance optimization
257
+ 2. **Actions** - Simplified form handling
258
+ 3. **Document Metadata** - Built-in SEO support
206
259
 
207
- 让我们一起探索这些新功能！`);
260
+ Let's explore these new features together!`);
208
261
  }, 2000);
209
262
  };
210
263
 
211
264
  return (
212
265
  <div>
213
- <button onClick={handleAsk}>询问 AI</button>
266
+ <button onClick={handleAsk}>Ask AI</button>
214
267
 
215
268
  {thinking && (
216
269
  <DsMarkdown answerType="thinking" interval={30}>
@@ -228,7 +281,7 @@ React 19 带来了许多激动人心的新特性：
228
281
  }
229
282
  ```
230
283
 
231
- ### 代码块功能 🆕
284
+ ### Code Block Features 🆕
232
285
 
233
286
  ```tsx
234
287
  import DsMarkdown from 'ds-markdown';
@@ -244,14 +297,14 @@ function greet(name) {
244
297
  greet('ds-markdown');
245
298
  \`\`\`
246
299
 
247
- 支持代码高亮、复制和下载功能！`;
300
+ Supports code highlighting, copying, and downloading!`;
248
301
 
249
302
  return (
250
303
  <DsMarkdown
251
304
  interval={20}
252
305
  answerType="answer"
253
306
  codeBlock={{
254
- headerActions: true, // 启用代码块头部操作按钮
307
+ headerActions: true, // Enable code block header action buttons
255
308
  }}
256
309
  >
257
310
  {codeContent}
@@ -260,7 +313,7 @@ greet('ds-markdown');
260
313
  }
261
314
  ```
262
315
 
263
- ### Mermaid图表支持
316
+ ### Mermaid Chart Support
264
317
 
265
318
  [DEMO](https://stackblitz.com/edit/vitejs-vite-iqbyta3j?file=README.md)
266
319
 
@@ -271,28 +324,28 @@ import mermaidPlugin from 'ds-markdown-mermaid-plugin';
271
324
  import 'ds-markdown/style.css';
272
325
 
273
326
  function MermaidDemo() {
274
- const chartContent = `以下是简化版的学习开车流程图，仅保留 **最核心步骤**，适合快速掌握关键节点：
327
+ const chartContent = `Here's a simplified learning to drive flowchart, keeping only the **most core steps**, suitable for quickly mastering key nodes:
275
328
 
276
329
  \`\`\`mermaid
277
330
  graph TD
278
- A[开始] --> B[科目一: 理论考试]
279
- B --> C[科目二: 场地五项]
280
- C --> D[科目三: 路考]
281
- D --> E[科目四: 安全笔试]
282
- E --> F[拿驾照]
283
- F --> G[实际驾驶练习]
331
+ A[Start] --> B[Subject 1: Theory Exam]
332
+ B --> C[Subject 2: Field Five Items]
333
+ C --> D[Subject 3: Road Test]
334
+ D --> E[Subject 4: Safety Written Test]
335
+ E --> F[Get Driver's License]
336
+ F --> G[Actual Driving Practice]
284
337
  \`\`\`
285
338
 
286
- ### 极简说明：
287
- 1. **理论先行**：先通过交通规则笔试（科目一）。
288
- 2. **场地基础**：练习倒车、坡起等（科目二）。
289
- 3. **上路实战**：实际道路驾驶考试（科目三）。
290
- 4. **安全收尾**：通过科目四即可领证。
291
- 5. **持续熟练**：拿证后继续练习适应真实路况。
339
+ ### Minimalist Explanation:
340
+ 1. **Theory First**: Pass traffic rules written test (Subject 1).
341
+ 2. **Field Basics**: Practice reversing, hill starts, etc. (Subject 2).
342
+ 3. **Road Combat**: Actual road driving test (Subject 3).
343
+ 4. **Safety Finish**: Pass Subject 4 to get license.
344
+ 5. **Continuous Proficiency**: Continue practicing after getting license to adapt to real road conditions.
292
345
 
293
- ### 可视化建议：
294
- - 用手机备忘录或白纸手绘时，按 **箭头顺序** 写步骤即可。
295
- - 想更直观？用圆形便签贴出每个科目，连线成流程。`;
346
+ ### Visualization Suggestions:
347
+ - When sketching with phone memo or white paper, write steps in **arrow order**.
348
+ - Want more intuitive? Use circular sticky notes for each subject, connect them into a flow.`;
296
349
 
297
350
  return (
298
351
  <ConfigProvider>
@@ -304,187 +357,142 @@ graph TD
304
357
  }
305
358
  ```
306
359
 
307
- ![效果预览](./assets/images/mermaid.gif)
360
+ ![Effect Preview](./assets/images/mermaid.gif)
308
361
 
309
362
  ---
310
363
 
311
- ## 📚 完整 API 文档
364
+ ## 📚 Complete API Documentation
312
365
 
313
- ### 默认导出 DsMarkdown 和 MarkdownCMD 的 props
366
+ ### Default export DsMarkdown and MarkdownCMD props
314
367
 
315
368
  ```js
316
369
  import DsMarkdown, { MarkdownCMD } from 'ds-markdown';
317
370
  ```
318
371
 
319
- | 属性 | 类型 | 说明 | 默认值 |
320
- | ------------------- | ------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------- |
321
- | `interval` | `number` \| `IntervalConfig` | 打字间隔配置，支持固定间隔或动态速度控制 | `30` |
322
- | `timerType` | `'setTimeout'` \| `'requestAnimationFrame'` | 定时器类型，不支持动态修改 | 当前默认值是`setTimeout`，后期会改为`requestAnimationFrame` |
323
- | `answerType` | `'thinking'` \| `'answer'` | 内容类型 (影响样式主题)，不支持动态修改 | `'answer'` |
324
- | `theme` | `'light'` \| `'dark'` | 主题类型 | `'light'` |
325
- | `plugins` | `IMarkdownPlugin[]` | 插件配置 | `[]` |
326
- | `math` | [IMarkdownMath](#IMarkdownMath) | 数学公式配置 | `{ splitSymbol: 'dollar' }` |
327
- | `onEnd` | `(data: EndData) => void` | 打字结束回调 | - |
328
- | `onStart` | `(data: StartData) => void` | 打字开始回调 | - |
329
- | `onBeforeTypedChar` | `(data: IBeforeTypedChar) => Promise<void>` | 字符打字前的回调，支持异步操作，会阻塞之后的打字 | - |
330
- | `onTypedChar` | `(data: ITypedChar) => void` | 每字符打字后的回调 | - |
331
- | `disableTyping` | `boolean` | 禁用打字动画效果 | `false` |
332
- | `autoStartTyping` | `boolean` | 是否自动开始打字动画，设为 false 时需手动触发，不支持动态修改 | `true` |
333
- | `codeBlock` | `IMarkdownCode` | 代码块配置 | `{headerActions: true}` |
334
-
335
- > 注意：打字进行中将 `disableTyping` 从 `true` 改为 `false` 只会从当前位置继续，不会回放已跳过的动画；若需从头播放，请调用实例方法 `restart()`。
372
+ | Property | Type | Description | Default Value |
373
+ | ------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
374
+ | `interval` | `number` | Typing interval (milliseconds) | `30` |
375
+ | `timerType` | `'setTimeout'` \| `'requestAnimationFrame'` | Timer type, does not support dynamic modification | Current default is `setTimeout`, will change to `requestAnimationFrame` later |
376
+ | `answerType` | `'thinking'` \| `'answer'` | Content type (affects style theme), does not support dynamic modification | `'answer'` |
377
+ | `theme` | `'light'` \| `'dark'` | Theme type | `'light'` |
378
+ | `plugins` | `IMarkdownPlugin[]` | Plugin configuration | `[]` |
379
+ | `math` | [IMarkdownMath](#IMarkdownMath) | Mathematical formula configuration | `{ splitSymbol: 'dollar' }` |
380
+ | `onEnd` | `(data: EndData) => void` | Typing completion callback | - |
381
+ | `onStart` | `(data: StartData) => void` | Typing start callback | - |
382
+ | `onBeforeTypedChar` | `(data: IBeforeTypedChar) => Promise<void>` | Callback before character typing, supports async operations, blocks subsequent typing | - |
383
+ | `onTypedChar` | `(data: ITypedChar) => void` | Callback after each character typing | - |
384
+ | `disableTyping` | `boolean` | Disable typing animation effects | `false` |
385
+ | `autoStartTyping` | `boolean` | Whether to automatically start typing animation, set to false for manual trigger, does not support dynamic modification | `true` |
386
+ | `codeBlock` | `IMarkdownCode` | Code block configuration | `{headerActions: true}` |
387
+
388
+ > Note: If `disableTyping` changes from `true` to `false` during typing
336
389
 
337
390
  ### IBeforeTypedChar
338
391
 
339
- | 属性 | 类型 | 说明 | 默认值 |
340
- | -------------- | ------------ | ---------------------------- | ------ |
341
- | `currentIndex` | `number` | 当前字符在整个字符串中的索引 | `0` |
342
- | `currentChar` | `string` | 当前即将打字的字符 | - |
343
- | `answerType` | `AnswerType` | 内容类型 (thinking/answer) | - |
344
- | `prevStr` | `string` | 当前类型内容的前缀字符串 | - |
345
- | `percent` | `number` | 打字进度百分比 (0-100) | `0` |
392
+ | Property | Type | Description | Default Value |
393
+ | -------------- | ------------ | -------------------------------------------- | ------------- |
394
+ | `currentIndex` | `number` | Current character index in the entire string | `0` |
395
+ | `currentChar` | `string` | Current character about to be typed | - |
396
+ | `answerType` | `AnswerType` | Content type (thinking/answer) | - |
397
+ | `prevStr` | `string` | Prefix string of current type content | - |
398
+ | `percent` | `number` | Typing progress percentage (0-100) | `0` |
346
399
 
347
400
  ### ITypedChar
348
401
 
349
- | 属性 | 类型 | 说明 | 默认值 |
350
- | -------------- | ------------ | ---------------------------- | ------ |
351
- | `currentIndex` | `number` | 当前字符在整个字符串中的索引 | `0` |
352
- | `currentChar` | `string` | 当前已打字的字符 | - |
353
- | `answerType` | `AnswerType` | 内容类型 (thinking/answer) | - |
354
- | `prevStr` | `string` | 当前类型内容的前缀字符串 | - |
355
- | `currentStr` | `string` | 当前类型内容的完整字符串 | - |
356
- | `percent` | `number` | 打字进度百分比 (0-100) | `0` |
357
-
358
- #### IntervalConfig 🆕
359
-
360
- | 属性 | 类型 | 说明 | 默认值 |
361
- | --------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------- | -------- |
362
- | `max` | `number` | 最大间隔时间 (毫秒)，剩余字符多时使用 | - |
363
- | `min` | `number` | 最小间隔时间 (毫秒)，剩余字符少时使用 | - |
364
- | `curveFn` | `(x: number) => number` | 自定义曲线函数，x 为剩余字符占比 [0,1] | - |
365
- | `curve` | `'ease'` \| `'ease-in'` \| `'ease-out'` \| `'ease-in-out'` \| `'linear'` \| `'step-start'` \| `'step-end'` | 预设曲线函数，curveFn 存在时无效 | `'ease'` |
366
-
367
- **动态速度控制说明：**
368
-
369
- - **剩余字符越多，打字越快**：当后端流式推送大量字符时，组件会自动加快打字速度
370
- - **剩余字符越少，打字越慢**：接近完成时，打字速度会逐渐放缓，提供更好的阅读体验
371
- - **流式数据适配**：自动适应流式场景中字符数量的动态变化
372
- - **曲线函数**：通过 `curve` 或 `curveFn` 控制速度变化曲线
373
-
374
- **使用示例：**
375
-
376
- ```tsx
377
- // 固定间隔
378
- <DsMarkdown interval={20}>内容</DsMarkdown>
379
-
380
- // 动态速度控制
381
- <DsMarkdown
382
- interval={{
383
- min: 10, // 最快 10ms
384
- max: 50, // 最慢 50ms
385
- curve: 'ease-out' // 减速曲线
386
- }}
387
- >
388
- 内容
389
- </DsMarkdown>
390
-
391
- // 自定义曲线
392
- <DsMarkdown
393
- interval={{
394
- min: 5,
395
- max: 100,
396
- curveFn: (x) => x * x // 二次函数曲线
397
- }}
398
- >
399
- 内容
400
- </DsMarkdown>
401
- ```
402
+ | Property | Type | Description | Default Value |
403
+ | -------------- | ------------ | -------------------------------------------- | ------------- |
404
+ | `currentIndex` | `number` | Current character index in the entire string | `0` |
405
+ | `currentChar` | `string` | Current typed character | - |
406
+ | `answerType` | `AnswerType` | Content type (thinking/answer) | - |
407
+ | `prevStr` | `string` | Prefix string of current type content | - |
408
+ | `currentStr` | `string` | Complete string of current type content | - |
409
+ | `percent` | `number` | Typing progress percentage (0-100) | `0` |
402
410
 
403
411
  #### IMarkdownMath
404
412
 
405
- | 属性 | 类型 | 说明 | 默认值 |
406
- | ------------- | ------------------------- | ------------------ | ---------- |
407
- | `splitSymbol` | `'dollar'` \| `'bracket'` | 数学公式分隔符类型 | `'dollar'` |
413
+ | Property | Type | Description | Default Value |
414
+ | ------------- | ------------------------- | --------------------------- | ------------- |
415
+ | `splitSymbol` | `'dollar'` \| `'bracket'` | Math formula delimiter type | `'dollar'` |
408
416
 
409
- **分隔符说明：**
417
+ **Delimiter Description:**
410
418
 
411
- - `'dollar'`：使用 `$...$` 和 `$$...$$` 语法
412
- - `'bracket'`：使用 `\(...\)` 和 `\[...\]` 语法
419
+ - `'dollar'`: Uses `$...$` and `$$...$$` syntax
420
+ - `'bracket'`: Uses `\(...\)` and `\[...\]` syntax
413
421
 
414
422
  #### IMarkdownCode 🆕
415
423
 
416
- | 属性 | 类型 | 说明 | 默认值 |
417
- | --------------- | --------- | -------------------- | ------ |
418
- | `headerActions` | `boolean` | 是否显示头部操作按钮 | `true` |
424
+ | Property | Type | Description | Default Value |
425
+ | --------------- | --------- | ------------------------------------- | ------------- |
426
+ | `headerActions` | `boolean` | Whether to show header action buttons | `true` |
419
427
 
420
428
  #### IMarkdownPlugin
421
429
 
422
- | 属性 | 类型 | 说明 | 默认值 |
423
- | -------------- | ---------------------------------------------- | ----------------- | ------ |
424
- | `remarkPlugin` | `Pluggable` | remark 插件 | - |
425
- | `rehypePlugin` | `Pluggable` | rehype 插件 | - |
426
- | `type` | `'buildIn'` \| `'custom'` | 插件类型 | - |
427
- | `id` | `any` | 插件唯一标识 | - |
428
- | `components` | `Record<string, React.ComponentType<unknown>>` | 自定义组件映射 🆕 | - |
430
+ | Property | Type | Description | Default Value |
431
+ | -------------- | ---------------------------------------------- | --------------------------- | ------------- |
432
+ | `remarkPlugin` | `Pluggable` | remark plugin | - |
433
+ | `rehypePlugin` | `Pluggable` | rehype plugin | - |
434
+ | `type` | `'buildIn'` \| `'custom'` | Plugin type | - |
435
+ | `id` | `any` | Plugin unique identifier | - |
436
+ | `components` | `Record<string, React.ComponentType<unknown>>` | Custom component mapping 🆕 | - |
429
437
 
430
- ### 组件暴露的方法
438
+ ### Component Exposed Methods
431
439
 
432
- #### 默认导出 DsMarkdown
440
+ #### Default export DsMarkdown
433
441
 
434
- | 方法 | 参数 | 说明 |
435
- | --------- | ---- | -------------------------------------- |
436
- | `start` | - | 开始打字动画 |
437
- | `stop` | - | 暂停打字动画 |
438
- | `resume` | - | 恢复打字动画 |
439
- | `restart` | - | 重新开始打字动画，从头开始播放当前内容 |
442
+ | Method | Parameters | Description |
443
+ | --------- | ---------- | ------------------------------------------------------------- |
444
+ | `start` | - | Start typing animation |
445
+ | `stop` | - | Pause typing animation |
446
+ | `resume` | - | Resume typing animation |
447
+ | `restart` | - | Restart typing animation, play current content from beginning |
440
448
 
441
- #### MarkdownCMD 暴露的方法
449
+ #### MarkdownCMD Exposed Methods
442
450
 
443
- | 方法 | 参数 | 说明 |
444
- | ----------------- | ------------------------------------------- | -------------------------------------- |
445
- | `push` | `(content: string, answerType: AnswerType)` | 添加内容并开始打字 |
446
- | `clear` | - | 清空所有内容和状态 |
447
- | `triggerWholeEnd` | - | 手动触发完成回调 |
448
- | `start` | - | 开始打字动画 |
449
- | `stop` | - | 暂停打字动画 |
450
- | `resume` | - | 恢复打字动画 |
451
- | `restart` | - | 重新开始打字动画，从头开始播放当前内容 |
451
+ | Method | Parameters | Description |
452
+ | ----------------- | ------------------------------------------- | ------------------------------------------------------------- |
453
+ | `push` | `(content: string, answerType: AnswerType)` | Add content and start typing |
454
+ | `clear` | - | Clear all content and state |
455
+ | `triggerWholeEnd` | - | Manually trigger completion callback |
456
+ | `start` | - | Start typing animation |
457
+ | `stop` | - | Pause typing animation |
458
+ | `resume` | - | Resume typing animation |
459
+ | `restart` | - | Restart typing animation, play current content from beginning |
452
460
 
453
- **用法示例：**
461
+ **Usage Examples:**
454
462
 
455
463
  ```tsx
456
- markdownRef.current?.start(); // 开始动画
457
- markdownRef.current?.stop(); // 暂停动画
458
- markdownRef.current?.resume(); // 恢复动画
459
- markdownRef.current?.restart(); // 重新开始动画
464
+ markdownRef.current?.start(); // Start animation
465
+ markdownRef.current?.stop(); // Pause animation
466
+ markdownRef.current?.resume(); // Resume animation
467
+ markdownRef.current?.restart(); // Restart animation
460
468
  ```
461
469
 
462
470
  ---
463
471
 
464
- ## 🔌 插件系统
472
+ ## 🔌 Plugin System
465
473
 
466
- ### 内置插件
474
+ ### Built-in Plugins
467
475
 
468
- #### KaTeX 数学公式插件
476
+ #### KaTeX Mathematical Formula Plugin
469
477
 
470
478
  [DEMO](https://stackblitz.com/edit/vitejs-vite-iqbyta3j?file=index.html)
471
479
 
472
480
  ```tsx
473
481
  import { katexPlugin } from 'ds-markdown/plugins';
474
482
 
475
- // 启用数学公式支持
476
- <DsMarkdown plugins={[katexPlugin]}>数学公式：$E = mc^2$</DsMarkdown>;
483
+ // Enable mathematical formula support
484
+ <DsMarkdown plugins={[katexPlugin]}>Math formula: $E = mc^2$</DsMarkdown>;
477
485
  ```
478
486
 
479
- #### Mermaid 图表插件 🆕
487
+ #### Mermaid Chart Plugin 🆕
480
488
 
481
- **安装 Mermaid 插件：**
489
+ **Install Mermaid Plugin:**
482
490
 
483
491
  ```bash
484
492
  npm install ds-markdown-mermaid-plugin
485
493
  ```
486
494
 
487
- **基础用法：**
495
+ **Basic Usage:**
488
496
 
489
497
  ```tsx
490
498
  import { ConfigProvider, Markdown } from 'ds-markdown';
@@ -492,14 +500,14 @@ import mermaidPlugin from 'ds-markdown-mermaid-plugin';
492
500
 
493
501
  function App() {
494
502
  const content = `
495
- # 流程图示例
503
+ # Flowchart Example
496
504
 
497
505
  \`\`\`mermaid
498
506
  flowchart TD
499
- A[开始] --> B{判断条件}
500
- B -->|是| C[处理A]
501
- B -->|否| D[处理B]
502
- C --> E[结束]
507
+ A[Start] --> B{Decision}
508
+ B -->|Yes| C[Process A]
509
+ B -->|No| D[Process B]
510
+ C --> E[End]
503
511
  D --> E
504
512
  \`\`\`
505
513
  `;
@@ -512,24 +520,24 @@ flowchart TD
512
520
  }
513
521
  ```
514
522
 
515
- **支持的图表类型：**
523
+ **Supported Chart Types:**
516
524
 
517
- - 🔄 **流程图** (Flowchart) - 展示流程和决策路径
518
- - 📋 **序列图** (Sequence Diagram) - 展示对象间的交互时序
519
- - 📅 **甘特图** (Gantt Chart) - 项目计划和时间线
520
- - 🏗️ **类图** (Class Diagram) - 面向对象设计
521
- - 🥧 **饼图** (Pie Chart) - 数据比例展示
522
- - 🔀 **状态图** (State Diagram) - 状态转换流程
523
- - 📊 **Git图** (Git Graph) - 代码分支历史
524
- - 🗺️ **用户旅程图** (User Journey) - 用户体验流程
525
+ - 🔄 **Flowchart** - Display processes and decision paths
526
+ - 📋 **Sequence Diagram** - Display interaction timing between objects
527
+ - 📅 **Gantt Chart** - Project planning and timelines
528
+ - 🏗️ **Class Diagram** - Object-oriented design
529
+ - 🥧 **Pie Chart** - Data proportion display
530
+ - 🔀 **State Diagram** - State transition processes
531
+ - 📊 **Git Graph** - Code branch history
532
+ - 🗺️ **User Journey** - User experience flow
525
533
 
526
- **配置 Mermaid：**
534
+ **Configure Mermaid:**
527
535
 
528
536
  ```tsx
529
537
  import { ConfigProvider } from 'ds-markdown';
530
538
 
531
539
  const mermaidConfig = {
532
- theme: 'default', // 主题：default, neutral, dark, forest
540
+ theme: 'default', // Theme: default, neutral, dark, forest
533
541
  flowchart: {
534
542
  useMaxWidth: true,
535
543
  htmlLabels: true,
@@ -547,38 +555,38 @@ return (
547
555
  );
548
556
  ```
549
557
 
550
- **相关链接：**
558
+ **Related Links:**
551
559
 
552
560
  - [ds-markdown-mermaid-plugin GitHub](https://github.com/onshinpei/ds-markdown-mermaid-plugin)
553
- - [Mermaid 官方文档](https://mermaid.js.org/)
561
+ - [Mermaid Official Documentation](https://mermaid.js.org/)
554
562
 
555
- ### 自定义插件
563
+ ### Custom Plugins
556
564
 
557
565
  ```tsx
558
566
  import { createBuildInPlugin } from 'ds-markdown/plugins';
559
567
 
560
- // 创建自定义插件
568
+ // Create custom plugin
561
569
  const customPlugin = createBuildInPlugin({
562
570
  remarkPlugin: yourRemarkPlugin,
563
571
  rehypePlugin: yourRehypePlugin,
564
572
  id: Symbol('custom-plugin'),
565
573
  components: {
566
- // 自定义组件映射 🆕
574
+ // Custom component mapping 🆕
567
575
  CustomComponent: MyCustomComponent,
568
576
  },
569
577
  });
570
578
 
571
- // 使用自定义插件
572
- <DsMarkdown plugins={[katexPlugin, customPlugin]}>内容</DsMarkdown>;
579
+ // Use custom plugin
580
+ <DsMarkdown plugins={[katexPlugin, customPlugin]}>Content</DsMarkdown>;
573
581
  ```
574
582
 
575
583
  ---
576
584
 
577
- ## 🎨 UI组件系统 🆕
585
+ ## 🎨 UI Component System 🆕
578
586
 
579
- ds-markdown 提供了丰富的UI组件，可以单独使用或与markdown组件配合。
587
+ ds-markdown provides rich UI components that can be used individually or in combination with markdown components.
580
588
 
581
- ### 核心组件
589
+ ### Core Components
582
590
 
583
591
  ```tsx
584
592
  import {
@@ -590,32 +598,32 @@ import {
590
598
  DownloadButton
591
599
  } from 'ds-markdown';
592
600
 
593
- // 按钮组件
601
+ // Button component
594
602
  <Button icon={<span>📄</span>} onClick={() => {}}>
595
- 点击按钮
603
+ Click Button
596
604
  </Button>
597
605
 
598
- // 工具提示
599
- <ToolTip title="提示信息">
606
+ // Tooltip
607
+ <ToolTip title="Tooltip information">
600
608
  <IconButton icon={<span>📋</span>} onClick={() => {}} />
601
609
  </ToolTip>
602
610
 
603
- // 分段控制器
611
+ // Segmented controller
604
612
  <Segmented
605
- Segmented={[
606
- { label: '图表', value: 'diagram' },
607
- { label: '代码', value: 'code' }
613
+ options={[
614
+ { label: 'Chart', value: 'diagram' },
615
+ { label: 'Code', value: 'code' }
608
616
  ]}
609
617
  value={value}
610
618
  onChange={setValue}
611
619
  />
612
620
 
613
- // 代码块操作
621
+ // Code block operations
614
622
  <CopyButton codeContent="console.log('Hello')" />
615
623
  <DownloadButton codeContent="console.log('Hello')" language="javascript" />
616
624
  ```
617
625
 
618
- ### 样式定制
626
+ ### Style Customization
619
627
 
620
628
  ```css
621
629
  :root {
@@ -627,19 +635,19 @@ import {
627
635
 
628
636
  ---
629
637
 
630
- ## 多语言配置
638
+ ## Multi-language Configuration
631
639
 
632
640
  ```tsx
633
641
  import { ConfigProvider } from 'ds-markdown';
634
642
  import zhCN from 'ds-markdown/i18n/zh';
635
643
  import enUS from 'ds-markdown/i18n/en';
636
644
 
637
- // 中文
645
+ // Chinese
638
646
  <ConfigProvider locale={zhCN}>
639
647
  <DsMarkdown {...props} />
640
648
  </ConfigProvider>
641
649
 
642
- // 英文
650
+ // English
643
651
  <ConfigProvider locale={enUS}>
644
652
  <DsMarkdown {...props} />
645
653
  </ConfigProvider>
@@ -647,182 +655,11 @@ import enUS from 'ds-markdown/i18n/en';
647
655
 
648
656
  ---
649
657
 
650
- ## 📚 ConfigProvider API
651
-
652
- `ConfigProvider` 是一个全局配置提供者，用于为 ds-markdown 组件提供多语言、Mermaid 图表和 KaTeX 数学公式的配置。
653
-
654
- ### Props 类型
655
-
656
- ```tsx
657
- interface ConfigProviderProps {
658
- locale?: Locale; // 语言包配置
659
- mermaidConfig?: IMarkdownMermaidConfig; // Mermaid 图表配置
660
- katexConfig?: IMarkdownKatexConfig; // KaTeX 数学公式配置
661
- children: React.ReactNode; // 子组件
662
- }
663
- ```
664
-
665
- ### 配置选项详解
666
-
667
- #### 1. 多语言配置 (locale)
668
-
669
- ```tsx
670
- import { ConfigProvider } from 'ds-markdown';
671
- import zhCN from 'ds-markdown/i18n/zh';
672
- import enUS from 'ds-markdown/i18n/en';
673
-
674
- <ConfigProvider locale={zhCN}>
675
- <DsMarkdown {...props} />
676
- </ConfigProvider>;
677
- ```
678
-
679
- #### 2. Mermaid 图表配置 (mermaidConfig)
680
-
681
- ```tsx
682
- const mermaidConfig = {
683
- theme: 'dark', // 主题：'default' | 'forest' | 'dark' | 'neutral'
684
- fontFamily: 'Arial', // 字体
685
- logLevel: 'warn', // 日志级别
686
- securityLevel: 'strict', // 安全级别
687
- startOnLoad: true, // 页面加载时自动启动
688
- // ... 更多 Mermaid 配置选项
689
- };
690
-
691
- <ConfigProvider mermaidConfig={mermaidConfig}>
692
- <DsMarkdown {...props} />
693
- </ConfigProvider>;
694
- ```
695
-
696
- #### 3. KaTeX 数学公式配置 (katexConfig)
697
-
698
- ```tsx
699
- const katexConfig = {
700
- throwOnError: false, // 错误时不抛出异常
701
- errorColor: '#cc0000', // 错误颜色
702
- macros: {
703
- // 自定义宏
704
- '\\RR': '\\mathbb{R}',
705
- '\\NN': '\\mathbb{N}',
706
- },
707
- minRuleThickness: 0.05, // 最小规则厚度
708
- colorIsTextColor: false, // 颜色是否为文本颜色
709
- // ... 更多 KaTeX 配置选项
710
- };
711
-
712
- <ConfigProvider katexConfig={katexConfig}>
713
- <DsMarkdown {...props} />
714
- </ConfigProvider>;
715
- ```
716
-
717
- ### 使用 Hooks
658
+ ## 💡 Practical Examples
718
659
 
719
- #### useConfig
660
+ ### 📝 AI Streaming Chat
720
661
 
721
- 获取完整的配置上下文：
722
-
723
- ```tsx
724
- import { useConfig } from 'ds-markdown';
725
-
726
- function MyComponent() {
727
- const { locale, mermaidConfig, katexConfig } = useConfig();
728
-
729
- return (
730
- <div>
731
- <p>当前语言: {locale.language}</p>
732
- <p>Mermaid 主题: {mermaidConfig?.theme}</p>
733
- </div>
734
- );
735
- }
736
- ```
737
-
738
- #### useLocale
739
-
740
- 仅获取语言包配置：
741
-
742
- ```tsx
743
- import { useLocale } from 'ds-markdown';
744
-
745
- function MyComponent() {
746
- const locale = useLocale();
747
-
748
- return (
749
- <div>
750
- <p>当前语言: {locale.language}</p>
751
- <p>复制按钮文本: {locale.copyButton}</p>
752
- </div>
753
- );
754
- }
755
- ```
756
-
757
- ### 完整配置示例
758
-
759
- ```tsx
760
- import { ConfigProvider } from 'ds-markdown';
761
- import zhCN from 'ds-markdown/i18n/zh';
762
-
763
- const mermaidConfig = {
764
- theme: 'dark',
765
- fontFamily: 'Consolas, monospace',
766
- logLevel: 'warn',
767
- };
768
-
769
- const katexConfig = {
770
- throwOnError: false,
771
- errorColor: '#cc0000',
772
- macros: {
773
- '\\RR': '\\mathbb{R}',
774
- },
775
- };
776
-
777
- function App() {
778
- return (
779
- <ConfigProvider locale={zhCN} mermaidConfig={mermaidConfig} katexConfig={katexConfig}>
780
- <DsMarkdown content="# Hello World" />
781
- </ConfigProvider>
782
- );
783
- }
784
- ```
785
-
786
- ---
787
-
788
- ## 💡 实战示例
789
-
790
- ### 🚀 动态速度控制 🆕
791
-
792
- ```tsx
793
- import DsMarkdown from 'ds-markdown';
794
-
795
- function DynamicSpeedDemo() {
796
- const content = `# 动态速度控制示例
797
-
798
- 这是一个演示动态速度控制的示例。当剩余字符较多时，打字速度会加快；
799
- 当剩余字符较少时，打字速度会放缓，提供更好的阅读体验。
800
-
801
- ## 流式数据场景
802
-
803
- 在 AI 流式对话中，后端可能会一次性推送大量文本，使用动态速度控制可以：
804
- - 快速处理大量文本，减少等待时间
805
- - 在接近完成时放缓速度，让用户有时间阅读
806
- - 提供更自然的打字体验`;
807
-
808
- return (
809
- <DsMarkdown
810
- interval={{
811
- min: 8, // 最快 8ms（剩余字符多时）
812
- max: 80, // 最慢 80ms（剩余字符少时）
813
- curve: 'ease-out', // 减速曲线
814
- }}
815
- timerType="requestAnimationFrame"
816
- >
817
- {content}
818
- </DsMarkdown>
819
- );
820
- }
821
- ```
822
-
823
- ### 📝 AI 流式对话
824
-
825
- [DEMO: 🔧 StackBlitz 体验](https://stackblitz.com/edit/vitejs-vite-2ri8kex3?file=src%2FApp.tsx)
662
+ [DEMO: 🔧 StackBlitz Experience](https://stackblitz.com/edit/vitejs-vite-2ri8kex3?file=src%2FApp.tsx)
826
663
 
827
664
  ```tsx
828
665
  import { useRef } from 'react';
@@ -830,33 +667,30 @@ import { MarkdownCMD, MarkdownCMDRef } from 'ds-markdown';
830
667
 
831
668
  function StreamingChat() {
832
669
  const markdownRef = useRef<MarkdownCMDRef>(null);
833
- const answerRef = useRef<MarkdownCMDRef>(null);
834
- const [isShowAnswer, setIsShowAnswer] = useState(false);
835
670
 
836
- // 模拟 AI 流式响应
671
+ // Simulate AI streaming response
837
672
  const simulateAIResponse = async () => {
838
673
  markdownRef.current?.clear();
839
- answerRef.current?.clear();
840
674
 
841
- // 思考阶段
842
- markdownRef.current?.push('🤔 正在分析您的问题...', 'thinking');
675
+ // Thinking phase
676
+ markdownRef.current?.push('🤔 Analyzing your question...', 'thinking');
843
677
  await delay(1000);
844
- markdownRef.current?.push('\n\n✅ 分析完成，开始回答', 'thinking');
845
- setIsShowAnswer(true);
846
- // 流式回答
678
+ markdownRef.current?.push('\n\n✅ Analysis complete, starting to answer', 'thinking');
679
+
680
+ // Streaming answer
847
681
  const chunks = [
848
- '# React 19 新特性解析\n\n',
682
+ '# React 19 New Features Analysis\n\n',
849
683
  '## 🚀 React Compiler\n',
850
- 'React 19 最大的亮点是引入了 **React Compiler**：\n\n',
851
- '- 🎯 **自动优化**：无需手动 memo 和 useMemo\n',
852
- '- ⚡ **性能提升**：编译时优化，运行时零开销\n',
853
- '- 🔧 **向后兼容**：现有代码无需修改\n\n',
854
- '希望这个解答对您有帮助！🎉',
684
+ 'The biggest highlight of React 19 is the introduction of **React Compiler**:\n\n',
685
+ '- 🎯 **Automatic Optimization**: No need for manual memo and useMemo\n',
686
+ '- ⚡ **Performance Boost**: Compile-time optimization, zero runtime overhead\n',
687
+ '- 🔧 **Backward Compatible**: Existing code requires no modification\n\n',
688
+ 'Hope this answer helps you! 🎉',
855
689
  ];
856
690
 
857
691
  for (const chunk of chunks) {
858
692
  await delay(100);
859
- answerRef.current?.push(chunk, 'answer');
693
+ markdownRef.current?.push(chunk, 'answer');
860
694
  }
861
695
  };
862
696
 
@@ -864,65 +698,54 @@ function StreamingChat() {
864
698
 
865
699
  return (
866
700
  <div className="chat-container">
867
- <button onClick={simulateAIResponse}>🤖 询问 React 19 新特性</button>
868
- <MarkdownCMD answerType="thinking" ref={markdownRef} interval={10} timerType="requestAnimationFrame" />
869
- {isShowAnswer && <MarkdownCMD answerType="answer" ref={answerRef} interval={10} timerType="requestAnimationFrame" />}
701
+ <button onClick={simulateAIResponse}>🤖 Ask about React 19 New Features</button>
702
+ <MarkdownCMD ref={markdownRef} interval={10} timerType="requestAnimationFrame" />
870
703
  </div>
871
704
  );
872
705
  }
873
706
  ```
874
707
 
875
- ## 🔧 最佳实践
708
+ ## 🔧 Best Practices
876
709
 
877
- ### 1. 性能优化
710
+ ### 1. Performance Optimization
878
711
 
879
712
  ```tsx
880
- // ✅ 推荐配置
881
- <DsMarkdown
882
- timerType="requestAnimationFrame"
883
- interval={15} // 15-30ms 为最佳体验
884
- />
885
-
886
- // ✅ 流式数据推荐配置
713
+ // ✅ Recommended configuration
887
714
  <DsMarkdown
888
715
  timerType="requestAnimationFrame"
889
- interval={{
890
- min: 8, // 快速处理大量文本
891
- max: 60, // 接近完成时放缓
892
- curve: 'ease-out' // 自然减速
893
- }}
716
+ interval={15} // 15-30ms for best experience
894
717
  />
895
718
  ```
896
719
 
897
- ### 2. 流式数据处理
720
+ ### 2. Streaming Data Processing
898
721
 
899
722
  ```tsx
900
- // ✅ 推荐：命令式 API
723
+ // ✅ Recommended: Imperative API
901
724
  const ref = useRef<MarkdownCMDRef>(null);
902
725
  useEffect(() => {
903
- ref.current?.push(newChunk);
726
+ ref.current?.push(newChunk, 'answer');
904
727
  }, [newChunk]);
905
728
  ```
906
729
 
907
- ### 3. 数学公式优化
730
+ ### 3. Mathematical Formula Optimization
908
731
 
909
732
  ```tsx
910
- // ✅ 推荐：按需加载
733
+ // ✅ Recommended: Load on demand
911
734
  import { katexPlugin } from 'ds-markdown/plugins';
912
- import 'ds-markdown/katex.css'; // 仅在需要时引入
735
+ import 'ds-markdown/katex.css'; // Only import when needed
913
736
 
914
- <DsMarkdown plugins={[katexPlugin]}>数学公式内容</DsMarkdown>;
737
+ <DsMarkdown plugins={[katexPlugin]}>Mathematical formula content</DsMarkdown>;
915
738
  ```
916
739
 
917
- ### 4. Mermaid图表最佳实践 🆕
740
+ ### 4. Mermaid Chart Best Practices 🆕
918
741
 
919
742
  ```tsx
920
- // ✅ 推荐：独立安装插件
743
+ // ✅ Recommended: Install plugin separately
921
744
  npm install ds-markdown-mermaid-plugin
922
745
 
923
- // ✅ 推荐：配置适合的主题
746
+ // ✅ Recommended: Configure suitable themes
924
747
  const mermaidConfig = {
925
- theme: 'default', // 根据应用主题选择
748
+ theme: 'default', // Choose based on application theme
926
749
  flowchart: { useMaxWidth: true },
927
750
  };
928
751