@data_wise/hyper-markdown 1.5.0 → 1.5.2

package/README.md

@@ -1,816 +1,816 @@
-# @data_wise/hyper-markdown
-
-一个功能强大的 Vue 3 Markdown 编辑器，支持 ECharts、Mermaid、KaTeX 和数据集等丰富功能。
-
-## 安装
-
-```bash
-npm install @data_wise/hyper-markdown
-```
-
-## CSS 导入
-
-组件已经内置了所有必要的样式文件，您只需要在项目中导入一次CSS即可使用所有功能：
-
-### 在 Vue 项目中导入
-
-```javascript
-import '@data_wise/hyper-markdown/dist/hyper-markdown.css'
-```
-
-### 完整使用示例
-
-```vue
-<template>
-  <div id="app">
-    <MarkdownEditor 
-      :content="markdownContent" 
-      :editable="true"
-    />
-  </div>
-</template>
-
-<script>
-import MarkdownEditor from '@data_wise/hyper-markdown'
-import '@data_wise/hyper-markdown/dist/hyper-markdown.css' // 导入CSS
-
-export default {
-  name: 'App',
-  components: {
-    MarkdownEditor
-  },
-  data() {
-    return {
-      markdownContent: '# 欢迎使用 Hyper Markdown'
-    }
-  }
-}
-</script>
-```
-
-### 包含的样式
-
-导入的CSS文件包含以下所有必要的样式：
-
-- **GitHub Markdown 样式** - 标准的Markdown渲染样式
-- **KaTeX 数学公式样式** - 数学公式渲染支持
-- **ECharts 图表样式** - 图表组件样式
-- **Mermaid 流程图样式** - 流程图渲染样式
-- **数据集表格样式** - 数据表格展示样式
-- **自定义容器样式** - 警告、提示等容器样式
-- **栅格布局样式** - 响应式布局支持
-
-### 注意事项
-
-- 只需要导入一次CSS文件，所有组件功能即可正常工作
-- CSS文件已经过优化，所有样式都打包到单个文件中
-- 无需额外配置或导入其他CSS文件
-
-## 快速开始
-
-### 组件属性
-
-| 属性 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `content` | String | `''` | Markdown 内容（支持 v-model） |
-| `editable` | Boolean | `false` | 是否启用编辑模式 |
-| `defaultShowEditor` | Boolean | `true` | 编辑器初始显示状态（仅在 editable 为 true 时有效） |
-| `datasource` | Object | - | 数据源配置对象（可选） |
-
-### 组件事件
-
-| 事件名 | 参数 | 说明 |
-|--------|------|------|
-| `update:content` | `(content: string)` | 内容更新时触发 |
-| `errors` | `(errors: Array)` | 渲染错误时触发，返回错误数组 |
-
-#### 错误对象格式
-
-```javascript
-{
-  line: 10,              // 错误所在行号
-  type: 'ECharts',       // 错误类型：ECharts, Dataset, Mermaid, Container
-  message: '配置错误',    // 错误描述
-  code: '```echarts...',  // 相关代码片段
-  severity: 'error'      // 错误级别
-}
-```
-
-#### 错误收集说明
-
-组件会自动收集以下类型的渲染错误：
-
-- **ECharts 错误**：图表配置错误、数据格式错误等
-- **Mermaid 错误**：流程图语法错误
-- **Dataset 错误**：数据集格式错误、数据源查询失败等
-- **Container 错误**：容器配置错误（如 cell 宽度超出范围）
-
-错误会在渲染完成后自动收集，并通过 `@errors` 事件传递给外部。你可以：
-
-1. **监听事件**：`@errors="handleErrors"` 实时获取错误
-2. **主动获取**：`this.$refs.editor.getErrors()` 获取当前错误列表
-
-### 基础用法
-
-```vue
-<template>
-  <div id="app">
-    <MarkdownEditor 
-      :content="markdownContent" 
-      :editable="true"
-      @errors="handleErrors"
-    />
-  </div>
-</template>
-
-<script>
-import MarkdownEditor from '@data_wise/hyper-markdown'
-
-export default {
-  name: 'App',
-  components: {
-    MarkdownEditor
-  },
-  data() {
-    return {
-      markdownContent: '# 欢迎使用 Hyper Markdown'
-    }
-  },
-  methods: {
-    handleErrors(errors) {
-      // 处理渲染错误
-      if (errors.length > 0) {
-        console.log('发现渲染错误:', errors)
-        errors.forEach(error => {
-          console.error(`第 ${error.line} 行 [${error.type}]: ${error.message}`)
-        })
-      }
-    }
-  }
-}
-</script>
-```
-
-### 控制编辑器显示状态
-
-```vue
-<template>
-  <div id="app">
-    <!-- 默认隐藏编辑器，只显示预览 -->
-    <MarkdownEditor 
-      :content="markdownContent" 
-      :editable="true"
-      :default-show-editor="false"
-    />
-  </div>
-</template>
-
-<script>
-import MarkdownEditor from '@data_wise/hyper-markdown'
-
-export default {
-  name: 'App',
-  components: {
-    MarkdownEditor
-  },
-  data() {
-    return {
-      markdownContent: '# 欢迎使用 Hyper Markdown'
-    }
-  }
-}
-</script>
-```
-
-### 使用数据源功能
-
-要使用数据源查询功能，需要注入 `datasource` 属性：
-
-```vue
-<template>
-  <div id="app">
-    <MarkdownEditor 
-      v-model:content="markdownContent" 
-      :editable="true"
-      :datasource="datasource"
-    />
-  </div>
-</template>
-
-<script>
-import MarkdownEditor from '@data_wise/hyper-markdown'
-import { datasource } from './utils/dataSource' // 导入数据源函数
-
-export default {
-  name: 'App',
-  components: {
-    MarkdownEditor
-  },
-  data() {
-    return {
-      markdownContent: '# 欢迎使用 Hyper Markdown',
-      datasource: datasource // 注入数据源函数
-    }
-  }
-}
-</script>
-```
-
-## 数据源配置
-
-### 数据源函数接口
-
-`datasource` 对象必须包含以下函数：
-
-```javascript
-{
-  // 获取数据源数据
-  getDataSource(sourceId, sql, options) => Promise<Object>
-  
-  // 获取数据源列表
-  getDataSourceList() => Array
-  
-  // 清除数据缓存
-  clearDataSourceCache(sourceId) => void
-  
-  // 测试数据源连接
-  testDataSourceConnection(sourceId) => Promise<boolean>
-}
-```
-
-### 内置数据源
-
-项目内置了以下模拟数据源：
-
-- **sales_db** - 销售数据库（MySQL）
-- **user_db** - 用户数据库（PostgreSQL）  
-- **finance_db** - 财务数据库（Oracle）
-
-### 自定义数据源
-
-您可以创建自定义数据源函数：
-
-```javascript
-// 自定义数据源函数示例
-const customDatasource = {
-  async getDataSource(sourceId, sql, options = {}) {
-    // 实现数据获取逻辑
-    return {
-      source: [], // 数据数组
-      dimensions: [], // 维度字段
-      metadata: {
-        sourceId: sourceId,
-        sql: sql,
-        count: 0,
-        timestamp: new Date().toISOString()
-      }
-    }
-  },
-  
-  getDataSourceList() {
-    return [
-      {
-        id: 'my_db',
-        name: '我的数据库',
-        type: 'mysql',
-        description: '自定义数据源'
-      }
-    ]
-  },
-  
-  clearDataSourceCache(sourceId = null) {
-    // 清除缓存逻辑
-  },
-  
-  async testDataSourceConnection(sourceId) {
-    return true
-  }
-}
-```
-
-## 特有插件语法
-
-### 1. ECharts 图表
-
-使用 `echarts` 代码块渲染图表：
-
-````markdown
-```echarts
-{
-  "title": {
-    "text": "销售数据"
-  },
-  "xAxis": {
-    "type": "category",
-    "data": ["一月", "二月", "三月"]
-  },
-  "yAxis": {
-    "type": "value"
-  },
-  "series": [{
-    "data": [120, 200, 150],
-    "type": "bar"
-  }]
-}
-```
-````
-
-### 2. Mermaid 流程图
-
-使用 `mermaid` 代码块渲染流程图：
-
-````markdown
-```mermaid
-graph TD
-    A[开始] --> B{条件判断}
-    B -->|是| C[执行操作]
-    B -->|否| D[结束]
-    C --> D
-```
-````
-
-### 3. 数据集功能
-
-使用 `dataset` 代码块定义数据集：
-
-````markdown
-```dataset datasetId: sales_data
-{
-  dimensions: ["产品", "2020", "2021", "2022"],
-  source: [
-    {产品: "产品A", 2020: 100, 2021: 120, 2022: 150},
-    {产品: "产品B", 2020: 80, 2021: 90, 2022: 110},
-    {产品: "产品C", 2020: 60, 2021: 70, 2022: 85}
-  ]
-}
-```
-
-然后在 ECharts 中使用数据集：
-
-```echarts
-{
-  dataset: dataset['sales_data'],
-  title: { text: "产品销售趋势" },
-  xAxis: { type: "category" },
-  yAxis: { type: "value" },
-  series: [{
-    type: "bar",
-    encode: { x: "产品", y: "2020" }
-  }]
-}
-```
-````
-
-#### ⚠️ 使用 dataset + encode 时的注意事项
-
-使用 `dataset` + `encode` 时，formatter 必须用**函数形式**，字符串模板会显示 `[object Object]`：
-
-````markdown
-```echarts
-{
-  dataset: dataset['sales_data'],
-  series: [{
-    type: "pie",
-    encode: { itemName: "产品", value: "销量" },
-    label: {
-      // ❌ 错误：formatter: "{b}: {c}次 ({d}%)"
-      // ✅ 正确：使用函数
-      formatter: function(params) {
-        return params.data['产品'] + ': ' + params.data['销量'] + '次 (' + params.percent + '%)';
-      }
-    }
-  }]
-}
-```
-````
-
-### 4. D3.js 可视化
-
-支持使用 D3.js 创建自定义可视化图表，提供两种使用方式：
-
-#### 方式一：JSON 配置（快速创建）
-
-使用预定义的图表类型快速创建可视化：
-
-````markdown
-```d3
-{
-  "type": "bar",
-  "data": [30, 86, 168, 281, 303, 365],
-  "width": 600,
-  "height": 400,
-  "color": "#5470c6"
-}
-```
-````
-
-**支持的图表类型：**
-- `bar` - 柱状图
-- `line` - 折线图
-- `pie` - 饼图
-- `scatter` - 散点图
-
-**配置选项：**
-- `type` - 图表类型（必需）
-- `data` - 数据数组或 dataset 引用（必需）
-- `width` - 图表宽度（默认 600）
-- `height` - 图表高度（默认 400）
-- `color` - 颜色
-- `xField` / `yField` - 数据字段映射
-- `nameField` / `valueField` - 饼图字段映射
-
-#### 方式二：自定义 D3 代码（完全控制）
-
-编写完整的 D3.js 代码实现自定义可视化：
-
-````markdown
-```d3
-// 创建 SVG
-const svg = d3.select(container)
-  .append('svg')
-  .attr('width', 600)
-  .attr('height', 400);
-
-// 绘制圆圈
-const data = [10, 20, 30, 40, 50];
-svg.selectAll('circle')
-  .data(data)
-  .enter()
-  .append('circle')
-  .attr('cx', (d, i) => 50 + i * 100)
-  .attr('cy', 200)
-  .attr('r', d => d)
-  .attr('fill', '#5470c6');
-```
-````
-
-**可用变量：**
-- `container` - DOM 容器元素
-- `d3` - D3.js 库对象
-- `dataset` - 数据集对象（访问已定义的数据集）
-- `theme` - 当前主题（'light' 或 'dark'）
-
-#### 与 Dataset 集成
-
-D3 图表可以直接使用 dataset 中定义的数据：
-
-````markdown
-```dataset datasetId: sales_data
-{
-  dimensions: ["产品", "销量"],
-  source: [
-    { 产品: "手机", 销量: 520 },
-    { 产品: "电脑", 销量: 380 },
-    { 产品: "平板", 销量: 290 }
-  ]
-}
-```
-
-**JSON 配置方式：**
-```d3
-{
-  "type": "bar",
-  "data": "dataset['sales_data']",
-  "xField": "产品",
-  "yField": "销量",
-  "width": 600,
-  "height": 400
-}
-```
-
-**自定义代码方式：**
-```d3
-// 获取数据集
-const data = dataset['sales_data'].source;
-
-// 使用 D3 绘制
-const svg = d3.select(container)
-  .append('svg')
-  .attr('width', 600)
-  .attr('height', 400);
-
-// ... 更多 D3 代码
-```
-````
-
-#### 主题适配
-
-D3 图表会自动适配明暗主题，可以在代码中使用 `theme` 变量：
-
-````markdown
-```d3
-const textColor = theme === 'dark' ? '#e0e0e0' : '#000';
-
-svg.append('text')
-  .attr('fill', textColor)
-  .text('标题');
-```
-````
-
-### 5. SQL 数据源查询
-
-支持从数据源查询数据，需要先注入 `datasource` 属性：
-
-#### 查询语法格式
-
-支持两种格式的数据源查询：
-
-**格式一：使用 datasourceId 指定数据源**
-
-````markdown
-```dataset datasetId: sql_query_1 datasourceId: sales_db
-SELECT 产品, 年份, 销售额 FROM sales_data WHERE 销售额 > 100
-```
-````
-
-**格式二：使用默认数据源（sales_db）**
-
-````markdown
-```dataset datasetId: sql_query_1
-SELECT 产品, 年份, 销售额 FROM sales_data WHERE 销售额 > 100
-```
-````
-
-#### 使用查询结果
-
-查询结果会自动转换为标准数据集格式，可以在 ECharts 中使用：
-
-```echarts
-{
-  dataset: dataset['sql_query_1'],
-  title: { text: "产品销售趋势" },
-  xAxis: { type: "category" },
-  yAxis: { type: "value" },
-  series: [{
-    type: "bar",
-    encode: { x: "产品", y: "销售额" }
-  }]
-}
-```
-
-#### 示例：完整的数据源查询
-
-````markdown
-```dataset datasetId: user_analysis datasourceId: user_db
-SELECT 地区, 用户数, 活跃度 FROM user_data WHERE 用户数 > 1000 AND 活跃度 > 0.7
-```
-
-```echarts
-{
-  dataset: dataset['user_analysis'],
-  title: { text: "用户分布分析" },
-  xAxis: { type: "category" },
-  yAxis: { type: "value" },
-  series: [{
-    type: "bar",
-    encode: { x: "地区", y: "用户数" }
-  }]
-}
-```
-````
-
-### 5. SQL 数据源查询
-
-支持从数据源查询数据，需要先注入 `datasource` 属性：
-
-#### 查询语法格式
-
-支持两种格式的数据源查询：
-
-**格式一：使用 datasourceId 指定数据源**
-
-````markdown
-```dataset datasetId: sql_query_1 datasourceId: sales_db
-SELECT 产品, 年份, 销售额 FROM sales_data WHERE 销售额 > 100
-```
-````
-
-**格式二：使用默认数据源（sales_db）**
-
-````markdown
-```dataset datasetId: sql_query_1
-SELECT 产品, 年份, 销售额 FROM sales_data WHERE 销售额 > 100
-```
-````
-
-#### 使用查询结果
-
-查询结果会自动转换为标准数据集格式，可以在 ECharts 或 D3 中使用：
-
-```echarts
-{
-  dataset: dataset['sql_query_1'],
-  title: { text: "产品销售趋势" },
-  xAxis: { type: "category" },
-  yAxis: { type: "value" },
-  series: [{
-    type: "bar",
-    encode: { x: "产品", y: "销售额" }
-  }]
-}
-```
-
-#### 示例：完整的数据源查询
-
-````markdown
-```dataset datasetId: user_analysis datasourceId: user_db
-SELECT 地区, 用户数, 活跃度 FROM user_data WHERE 用户数 > 1000 AND 活跃度 > 0.7
-```
-
-```echarts
-{
-  dataset: dataset['user_analysis'],
-  title: { text: "用户分布分析" },
-  xAxis: { type: "category" },
-  yAxis: { type: "value" },
-  series: [{
-    type: "bar",
-    encode: { x: "地区", y: "用户数" }
-  }]
-}
-```
-````
-
-### 6. 栅格布局
-
-使用 `cell` 容器创建响应式布局：
-
-````markdown
-::: cell 6
-### 大单元格 (6格宽)
-这是一个较大的单元格，宽度占6格
-
-可以包含任何 Markdown 语法：
-- 列表项
-- 图片
-- 代码等
-:::
-
-::: cell 3
-### 中等单元格 (3格宽)
-中等大小的单元格
-
-```javascript
-console.log('支持代码块');
-```
-:::
-````
-
-### 7. 自定义容器
-
-支持多种自定义容器：
-
-````markdown
-::: info
-这是一个信息提示
-:::
-
-::: warning
-这是一个警告信息
-:::
-
-::: danger
-这是一个危险提示
-:::
-
-::: success
-这是一个成功提示
-:::
-````
-
-
-
-## 数据源使用注意事项
-
-### 错误处理
-
-当数据源查询失败时，会显示错误信息：
-
-- **数据源未注入**："数据源获取函数未注入，请确保已设置datasource属性"
-- **数据源不存在**："数据源不存在: {sourceId}"
-- **SQL语法错误**："SQL查询语句不能为空" 或 "数据源查询格式不正确"
-
-### 缓存机制
-
-数据源查询结果会自动缓存，避免重复查询：
-
-- 相同查询条件会返回缓存结果
-- 可以通过 `clearDataSourceCache()` 清除缓存
-- 使用 `{forceRefresh: true}` 选项强制刷新
-
-### 性能优化
-
-- 数据源查询支持异步处理
-- 支持延迟加载选项 `{delay: 500}`
-- 内置数据源使用模拟数据，无网络请求
-
-## 特性
-
-- ✅ Vue 3 支持
-- ✅ ECharts 图表渲染
-- ✅ D3.js 可视化支持（新功能）
-- ✅ Mermaid 流程图支持
-- ✅ KaTeX 数学公式
-- ✅ 数据集表格展示
-- ✅ 可编辑区域
-- ✅ 自定义容器
-- ✅ 响应式设计
-- ✅ TypeScript 支持
-- ✅ 数据源查询功能
-- ✅ SQL 语法支持
-- ✅ 数据缓存机制
-- ✅ **Word 文档导出**
-- ✅ **Dashboard 看板模式**
-
-## Word 导出功能
-
-支持将 Markdown 内容导出为 Word 文档（.docx 格式）：
-
-```vue
-<template>
-  <div>
-    <button @click="exportToWord">导出 Word</button>
-    <MarkdownEditor ref="editor" v-model:content="content" :editable="true" />
-  </div>
-</template>
-
-<script>
-export default {
-  methods: {
-    async exportToWord() {
-      const result = await this.$refs.editor.exportToWord('我的文档.docx')
-      if (result.success) {
-        console.log('导出成功！')
-      }
-    }
-  }
-}
-</script>
-```
-
-**支持导出：**
-- 标题、段落、列表、表格
-- 粗体、斜体、代码块
-- **ECharts 图表**（自动转为图片）
-- **Mermaid 流程图**（自动转为图片）
-
-**详细文档：** 查看 [EXPORT.md](./docs/EXPORT.md)
-
-## Dashboard 看板模式
-
-支持将数据集集中管理的看板模式，通过添加 `<!-- dashboard -->` 注释激活：
-
-```markdown
-<!-- dashboard -->
-
-# 销售数据看板
-
-\`\`\`dataset datasetId: sales_data
-{
-  dimensions: ["月份", "销售额"],
-  source: [
-    { 月份: "1月", 销售额: 12500 },
-    { 月份: "2月", 销售额: 13800 }
-  ]
-}
-\`\`\`
-
-\`\`\`echarts
-{
-  dataset: dataset['sales_data'],
-  xAxis: { type: "category" },
-  yAxis: { type: "value" },
-  series: [{ type: "line", encode: { x: "月份", y: "销售额" } }]
-}
-\`\`\`
-```
-
-**Dashboard 模式特性：**
-- 左侧抽屉显示所有数据集
-- 数据集不在正文中显示
-- 支持搜索、刷新、导出
-- 数据预览功能
-
-**详细文档：** 查看 [DASHBOARD.md](./docs/DASHBOARD.md)
-
-## 特性
-
-- ✅ Vue 3 支持
-- ✅ ECharts 图表渲染
-- ✅ D3.js 可视化支持
-- ✅ Mermaid 流程图支持
-- ✅ KaTeX 数学公式
-- ✅ 数据集表格展示
-- ✅ 可编辑区域
-- ✅ 自定义容器
-- ✅ 响应式设计
-- ✅ TypeScript 支持
-- ✅ 数据源查询功能
-- ✅ SQL 语法支持
-- ✅ 数据缓存机制
-- ✅ Word 文档导出
-- ✅ Dashboard 看板模式
-
-## 许可证
-
+# @data_wise/hyper-markdown
+
+一个功能强大的 Vue 3 Markdown 编辑器，支持 ECharts、Mermaid、KaTeX 和数据集等丰富功能。
+
+## 安装
+
+```bash
+npm install @data_wise/hyper-markdown
+```
+
+## CSS 导入
+
+组件已经内置了所有必要的样式文件，您只需要在项目中导入一次CSS即可使用所有功能：
+
+### 在 Vue 项目中导入
+
+```javascript
+import '@data_wise/hyper-markdown/dist/hyper-markdown.css'
+```
+
+### 完整使用示例
+
+```vue
+<template>
+  <div id="app">
+    <MarkdownEditor 
+      :content="markdownContent" 
+      :editable="true"
+    />
+  </div>
+</template>
+
+<script>
+import MarkdownEditor from '@data_wise/hyper-markdown'
+import '@data_wise/hyper-markdown/dist/hyper-markdown.css' // 导入CSS
+
+export default {
+  name: 'App',
+  components: {
+    MarkdownEditor
+  },
+  data() {
+    return {
+      markdownContent: '# 欢迎使用 Hyper Markdown'
+    }
+  }
+}
+</script>
+```
+
+### 包含的样式
+
+导入的CSS文件包含以下所有必要的样式：
+
+- **GitHub Markdown 样式** - 标准的Markdown渲染样式
+- **KaTeX 数学公式样式** - 数学公式渲染支持
+- **ECharts 图表样式** - 图表组件样式
+- **Mermaid 流程图样式** - 流程图渲染样式
+- **数据集表格样式** - 数据表格展示样式
+- **自定义容器样式** - 警告、提示等容器样式
+- **栅格布局样式** - 响应式布局支持
+
+### 注意事项
+
+- 只需要导入一次CSS文件，所有组件功能即可正常工作
+- CSS文件已经过优化，所有样式都打包到单个文件中
+- 无需额外配置或导入其他CSS文件
+
+## 快速开始
+
+### 组件属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `content` | String | `''` | Markdown 内容（支持 v-model） |
+| `editable` | Boolean | `false` | 是否启用编辑模式 |
+| `defaultShowEditor` | Boolean | `true` | 编辑器初始显示状态（仅在 editable 为 true 时有效） |
+| `datasource` | Object | - | 数据源配置对象（可选） |
+
+### 组件事件
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| `update:content` | `(content: string)` | 内容更新时触发 |
+| `errors` | `(errors: Array)` | 渲染错误时触发，返回错误数组 |
+
+#### 错误对象格式
+
+```javascript
+{
+  line: 10,              // 错误所在行号
+  type: 'ECharts',       // 错误类型：ECharts, Dataset, Mermaid, Container
+  message: '配置错误',    // 错误描述
+  code: '```echarts...',  // 相关代码片段
+  severity: 'error'      // 错误级别
+}
+```
+
+#### 错误收集说明
+
+组件会自动收集以下类型的渲染错误：
+
+- **ECharts 错误**：图表配置错误、数据格式错误等
+- **Mermaid 错误**：流程图语法错误
+- **Dataset 错误**：数据集格式错误、数据源查询失败等
+- **Container 错误**：容器配置错误（如 cell 宽度超出范围）
+
+错误会在渲染完成后自动收集，并通过 `@errors` 事件传递给外部。你可以：
+
+1. **监听事件**：`@errors="handleErrors"` 实时获取错误
+2. **主动获取**：`this.$refs.editor.getErrors()` 获取当前错误列表
+
+### 基础用法
+
+```vue
+<template>
+  <div id="app">
+    <MarkdownEditor 
+      :content="markdownContent" 
+      :editable="true"
+      @errors="handleErrors"
+    />
+  </div>
+</template>
+
+<script>
+import MarkdownEditor from '@data_wise/hyper-markdown'
+
+export default {
+  name: 'App',
+  components: {
+    MarkdownEditor
+  },
+  data() {
+    return {
+      markdownContent: '# 欢迎使用 Hyper Markdown'
+    }
+  },
+  methods: {
+    handleErrors(errors) {
+      // 处理渲染错误
+      if (errors.length > 0) {
+        console.log('发现渲染错误:', errors)
+        errors.forEach(error => {
+          console.error(`第 ${error.line} 行 [${error.type}]: ${error.message}`)
+        })
+      }
+    }
+  }
+}
+</script>
+```
+
+### 控制编辑器显示状态
+
+```vue
+<template>
+  <div id="app">
+    <!-- 默认隐藏编辑器，只显示预览 -->
+    <MarkdownEditor 
+      :content="markdownContent" 
+      :editable="true"
+      :default-show-editor="false"
+    />
+  </div>
+</template>
+
+<script>
+import MarkdownEditor from '@data_wise/hyper-markdown'
+
+export default {
+  name: 'App',
+  components: {
+    MarkdownEditor
+  },
+  data() {
+    return {
+      markdownContent: '# 欢迎使用 Hyper Markdown'
+    }
+  }
+}
+</script>
+```
+
+### 使用数据源功能
+
+要使用数据源查询功能，需要注入 `datasource` 属性：
+
+```vue
+<template>
+  <div id="app">
+    <MarkdownEditor 
+      v-model:content="markdownContent" 
+      :editable="true"
+      :datasource="datasource"
+    />
+  </div>
+</template>
+
+<script>
+import MarkdownEditor from '@data_wise/hyper-markdown'
+import { datasource } from './utils/dataSource' // 导入数据源函数
+
+export default {
+  name: 'App',
+  components: {
+    MarkdownEditor
+  },
+  data() {
+    return {
+      markdownContent: '# 欢迎使用 Hyper Markdown',
+      datasource: datasource // 注入数据源函数
+    }
+  }
+}
+</script>
+```
+
+## 数据源配置
+
+### 数据源函数接口
+
+`datasource` 对象必须包含以下函数：
+
+```javascript
+{
+  // 获取数据源数据
+  getDataSource(sourceId, sql, options) => Promise<Object>
+  
+  // 获取数据源列表
+  getDataSourceList() => Array
+  
+  // 清除数据缓存
+  clearDataSourceCache(sourceId) => void
+  
+  // 测试数据源连接
+  testDataSourceConnection(sourceId) => Promise<boolean>
+}
+```
+
+### 内置数据源
+
+项目内置了以下模拟数据源：
+
+- **sales_db** - 销售数据库（MySQL）
+- **user_db** - 用户数据库（PostgreSQL）  
+- **finance_db** - 财务数据库（Oracle）
+
+### 自定义数据源
+
+您可以创建自定义数据源函数：
+
+```javascript
+// 自定义数据源函数示例
+const customDatasource = {
+  async getDataSource(sourceId, sql, options = {}) {
+    // 实现数据获取逻辑
+    return {
+      source: [], // 数据数组
+      dimensions: [], // 维度字段
+      metadata: {
+        sourceId: sourceId,
+        sql: sql,
+        count: 0,
+        timestamp: new Date().toISOString()
+      }
+    }
+  },
+  
+  getDataSourceList() {
+    return [
+      {
+        id: 'my_db',
+        name: '我的数据库',
+        type: 'mysql',
+        description: '自定义数据源'
+      }
+    ]
+  },
+  
+  clearDataSourceCache(sourceId = null) {
+    // 清除缓存逻辑
+  },
+  
+  async testDataSourceConnection(sourceId) {
+    return true
+  }
+}
+```
+
+## 特有插件语法
+
+### 1. ECharts 图表
+
+使用 `echarts` 代码块渲染图表：
+
+````markdown
+```echarts
+{
+  "title": {
+    "text": "销售数据"
+  },
+  "xAxis": {
+    "type": "category",
+    "data": ["一月", "二月", "三月"]
+  },
+  "yAxis": {
+    "type": "value"
+  },
+  "series": [{
+    "data": [120, 200, 150],
+    "type": "bar"
+  }]
+}
+```
+````
+
+### 2. Mermaid 流程图
+
+使用 `mermaid` 代码块渲染流程图：
+
+````markdown
+```mermaid
+graph TD
+    A[开始] --> B{条件判断}
+    B -->|是| C[执行操作]
+    B -->|否| D[结束]
+    C --> D
+```
+````
+
+### 3. 数据集功能
+
+使用 `dataset` 代码块定义数据集：
+
+````markdown
+```dataset datasetId: sales_data
+{
+  dimensions: ["产品", "2020", "2021", "2022"],
+  source: [
+    {产品: "产品A", 2020: 100, 2021: 120, 2022: 150},
+    {产品: "产品B", 2020: 80, 2021: 90, 2022: 110},
+    {产品: "产品C", 2020: 60, 2021: 70, 2022: 85}
+  ]
+}
+```
+
+然后在 ECharts 中使用数据集：
+
+```echarts
+{
+  dataset: dataset['sales_data'],
+  title: { text: "产品销售趋势" },
+  xAxis: { type: "category" },
+  yAxis: { type: "value" },
+  series: [{
+    type: "bar",
+    encode: { x: "产品", y: "2020" }
+  }]
+}
+```
+````
+
+#### ⚠️ 使用 dataset + encode 时的注意事项
+
+使用 `dataset` + `encode` 时，formatter 必须用**函数形式**，字符串模板会显示 `[object Object]`：
+
+````markdown
+```echarts
+{
+  dataset: dataset['sales_data'],
+  series: [{
+    type: "pie",
+    encode: { itemName: "产品", value: "销量" },
+    label: {
+      // ❌ 错误：formatter: "{b}: {c}次 ({d}%)"
+      // ✅ 正确：使用函数
+      formatter: function(params) {
+        return params.data['产品'] + ': ' + params.data['销量'] + '次 (' + params.percent + '%)';
+      }
+    }
+  }]
+}
+```
+````
+
+### 4. D3.js 可视化
+
+支持使用 D3.js 创建自定义可视化图表，提供两种使用方式：
+
+#### 方式一：JSON 配置（快速创建）
+
+使用预定义的图表类型快速创建可视化：
+
+````markdown
+```d3
+{
+  "type": "bar",
+  "data": [30, 86, 168, 281, 303, 365],
+  "width": 600,
+  "height": 400,
+  "color": "#5470c6"
+}
+```
+````
+
+**支持的图表类型：**
+- `bar` - 柱状图
+- `line` - 折线图
+- `pie` - 饼图
+- `scatter` - 散点图
+
+**配置选项：**
+- `type` - 图表类型（必需）
+- `data` - 数据数组或 dataset 引用（必需）
+- `width` - 图表宽度（默认 600）
+- `height` - 图表高度（默认 400）
+- `color` - 颜色
+- `xField` / `yField` - 数据字段映射
+- `nameField` / `valueField` - 饼图字段映射
+
+#### 方式二：自定义 D3 代码（完全控制）
+
+编写完整的 D3.js 代码实现自定义可视化：
+
+````markdown
+```d3
+// 创建 SVG
+const svg = d3.select(container)
+  .append('svg')
+  .attr('width', 600)
+  .attr('height', 400);
+
+// 绘制圆圈
+const data = [10, 20, 30, 40, 50];
+svg.selectAll('circle')
+  .data(data)
+  .enter()
+  .append('circle')
+  .attr('cx', (d, i) => 50 + i * 100)
+  .attr('cy', 200)
+  .attr('r', d => d)
+  .attr('fill', '#5470c6');
+```
+````
+
+**可用变量：**
+- `container` - DOM 容器元素
+- `d3` - D3.js 库对象
+- `dataset` - 数据集对象（访问已定义的数据集）
+- `theme` - 当前主题（'light' 或 'dark'）
+
+#### 与 Dataset 集成
+
+D3 图表可以直接使用 dataset 中定义的数据：
+
+````markdown
+```dataset datasetId: sales_data
+{
+  dimensions: ["产品", "销量"],
+  source: [
+    { 产品: "手机", 销量: 520 },
+    { 产品: "电脑", 销量: 380 },
+    { 产品: "平板", 销量: 290 }
+  ]
+}
+```
+
+**JSON 配置方式：**
+```d3
+{
+  "type": "bar",
+  "data": "dataset['sales_data']",
+  "xField": "产品",
+  "yField": "销量",
+  "width": 600,
+  "height": 400
+}
+```
+
+**自定义代码方式：**
+```d3
+// 获取数据集
+const data = dataset['sales_data'].source;
+
+// 使用 D3 绘制
+const svg = d3.select(container)
+  .append('svg')
+  .attr('width', 600)
+  .attr('height', 400);
+
+// ... 更多 D3 代码
+```
+````
+
+#### 主题适配
+
+D3 图表会自动适配明暗主题，可以在代码中使用 `theme` 变量：
+
+````markdown
+```d3
+const textColor = theme === 'dark' ? '#e0e0e0' : '#000';
+
+svg.append('text')
+  .attr('fill', textColor)
+  .text('标题');
+```
+````
+
+### 5. SQL 数据源查询
+
+支持从数据源查询数据，需要先注入 `datasource` 属性：
+
+#### 查询语法格式
+
+支持两种格式的数据源查询：
+
+**格式一：使用 datasourceId 指定数据源**
+
+````markdown
+```dataset datasetId: sql_query_1 datasourceId: sales_db
+SELECT 产品, 年份, 销售额 FROM sales_data WHERE 销售额 > 100
+```
+````
+
+**格式二：使用默认数据源（sales_db）**
+
+````markdown
+```dataset datasetId: sql_query_1
+SELECT 产品, 年份, 销售额 FROM sales_data WHERE 销售额 > 100
+```
+````
+
+#### 使用查询结果
+
+查询结果会自动转换为标准数据集格式，可以在 ECharts 中使用：
+
+```echarts
+{
+  dataset: dataset['sql_query_1'],
+  title: { text: "产品销售趋势" },
+  xAxis: { type: "category" },
+  yAxis: { type: "value" },
+  series: [{
+    type: "bar",
+    encode: { x: "产品", y: "销售额" }
+  }]
+}
+```
+
+#### 示例：完整的数据源查询
+
+````markdown
+```dataset datasetId: user_analysis datasourceId: user_db
+SELECT 地区, 用户数, 活跃度 FROM user_data WHERE 用户数 > 1000 AND 活跃度 > 0.7
+```
+
+```echarts
+{
+  dataset: dataset['user_analysis'],
+  title: { text: "用户分布分析" },
+  xAxis: { type: "category" },
+  yAxis: { type: "value" },
+  series: [{
+    type: "bar",
+    encode: { x: "地区", y: "用户数" }
+  }]
+}
+```
+````
+
+### 5. SQL 数据源查询
+
+支持从数据源查询数据，需要先注入 `datasource` 属性：
+
+#### 查询语法格式
+
+支持两种格式的数据源查询：
+
+**格式一：使用 datasourceId 指定数据源**
+
+````markdown
+```dataset datasetId: sql_query_1 datasourceId: sales_db
+SELECT 产品, 年份, 销售额 FROM sales_data WHERE 销售额 > 100
+```
+````
+
+**格式二：使用默认数据源（sales_db）**
+
+````markdown
+```dataset datasetId: sql_query_1
+SELECT 产品, 年份, 销售额 FROM sales_data WHERE 销售额 > 100
+```
+````
+
+#### 使用查询结果
+
+查询结果会自动转换为标准数据集格式，可以在 ECharts 或 D3 中使用：
+
+```echarts
+{
+  dataset: dataset['sql_query_1'],
+  title: { text: "产品销售趋势" },
+  xAxis: { type: "category" },
+  yAxis: { type: "value" },
+  series: [{
+    type: "bar",
+    encode: { x: "产品", y: "销售额" }
+  }]
+}
+```
+
+#### 示例：完整的数据源查询
+
+````markdown
+```dataset datasetId: user_analysis datasourceId: user_db
+SELECT 地区, 用户数, 活跃度 FROM user_data WHERE 用户数 > 1000 AND 活跃度 > 0.7
+```
+
+```echarts
+{
+  dataset: dataset['user_analysis'],
+  title: { text: "用户分布分析" },
+  xAxis: { type: "category" },
+  yAxis: { type: "value" },
+  series: [{
+    type: "bar",
+    encode: { x: "地区", y: "用户数" }
+  }]
+}
+```
+````
+
+### 6. 栅格布局
+
+使用 `cell` 容器创建响应式布局：
+
+````markdown
+::: cell 6
+### 大单元格 (6格宽)
+这是一个较大的单元格，宽度占6格
+
+可以包含任何 Markdown 语法：
+- 列表项
+- 图片
+- 代码等
+:::
+
+::: cell 3
+### 中等单元格 (3格宽)
+中等大小的单元格
+
+```javascript
+console.log('支持代码块');
+```
+:::
+````
+
+### 7. 自定义容器
+
+支持多种自定义容器：
+
+````markdown
+::: info
+这是一个信息提示
+:::
+
+::: warning
+这是一个警告信息
+:::
+
+::: danger
+这是一个危险提示
+:::
+
+::: success
+这是一个成功提示
+:::
+````
+
+
+
+## 数据源使用注意事项
+
+### 错误处理
+
+当数据源查询失败时，会显示错误信息：
+
+- **数据源未注入**："数据源获取函数未注入，请确保已设置datasource属性"
+- **数据源不存在**："数据源不存在: {sourceId}"
+- **SQL语法错误**："SQL查询语句不能为空" 或 "数据源查询格式不正确"
+
+### 缓存机制
+
+数据源查询结果会自动缓存，避免重复查询：
+
+- 相同查询条件会返回缓存结果
+- 可以通过 `clearDataSourceCache()` 清除缓存
+- 使用 `{forceRefresh: true}` 选项强制刷新
+
+### 性能优化
+
+- 数据源查询支持异步处理
+- 支持延迟加载选项 `{delay: 500}`
+- 内置数据源使用模拟数据，无网络请求
+
+## 特性
+
+- ✅ Vue 3 支持
+- ✅ ECharts 图表渲染
+- ✅ D3.js 可视化支持（新功能）
+- ✅ Mermaid 流程图支持
+- ✅ KaTeX 数学公式
+- ✅ 数据集表格展示
+- ✅ 可编辑区域
+- ✅ 自定义容器
+- ✅ 响应式设计
+- ✅ TypeScript 支持
+- ✅ 数据源查询功能
+- ✅ SQL 语法支持
+- ✅ 数据缓存机制
+- ✅ **Word 文档导出**
+- ✅ **Dashboard 看板模式**
+
+## Word 导出功能
+
+支持将 Markdown 内容导出为 Word 文档（.docx 格式）：
+
+```vue
+<template>
+  <div>
+    <button @click="exportToWord">导出 Word</button>
+    <MarkdownEditor ref="editor" v-model:content="content" :editable="true" />
+  </div>
+</template>
+
+<script>
+export default {
+  methods: {
+    async exportToWord() {
+      const result = await this.$refs.editor.exportToWord('我的文档.docx')
+      if (result.success) {
+        console.log('导出成功！')
+      }
+    }
+  }
+}
+</script>
+```
+
+**支持导出：**
+- 标题、段落、列表、表格
+- 粗体、斜体、代码块
+- **ECharts 图表**（自动转为图片）
+- **Mermaid 流程图**（自动转为图片）
+
+**详细文档：** 查看 [EXPORT.md](./docs/EXPORT.md)
+
+## Dashboard 看板模式
+
+支持将数据集集中管理的看板模式，通过添加 `<!-- dashboard -->` 注释激活：
+
+```markdown
+<!-- dashboard -->
+
+# 销售数据看板
+
+\`\`\`dataset datasetId: sales_data
+{
+  dimensions: ["月份", "销售额"],
+  source: [
+    { 月份: "1月", 销售额: 12500 },
+    { 月份: "2月", 销售额: 13800 }
+  ]
+}
+\`\`\`
+
+\`\`\`echarts
+{
+  dataset: dataset['sales_data'],
+  xAxis: { type: "category" },
+  yAxis: { type: "value" },
+  series: [{ type: "line", encode: { x: "月份", y: "销售额" } }]
+}
+\`\`\`
+```
+
+**Dashboard 模式特性：**
+- 左侧抽屉显示所有数据集
+- 数据集不在正文中显示
+- 支持搜索、刷新、导出
+- 数据预览功能
+
+**详细文档：** 查看 [DASHBOARD.md](./docs/DASHBOARD.md)
+
+## 特性
+
+- ✅ Vue 3 支持
+- ✅ ECharts 图表渲染
+- ✅ D3.js 可视化支持
+- ✅ Mermaid 流程图支持
+- ✅ KaTeX 数学公式
+- ✅ 数据集表格展示
+- ✅ 可编辑区域
+- ✅ 自定义容器
+- ✅ 响应式设计
+- ✅ TypeScript 支持
+- ✅ 数据源查询功能
+- ✅ SQL 语法支持
+- ✅ 数据缓存机制
+- ✅ Word 文档导出
+- ✅ Dashboard 看板模式
+
+## 许可证
+
 MIT License