图表配置文档

    配置方式

    图表配置通过 Markdown 注释的方式添加，格式如下：

    {/* [配置JSON] */}

| 表头1 | 表头2 | 表头3 |
| ----- | ----- | ----- |
| 数据1 | 数据2 | 数据3 |

    配置参数

    筛选维度层次关系

    图表支持三个层次的筛选维度，从高到低依次为：

    1. 主筛选维度 (filterBy → filterLabel)

      • 最高维度的筛选，如：全球、美国、华北、华南
      • 决定查看哪个范围的数据
      • 展现形式：下拉框

    2. 业务分组维度 (groupBy → category)

      • 业务层面的分组，如：访客数据、营收数据、线上业务、线下业务
      • 决定数据的业务分类
      • 展现形式：标签卡

    3. 数据系列维度 (colorLegend → type)

      • 最细粒度的数据系列，如：本周访客、上周访客、本年营收、去年营收
      • 决定图表中的线条/柱子的颜色区分
      • 展现形式：图例

    基础配置

    type ChartConfig = {
  chartType: string; // 图表类型
  x: string; // X 轴字段
  y: string; // Y 轴字段
  title?: string; // 图表标题
  height?: number; // 图表高度，默认400
  dataTime?: string; // 数据时间，显示在图表工具栏中
  groupBy?: 业务分组维度; //（映射为 category）- 如：访客数据、营收数据
  filterBy?: 主筛选维度; //（映射为 filterLabel）- 如：全球、美国
  colorLegend?: 数据系列维度; //（映射为 type）- 如：本周访客、上周访客
  sortBy?: string; // 排序列名；有则按该列排 X 轴类目。未配置时若表格含 `index` 列会自动使用；否则仅当 x 全部为日期/日期区间时按时间排序，其余保持表格顺序
  subgraphBy?: 分组字段，用于生成子图表; //（同段落按该字段拆分）
};

    支持的图表类型

    1. 饼图 (pie)

      实心圆形图表，适用于显示各部分占整体的比例关系。

      {/* {"chartType": "pie", "x": "业务", "y": "2021Q1"} */}

    2. 环形图 (donut)

      中心空心的圆环图表，相比饼图更现代化，可在中心显示总计信息。

      {/* {"chartType": "donut", "x": "业务", "y": "2021Q1"} */}

    3. 条形图 (bar)

      {/* {"chartType": "bar", "x": "业务", "y": "2021Q1"} */}

    4. 折线图 (line)

      {/* {"chartType": "line", "x": "业务", "y": "2021Q1"} */}

    5. 柱状图 (column)

      {/* {"chartType": "column", "x": "业务", "y": "2021Q1"} */}

    6. 面积图 (area)

      {/* {"chartType": "area", "x": "业务", "y": "2021Q1"} */}

    7. 雷达图 (radar)

      {/* {"chartType": "radar", "x": "label", "y": "score"} */}

    8. 散点图 (scatter)

      {/* {"chartType": "scatter", "x": "x", "y": "y"} */}

    9. 表格 (table)

      {/* {"chartType": "table"} */}

    10. 漏斗图 (funnel)

      {/* {"chartType": "funnel", "x": "阶段", "y": "人数"} */}

    11. 定义列表 (descriptions)

    {/* {"chartType": "descriptions"} */}

    1. 卡片列表 (docCards)

      将一行 Markdown 表格映射为一张卡片，默认按桌面 2 列、窄屏 1 列栅格布局。 表头按以下别名解析为语义字段（支持「逻辑名 + 中英文括号单位」的宽松匹配）：

      字段别名必填
      title名称、标题、name、title是
      url地址、链接、URL、网址否
      description简介、描述、说明否
      tags亮点、标签、tags、关键词否

      标签列允许使用半角逗号、分号、竖线、斜杠或全角逗号、分号、顿号分隔多个标签。 可通过 cardColumns 控制每行卡片数（默认 2，传入 1 即全宽列表）， 通过 fieldMap 将语义字段显式映射到自定义表头。

      {/* {"chartType": "docCards", "title": "优秀开发者文档站", "cardColumns": 2} */}

| 名称              | 地址                          | 简介                   | 亮点                       |
| :---------------- | :---------------------------- | :--------------------- | :------------------------- |
| Tailwind CSS Docs | https://tailwindcss.com/docs  | 结构清晰、搜索与导航强 | 交互式示例, 深链, 暗色模式 |
| MDN               | https://developer.mozilla.org | 权威 Web 参考          | 多语言, 可折叠, 示例可编辑 |

      若注释中无法定位主标题列（即 名称/标题/name/title 均未命中且未通过 fieldMap.title 显式指定），整表会降级为普通 Markdown 表格渲染。

    2. 四象限图 (quadrant)

      按行顺序将表格前 4 行渲染为 2×2 网格，常用于优先级矩阵、技术评估等场景。

      • 第 1 列 = 象限标签；
      • 第 2 列 = 逗号分隔的条目列表；
      • 不足 4 行时自动补空占位。
      {/* {"chartType": "quadrant", "title": "优先级矩阵"} */}

