@data_wise/hyper-markdown 1.1.2 → 1.1.4

package/README.md

@@ -1,431 +1,471 @@
-# @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 语法支持
-- ✅ 数据缓存机制
-
-## 许可证
-
+# @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 | - | 数据源配置对象（可选） |
+
+### 基础用法
+
+```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>
+```
+
+### 控制编辑器显示状态
+
+```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" }
+  }]
+}
+```
+````
+
+### 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