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

## 快速开始

### 基础用法

```vue
<template>
  <div id="app">
    <MarkdownEditor 
      :content="markdownContent" 
      :editable="true"
    />
  </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" }
  }]
}
```
````

### 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
::: warning
这是一个警告信息
:::

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

::: tip
这是一个小贴士
:::

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



## 数据源使用注意事项

### 错误处理

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

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

### 缓存机制

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

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

### 性能优化

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

## 特性

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

## 许可证

MIT License