| 象限         | 内容                      |
| :----------- | :------------------------ |
| 重要且紧急   | 修复线上bug, 处理客户投诉 |
| 重要不紧急   | 技术改进, 学习新技术      |
| 不重要但紧急 | 回复邮件, 参加会议        |
| 不重要不紧急 | 整理桌面, 清理文档        |

    高级配置示例

    1. 多图表配置

    {/* [{"chartType": "bar", "title": "样本数据", "x": "sens_type", "y": "count"}, {"chartType": "column", "x": "sens_type", "y": "count"}, {"chartType": "pie", "x": "sens_type", "y": "percentage"}, {"chartType": "line", "x": "sens_type", "y": "percentage"}, {"chartType": "area", "x": "sens_type", "y": "percentage"}] */}

    2. 带分组的折线图

    {/* {"chartType": "line", "x": "日期", "y": "uv点击标记", "title": "UV 点击标记",
      "rest": {"colorLegend": "内容", "groupBy": "名称"}} */}

    3. 带标题的图表

    {/* {"chartType": "bar", "x": "业务", "y": "2021Q1", "title": "2021年第一季度业务数据"} */}

    3.1 带数据时间的图表

    通过 dataTime 参数可以在图表工具栏中显示数据时间：

    {/* {"chartType": "bar", "x": "业务", "y": "2021Q1", "title": "2021年第一季度业务数据", "dataTime": "2025-10-30 10:00:00"} */}

    4. 带图例的图表

    图例用于区分不同的数据系列，通过 colorLegend 参数配置：

    {/* {"chartType": "line", "x": "月份", "y": "数值", "title": "月度数据趋势",
      "colorLegend": "系列"} */}

| 月份 | 数值 | 系列  |
| ---- | ---- | ----- |
| 1月  | 100  | A系列 |
| 2月  | 120  | A系列 |
| 3月  | 110  | A系列 |
| 1月  | 80   | B系列 |
| 2月  | 90   | B系列 |
| 3月  | 95   | B系列 |

    5. 带业务分组的图表

    业务分组用于将数据按不同业务类别分组显示，通过 groupBy 参数配置：

    {/* {"chartType": "bar", "x": "产品", "y": "销量", "title": "产品销量对比",
      "groupBy": "业务类型"} */}

| 产品  | 销量 | 业务类型 |
| ----- | ---- | -------- |
| 产品A | 100  | 线上业务 |
| 产品B | 150  | 线上业务 |
| 产品C | 80   | 线上业务 |
| 产品A | 120  | 线下业务 |
| 产品B | 180  | 线下业务 |
| 产品C | 90   | 线下业务 |

    6. 带主筛选的图表

    主筛选提供最高维度的数据筛选，通过 filterBy 参数配置：

    {/* {"chartType": "pie", "x": "类别", "y": "占比", "title": "市场份额分布",
      "groupBy": "业务类型", "filterBy": "地区"} */}

| 类别  | 占比 | 业务类型 | 地区 |
| ----- | ---- | -------- | ---- |
| 类别A | 40   | 线上业务 | 华北 |
| 类别B | 35   | 线上业务 | 华北 |
| 类别C | 25   | 线上业务 | 华北 |
| 类别A | 45   | 线上业务 | 华南 |
| 类别B | 30   | 线上业务 | 华南 |
| 类别C | 25   | 线上业务 | 华南 |

    7. 组合筛选图表

    可以同时使用数据系列、业务分组和主筛选：

    {/* {"chartType": "radar", "x": "指标", "y": "得分", "title": "能力评估",
      "colorLegend": "类型", "groupBy": "维度", "filterBy": "地区"} */}

| 指标 | 得分 | 类型     | 维度 | 地区 |
| ---- | ---- | -------- | ---- | ---- |
| 技术 | 75   | 当前能力 | 年龄 | 全球 |
| 设计 | 60   | 当前能力 | 年龄 | 全球 |
| 产品 | 80   | 当前能力 | 年龄 | 全球 |
| 技术 | 90   | 目标能力 | 年龄 | 全球 |
| 设计 | 85   | 目标能力 | 年龄 | 全球 |
| 产品 | 95   | 目标能力 | 年龄 | 全球 |

    数据格式要求

    1. 表格数据

      • 必须包含表头
      • 数据必须与表头对应
      • 数值类型会自动格式化

    2. 日期数据

      • 日期格式会自动排序
      • 支持标准日期格式

    3. 数值数据

      • 支持数字格式化
      • 支持千分位显示

    特殊功能

    1. 图表切换

      • 支持在图表类型之间切换
      • 切换时会保持数据不变

    2. 图表配置

      • 支持动态修改X轴和Y轴字段
      • 支持自定义图表高度
      • 支持图表标题设置

    3. 响应式布局

      • 支持多列布局
      • 自动适应容器宽度
      • 最小宽度为256px

    完整示例

    ## 业务数据图表

{/* {"chartType": "bar", "x": "业务", "y": "2021Q1", "title": "2021年第一季度业务数据", "dataTime": "2025-10-30 10:00:00",
      "groupBy": "业务类型", "colorLegend": "数据系列", "filterBy": "地区"} */}

| 业务         | 2021Q1  | 2021Q2  | 2021Q3  | 2021Q4  |
| ------------ | ------- | ------- | ------- | ------- |
| 收入         | 135,303 | 138,259 | 142,368 | 144,188 |
| 增值服务     | 72,443  | 72,013  | 75,203  | 71,913  |
| 网络游戏     | 43,600  | 43,000  | 44,900  | 42,800  |
| 社交网络收入 | 28,800  | 29,000  | 30,300  | 29,100  |
| 网络广告     | 21,820  | 22,833  | 22,495  | 21,518  |
| 其他         | 41,040  | 43,413  | 44,670  | 50,757  |
| 金融科技     | 39,028  | 41,892  | 43,317  | 47,958  |
| 云           | 162,012 | 111,521 | 111,353 | 112,799 |

    注意事项

    1. 配置必须放在表格之前
    2. 配置必须是有效的JSON格式
    3. 表格数据必须与配置的字段对应
    4. 日期类型的数据会自动排序
    5. 数值类型的数据会自动格式化
    6. 图表支持全屏显示
    7. 支持数据导出为CSV格式
    8. 支持图表的拖拽和编辑功能