A powerful Vue 3 Markdown editor with rich features including ECharts, D3.js, Mermaid, KaTeX, and dataset support
npm install @data_wise/hyper-markdown一个功能强大的 Vue 3 Markdown 编辑器，支持 ECharts、Mermaid、KaTeX 和数据集等丰富功能。
``bash`
npm install @data_wise/hyper-markdown
组件已经内置了所有必要的样式文件，您只需要在项目中导入一次CSS即可使用所有功能：
`javascript`
import '@data_wise/hyper-markdown/dist/hyper-markdown.css'
`vue
:editable="true"
/>
`
导入的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" 实时获取错误this.$refs.editor.getErrors()
2. 主动获取： 获取当前错误列表
`vue
:editable="true"
@errors="handleErrors"
/>
`
`vue
:editable="true"
:default-show-editor="false"
/>
`
要使用数据源查询功能，需要注入 datasource 属性：
`vue
:editable="true"
:datasource="datasource"
/>
`
datasource 对象必须包含以下函数：
`javascript`
{
// 获取数据源数据
getDataSource(sourceId, sql, options) => Promise
项目内置了以下模拟数据源：
- 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
}
}
使用 echarts 代码块渲染图表：
``markdown`echarts`
{
"title": {
"text": "销售数据"
},
"xAxis": {
"type": "category",
"data": ["一月", "二月", "三月"]
},
"yAxis": {
"type": "value"
},
"series": [{
"data": [120, 200, 150],
"type": "bar"
}]
}
使用 mermaid 代码块渲染流程图：
``markdown`mermaid`
graph TD
A[开始] --> B{条件判断}
B -->|是| C[执行操作]
B -->|否| D[结束]
C --> D
使用 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 + '%)';
}
}
}]
}
支持使用 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('标题');
`
支持从数据源查询数据，需要先注入 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: "用户数" }
}]
}
支持从数据源查询数据，需要先注入 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: "用户数" }
}]
}
使用 cell 容器创建响应式布局：
``markdown
::: cell 6$3
这是一个较大的单元格，宽度占6格
可以包含任何 Markdown 语法：
- 列表项
- 图片
- 代码等
:::
::: cell 3
`javascript`
console.log('支持代码块');
:::
支持多种自定义容器：
``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 看板模式
支持将 Markdown 内容导出为 Word 文档（.docx 格式）：
`vue
`
支持导出：
- 标题、段落、列表、表格
- 粗体、斜体、代码块
- ECharts 图表（自动转为图片）
- Mermaid 流程图（自动转为图片）
详细文档： 查看 EXPORT.md
支持将数据集集中管理的看板模式，通过添加 注释激活：
`markdown
\\\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