@data_wise/hyper-markdown

@data_wise/hyper-markdown

一个功能强大的 Vue 3 Markdown 编辑器，支持 ECharts、Mermaid、KaTeX 和数据集等丰富功能。

安装

npm install @data_wise/hyper-markdown

CSS 导入

组件已经内置了所有必要的样式文件，您只需要在项目中导入一次CSS即可使用所有功能：

在 Vue 项目中导入

import '@data_wise/hyper-markdown/dist/hyper-markdown.css'

完整使用示例

<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文件

快速开始

组件属性

组件事件

错误对象格式

{
  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() 获取当前错误列表

基础用法

<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>

控制编辑器显示状态

<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 属性：

<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 对象必须包含以下函数：

{
  // 获取数据源数据
  getDataSource(sourceId, sql, options) => Promise<Object>
  
  // 获取数据源列表
  getDataSourceList() => Array
  
  // 清除数据缓存
  clearDataSourceCache(sourceId) => void
  
  // 测试数据源连接
  testDataSourceConnection(sourceId) => Promise<boolean>
}

内置数据源

项目内置了以下模拟数据源：

• sales_db - 销售数据库（MySQL）
• user_db - 用户数据库（PostgreSQL）
• finance_db - 财务数据库（Oracle）

自定义数据源

您可以创建自定义数据源函数：

// 自定义数据源函数示例
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 代码块渲染图表：

```echarts
{
  "title": {
    "text": "销售数据"
  },
  "xAxis": {
    "type": "category",
    "data": ["一月", "二月", "三月"]
  },
  "yAxis": {
    "type": "value"
  },
  "series": [{
    "data": [120, 200, 150],
    "type": "bar"
  }]
}
```

2. Mermaid 流程图

使用 mermaid 代码块渲染流程图：

```mermaid
graph TD
    A[开始] --> B{条件判断}
    B -->|是| C[执行操作]
    B -->|否| D[结束]
    C --> D
```

3. 数据集功能

使用 dataset 代码块定义数据集：

```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]：

```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 配置（快速创建）

使用预定义的图表类型快速创建可视化：

```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 代码实现自定义可视化：

```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 中定义的数据：

```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 变量：

```d3
const textColor = theme === 'dark' ? '#e0e0e0' : '#000';

svg.append('text')
  .attr('fill', textColor)
  .text('标题');
```

5. SQL 数据源查询

支持从数据源查询数据，需要先注入 datasource 属性：

查询语法格式

支持两种格式的数据源查询：

格式一：使用 datasourceId 指定数据源

```dataset datasetId: sql_query_1 datasourceId: sales_db
SELECT 产品, 年份, 销售额 FROM sales_data WHERE 销售额 > 100
```

格式二：使用默认数据源（sales_db）

```dataset datasetId: sql_query_1
SELECT 产品, 年份, 销售额 FROM sales_data WHERE 销售额 > 100
```

使用查询结果

查询结果会自动转换为标准数据集格式，可以在 ECharts 中使用：

{
  dataset: dataset['sql_query_1'],
  title: { text: "产品销售趋势" },
  xAxis: { type: "category" },
  yAxis: { type: "value" },
  series: [{
    type: "bar",
    encode: { x: "产品", y: "销售额" }
  }]
}

示例：完整的数据源查询

```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 指定数据源

```dataset datasetId: sql_query_1 datasourceId: sales_db
SELECT 产品, 年份, 销售额 FROM sales_data WHERE 销售额 > 100
```

格式二：使用默认数据源（sales_db）

```dataset datasetId: sql_query_1
SELECT 产品, 年份, 销售额 FROM sales_data WHERE 销售额 > 100
```

使用查询结果

查询结果会自动转换为标准数据集格式，可以在 ECharts 或 D3 中使用：

{
  dataset: dataset['sql_query_1'],
  title: { text: "产品销售趋势" },
  xAxis: { type: "category" },
  yAxis: { type: "value" },
  series: [{
    type: "bar",
    encode: { x: "产品", y: "销售额" }
  }]
}

示例：完整的数据源查询

```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 容器创建响应式布局：

::: cell 6
### 大单元格 (6格宽)
这是一个较大的单元格，宽度占6格

可以包含任何 Markdown 语法：
- 列表项
- 图片
- 代码等
:::

::: cell 3
### 中等单元格 (3格宽)
中等大小的单元格

```javascript
console.log('支持代码块');
```
:::

7. 自定义容器

支持多种自定义容器：

::: 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 格式）：

<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

Dashboard 看板模式

支持将数据集集中管理的看板模式，通过添加 <!-- dashboard --> 注释激活：

<!-- 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

特性

• ✅ Vue 3 支持
• ✅ ECharts 图表渲染
• ✅ D3.js 可视化支持
• ✅ Mermaid 流程图支持
• ✅ KaTeX 数学公式
• ✅ 数据集表格展示
• ✅ 可编辑区域
• ✅ 自定义容器
• ✅ 响应式设计
• ✅ TypeScript 支持
• ✅ 数据源查询功能
• ✅ SQL 语法支持
• ✅ 数据缓存机制
• ✅ Word 文档导出
• ✅ Dashboard 看板模式

许可证

MIT License