@data_wise/hyper-markdown 1.4.1 → 1.5.0

package/README.md

@@ -384,7 +384,130 @@ graph TD
 ```
 ````
 
-### 4. SQL 数据源查询
+### 4. D3.js 可视化
+
+支持使用 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('标题');
+```
+````
+
+### 5. SQL 数据源查询
 
 支持从数据源查询数据，需要先注入 `datasource` 属性：
 
@@ -446,7 +569,69 @@ SELECT 地区, 用户数, 活跃度 FROM user_data WHERE 用户数 > 1000 AND
 ```
 ````
 
-### 5. 栅格布局
+### 5. 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 或 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: "用户数" }
+  }]
+}
+```
+````
+
+### 6. 栅格布局
 
 使用 `cell` 容器创建响应式布局：
 
@@ -471,7 +656,7 @@ console.log('支持代码块');
 :::
 ````
 
-### 6. 自定义容器
+### 7. 自定义容器
 
 支持多种自定义容器：
 
@@ -523,6 +708,7 @@ console.log('支持代码块');
 
 - ✅ Vue 3 支持
 - ✅ ECharts 图表渲染
+- ✅ D3.js 可视化支持（新功能）
 - ✅ Mermaid 流程图支持
 - ✅ KaTeX 数学公式
 - ✅ 数据集表格展示
@@ -534,7 +720,7 @@ console.log('支持代码块');
 - ✅ SQL 语法支持
 - ✅ 数据缓存机制
 - ✅ **Word 文档导出**
-- ✅ **Dashboard 看板模式**（新功能）
+- ✅ **Dashboard 看板模式**
 
 ## Word 导出功能
 
@@ -611,6 +797,7 @@ export default {
 
 - ✅ Vue 3 支持
 - ✅ ECharts 图表渲染
+- ✅ D3.js 可视化支持
 - ✅ Mermaid 流程图支持
 - ✅ KaTeX 数学公式
 - ✅ 数据集表格展示
@@ -621,6 +808,8 @@ export default {
 - ✅ 数据源查询功能
 - ✅ SQL 语法支持
 - ✅ 数据缓存机制
+- ✅ Word 文档导出
+- ✅ Dashboard 看板模式
 
 ## 许可证