# @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. 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. 栅格布局

使用 `cell` 容器创建响应式布局：

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

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

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

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

### 6. 自定义容器

支持多种自定义容器：

````markdown
::: info
这是一个信息提示
:::

::: warning
这是一个警告信息
:::

::: danger
这是一个危险提示
:::

::: success
这是一个成功提示
:::
````



## 数据源使用注意事项

### 错误处理

当数据源查询失败时，会显示错误信息：

- **数据源未注入**："数据源获取函数未注入，请确保已设置datasource属性"
- **数据源不存在**："数据源不存在: {sourceId}"
- **SQL语法错误**："SQL查询语句不能为空" 或 "数据源查询格式不正确"

### 缓存机制

数据源查询结果会自动缓存，避免重复查询：

- 相同查询条件会返回缓存结果
- 可以通过 `clearDataSourceCache()` 清除缓存
- 使用 `{forceRefresh: true}` 选项强制刷新

### 性能优化

- 数据源查询支持异步处理
- 支持延迟加载选项 `{delay: 500}`
- 内置数据源使用模拟数据，无网络请求

## 特性

- ✅ Vue 3 支持
- ✅ ECharts 图表渲染
- ✅ 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 图表渲染
- ✅ Mermaid 流程图支持
- ✅ KaTeX 数学公式
- ✅ 数据集表格展示
- ✅ 可编辑区域
- ✅ 自定义容器
- ✅ 响应式设计
- ✅ TypeScript 支持
- ✅ 数据源查询功能
- ✅ SQL 语法支持
- ✅ 数据缓存机制

## 许可证

MIT License