vue2-client 1.18.64 → 1.18.66

package/docs/HChart/351/205/215/347/275/256/346/226/207/346/241/243.md

@@ -0,0 +1,960 @@
+# HChart 组件配置文档
+
+## 目录
+
+1. [概述](#概述)
+2. [基础配置结构](#基础配置结构)
+3. [图表类型配置](#图表类型配置)
+   - [柱状图 (bar)](#柱状图-bar)
+   - [折线图 (line)](#折线图-line)
+   - [饼图 (pie)](#饼图-pie)
+   - [区间折线图 (range-line)](#区间折线图-range-line)
+4. [筛选模式配置](#筛选模式配置)
+   - [单选过滤 (radioFilter)](#单选过滤-radiofilter)
+   - [侧边列表 (sideList)](#侧边列表-sidelist)
+   - [级联筛选 (sideList.cascade)](#级联筛选-sidelistcascade)
+5. [数据模式配置](#数据模式配置)
+   - [静态数据 (dataset)](#静态数据-dataset)
+   - [逻辑数据 (data)](#逻辑数据-data)
+6. [完整配置示例](#完整配置示例)
+7. [高级配置](#高级配置)
+
+---
+
+## 概述
+
+`HChart` 是一个配置驱动的通用图表组件，支持多种图表类型、筛选模式和数据源。
+
+### 核心特性
+
+- **4种图表类型**：柱状图、折线图、饼图、区间折线图
+- **3种筛选模式**：单选过滤、侧边列表、级联筛选
+- **2种数据模式**：静态数据、逻辑数据
+- **自动颜色渐变**：单色自动生成渐变色数组
+- **深度配置合并**：支持与 ECharts 原生配置深度合并
+
+---
+
+## 基础配置结构
+
+所有配置都遵循以下基础结构：
+
+```json
+{
+  "type": "bar|line|pie|range-line",
+  "xtitle": "图表标题",
+  "xtitleAttrs": {},
+  "style": {},
+  
+  // 数据来源（二选一）
+  "dataset": [...],           // 静态数据
+  "data": "logicName",        // 逻辑数据
+  
+  // 筛选配置（可选）
+  "radioFilter": {...},
+  "sideList": {...},
+  
+  // 图表类型专属配置
+  // ... 见各图表类型章节
+  
+  // ECharts 原生配置（可选）
+  "options": {...},
+  "legend": {...},
+  "grid": {...}
+}
+```
+
+### 字段说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `type` | `string` | ✅ | 图表类型：`bar`、`line`、`pie`、`range-line` |
+| `xtitle` | `string` | ❌ | 图表标题（注意：不是 `title`） |
+| `xtitleAttrs` | `object` | ❌ | 透传给 XTitle 组件的属性 |
+| `style` | `object` | ❌ | 图表容器的样式对象 |
+| `dataset` | `array\|object` | ⚠️ | 静态数据（与 `data` 二选一） |
+| `data` | `string` | ⚠️ | 逻辑名称（与 `dataset` 二选一） |
+| `dataMapping` | `object` | ❌ | 数据字段映射（仅逻辑数据模式） |
+| `radioFilter` | `object` | ❌ | 单选过滤配置 |
+| `sideList` | `object` | ❌ | 侧边列表/级联筛选配置 |
+| `options` | `object` | ❌ | ECharts 原生配置（会与预设合并） |
+
+---
+
+## 图表类型配置
+
+### 柱状图 (bar)
+
+#### 专用配置字段
+
+| 字段 | 类型 | 默认值 | 说明 | 
+|------|------|--------|------|
+| `barColor` | `string` | `#3362DA` | 柱子颜色 |
+| `barHighlightColor` | `string` | `#4C7CFF` | 高亮颜色（点击/悬停） |
+| `valueSuffix` | `string` | `''` | 数值后缀（如 `%`、`人次`） |
+| `yMax` | `number` | `100` | Y轴最大值 |
+
+#### 基础配置示例
+
+```json
+{
+  "type": "bar",
+  "xtitle": "满意度统计",
+  "barColor": "#3E7BFA", 
+  "barHighlightColor": "#6898FF",
+  "valueSuffix": "%",
+  "yMax": 100,
+  "dataset": [
+    { "label": "一月", "value": 90 },
+    { "label": "二月", "value": 95 },
+    { "label": "三月", "value": 88 }
+  ]
+}
+```
+
+#### 数据格式要求
+
+```json
+[
+  { "label": "标签", "value": 数值 }
+]
+```
+
+---
+
+### 折线图 (line)
+
+#### 专用配置字段
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `highlightColor` | `string` | `#1F5BFF` | 高亮节点/文本颜色 |
+| `lineColor` | `string` | `#1F66FF` | 折线颜色 |
+| `areaStartColor` | `string` | `rgba(31, 91, 255, 0.25)` | 面积渐变起始色 |
+| `areaEndColor` | `string` | `rgba(31, 91, 255, 0.02)` | 面积渐变结束色 |
+| `valueSuffix` | `string` | `''` | 数值后缀 |
+| `smooth` | `boolean` | `false` | 是否平滑曲线 |
+| `symbolSize` | `number` | `12` | 基准点大小 |
+| `activeSymbolSize` | `number` | `symbolSize + 4` | 选中点大小 |
+| `inactivePointFill` | `string` | `#fff` | 非激活点填充色 |
+| `pointBorderWidth` | `number` | `4` | 点边框宽度 |
+
+#### 基础配置示例
+
+```json
+{
+  "type": "line",
+  "xtitle": "门急诊量趋势",
+  "smooth": true,
+  "valueSuffix": "人次",
+  "highlightColor": "#FF6A00",
+  "lineColor": "#FF9240",
+  "areaStartColor": "rgba(255, 146, 64, 0.35)",
+  "areaEndColor": "rgba(255, 146, 64, 0.02)",
+  "dataset": [
+    { "label": "周一", "value": 1200 },
+    { "label": "周二", "value": 1350 },
+    { "label": "周三", "value": 1100 }
+  ]
+}
+```
+
+#### 数据格式要求
+
+```json
+[
+  { "label": "标签", "value": 数值 }
+]
+```
+
+---
+
+### 饼图 (pie)
+
+#### 专用配置字段
+
+饼图没有专用配置字段，主要使用通用配置和 `options`。
+
+#### 基础配置示例
+
+```json
+{
+  "type": "pie",
+  "xtitle": "患者来源占比",
+  "dataset": [
+    { "label": "门诊", "value": 60 },
+    { "label": "住院", "value": 30 },
+    { "label": "急诊", "value": 10 }
+  ],
+  "options": {
+    "legend": {
+      "orient": "vertical",
+      "right": 10,
+      "top": "center"
+    }
+  }
+}
+```
+
+#### 数据格式要求
+
+```json
+[
+  { "label": "标签", "value": 数值 }
+]
+```
+
+---
+
+### 区间折线图 (range-line)
+
+#### 专用配置字段
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `highField` | `string` | `high` | 高值字段名 |
+| `lowField` | `string` | `low` | 低值字段名 |
+| `highName` | `string` | `流入` | 高值折线名称（图例/tooltip） |
+| `lowName` | `string` | `流出` | 低值折线名称（图例/tooltip） |
+| `highColor` | `string` | `#1F66FF` | 高值折线颜色 |
+| `lowColor` | `string` | `#A8C4FF` | 低值折线颜色 |
+| `rangeLineColor` | `string` | `#1F66FF` | 差值连线颜色 |
+| `rangeLineType` | `string` | `solid` | 差值连线类型：`solid` / `dashed` |
+| `valueSuffix` | `string` | `''` | 数值后缀 |
+| `showRangeLines` | `boolean` | `true` | 是否显示差值连线 |
+| `smooth` | `boolean` | `false` | 是否平滑曲线 |
+| `symbolSize` | `number` | `10` | 点大小 |
+| `pointBorderWidth` | `number` | `3` | 点边框宽度 |
+
+#### 基础配置示例
+
+```json
+{
+  "type": "range-line",
+  "xtitle": "现金出入",
+  "highField": "inflow",
+  "lowField": "outflow",
+  "highName": "经营现金流入",
+  "lowName": "经营现金流出",
+  "highColor": "#3362DA",
+  "lowColor": "#A8C4FF",
+  "rangeLineColor": "#3362DA",
+  "rangeLineType": "solid",
+  "valueSuffix": "万",
+  "showRangeLines": true,
+  "smooth": false,
+  "symbolSize": 10,
+  "dataset": [
+    { "label": "01月", "inflow": 900, "outflow": 700 },
+    { "label": "02月", "inflow": 1500, "outflow": 920 }
+  ]
+}
+```
+
+#### 数据格式要求
+
+```json
+[
+  { 
+    "label": "标签", 
+    "highField值": 数值,    // 如 "inflow": 900
+    "lowField值": 数值       // 如 "outflow": 700
+  }
+]
+```
+
+---
+
+## 筛选模式配置
+
+### 单选过滤 (radioFilter)
+
+在图表顶部显示一排单选按钮（pill 样式），用于切换维度。
+
+#### 配置结构
+
+```json
+{
+  "radioFilter": {
+    "label": "时间维度",
+    "field": "dateType",
+    "defaultValue": "month",
+    "options": [
+      { "label": "年", "value": "year" },
+      { "label": "季", "value": "quarter" },
+      { "label": "月", "value": "month" }
+    ]
+  }
+}
+```
+
+#### 字段说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `label` | `string` | ❌ | 筛选器标签 |
+| `field` | `string` | ❌ | 查询参数 key（逻辑数据模式）或 `prop` |
+| `defaultValue` | `string` | ❌ | 默认选中的 value |
+| `options` | `array` | ✅ | 选项数组，每项包含 `label` 和 `value` |
+
+#### 与静态数据联动
+
+当使用静态 `dataset` 时，`radioFilter` 的当前选中值会作为 key 去 `dataset` 对象中取对应的数组：
+
+```json
+{
+  "type": "bar",
+  "radioFilter": {
+    "field": "dateType",
+    "defaultValue": "month",
+    "options": [
+      { "label": "月", "value": "month" },
+      { "label": "年", "value": "year" }
+    ]
+  },
+  "dataset": {
+    "month": [
+      { "label": "01月", "value": 100 },
+      { "label": "02月", "value": 120 }
+    ],
+    "year": [
+      { "label": "2022", "value": 1200 },
+      { "label": "2023", "value": 1500 }
+    ]
+  }
+}
+```
+
+---
+
+### 侧边列表 (sideList)
+
+在图表左侧显示一列按钮，用于切换分类。
+
+#### 配置结构（非级联模式）
+
+```json
+{
+  "sideList": {
+    "label": "科室",
+    "title": "科室",           // 与 label 等价
+    "field": "deptCode",
+    "prop": "deptCode",        // 与 field 等价
+    "defaultValue": "dept01",
+    "options": [
+      { "label": "心内科", "value": "dept01", "badge": "热门" },
+      { "label": "呼吸科", "value": "dept02" }
+    ]
+  }
+}
+```
+
+#### 字段说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `label` | `title` | `string` | ❌ | 列表标题 |
+| `field` | `prop` | `string` | ❌ | 查询参数 key（逻辑数据模式），默认 `category` |
+| `defaultValue` | `string` | ❌ | 默认选中的 value |
+| `options` | `array` | ✅ | 选项数组，每项包含 `label`、`value`、`badge`（可选） |
+| `mode` | `string` | ❌ | 不设置或非 `cascade` 时为侧边列表模式 |
+
+#### 与静态数据联动
+
+```json
+{
+  "type": "line",
+  "sideList": {
+    "label": "科室",
+    "defaultValue": "dept01",
+    "options": [
+      { "label": "心内科", "value": "dept01" },
+      { "label": "呼吸科", "value": "dept02" }
+    ]
+  },
+  "dataset": {
+    "dept01": [
+      { "label": "周一", "value": 100 },
+      { "label": "周二", "value": 120 }
+    ],
+    "dept02": [
+      { "label": "周一", "value": 80 },
+      { "label": "周二", "value": 90 }
+    ]
+  }
+}
+```
+
+---
+
+### 级联筛选 (sideList.cascade)
+
+在图表顶部显示多列级联选择（如：院区 → 楼栋 → 科室）。
+
+#### 配置结构
+
+```json
+{
+  "sideList": {
+    "mode": "cascade",
+    "label": "筛选条件",
+    "levels": [
+      {
+        "label": "院区",
+        "title": "院区",           // 与 label 等价
+        "field": "areaCode",
+        "defaultValue": "A",
+        "subtitle": "可选",
+        "options": [
+          { "label": "一院区", "value": "A" },
+          { "label": "二院区", "value": "B" }
+        ]
+      },
+      {
+        "label": "楼栋",
+        "field": "buildingCode",
+        "options": {
+          "A": [
+            { "label": "1号楼", "value": "A1" },
+            { "label": "2号楼", "value": "A2" }
+          ],
+          "B": [
+            { "label": "3号楼", "value": "B3" }
+          ],
+          "default": []
+        }
+      }
+    ]
+  }
+}
+```
+
+#### 字段说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `mode` | `string` | ✅ | 必须为 `"cascade"` |
+| `label` / `title` | `string` | ❌ | 级联面板标题 |
+| `levels` | `array` | ✅ | 级联层级数组 |
+
+**levels 每项字段：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `label` / `title` | `string` | ❌ | 列标题 |
+| `subtitle` | `string` | ❌ | 列副标题 |
+| `field` / `prop` | `string` | ❌ | 查询参数 key，默认 `cascade-field-{index}` |
+| `defaultValue` | `string` | ❌ | 默认选中的 value |
+| `options` | `array\|object` | ✅ | 选项数组或对象（见下方说明） |
+
+**options 的两种写法：**
+
+1. **直接数组**（第一级常用）：
+```json
+"options": [
+  { "label": "一院区", "value": "A" }
+]
+```
+
+2. **对象映射**（子级根据父级值动态切换）：
+```json
+"options": {
+  "A": [
+    { "label": "1号楼", "value": "A1" }
+  ],
+  "B": [
+    { "label": "3号楼", "value": "B3" }
+  ],
+  "default": []  // 兜底数组
+}
+```
+
+#### 与静态数据联动
+
+级联筛选会按选中的层级值（如 `["A", "A1"]`）去 `dataset` 对象中嵌套取值：
+
+```json
+{
+  "type": "bar",
+  "sideList": {
+    "mode": "cascade",
+    "levels": [
+      {
+        "label": "院区",
+        "field": "areaCode",
+        "defaultValue": "A",
+        "options": [
+          { "label": "一院区", "value": "A" }
+        ]
+      },
+      {
+        "label": "楼栋",
+        "field": "buildingCode",
+        "options": {
+          "A": [
+            { "label": "1号楼", "value": "A1" }
+          ]
+        }
+      }
+    ]
+  },
+  "dataset": {
+    "A": {
+      "A1": [
+        { "label": "一月", "value": 100 }
+      ]
+    }
+  }
+}
+```
+
+#### 与逻辑数据联动（SQL 示例）
+
+后端 `runLogic` 会收到级联各层的 `field` 作为查询参数（如 `provinceCode`、`cityCode`、`districtCode`、`streetCode`），SQL 可按需拼接：
+
+```sql
+-- 例：按省/市/区/街道筛选患者常住地，并按周/月/年汇总
+WITH base AS (
+  SELECT
+    p.province_code,
+    p.city_code,
+    p.district_code,
+    p.street_code,
+    p.resident_date
+  FROM patient_residence p
+  WHERE (:provinceCode IS NULL OR p.province_code = :provinceCode)
+    AND (:cityCode IS NULL OR p.city_code = :cityCode)
+    AND (:districtCode IS NULL OR p.district_code = :districtCode)
+    AND (:streetCode IS NULL OR p.street_code = :streetCode)
+)
+SELECT
+  CASE
+    WHEN :periodType = 'week' THEN TO_CHAR(resident_date, 'IYYY-IW')
+    WHEN :periodType = 'month' THEN TO_CHAR(resident_date, 'YYYY-MM')
+    ELSE TO_CHAR(resident_date, 'YYYY')
+  END AS label,
+  COUNT(*) AS value
+FROM base
+GROUP BY
+  CASE
+    WHEN :periodType = 'week' THEN TO_CHAR(resident_date, 'IYYY-IW')
+    WHEN :periodType = 'month' THEN TO_CHAR(resident_date, 'YYYY-MM')
+    ELSE TO_CHAR(resident_date, 'YYYY')
+  END
+ORDER BY label;
+```
+
+`field` 名即为参数名；未选中时参数为空，条件自动放行。`periodType` 可由单选过滤（周/月/年）传入。
+
+---
+
+## 数据模式配置
+
+### 静态数据 (dataset)
+
+直接在配置中提供数据，支持简单数组或嵌套对象。
+
+#### 简单数组
+
+```json
+{
+  "type": "bar",
+  "dataset": [
+    { "label": "一月", "value": 120 },
+    { "label": "二月", "value": 80 }
+  ]
+}
+```
+
+#### 嵌套对象（与筛选联动）
+
+```json
+{
+  "type": "line",
+  "radioFilter": {
+    "defaultValue": "month",
+    "options": [
+      { "label": "月", "value": "month" },
+      { "label": "年", "value": "year" }
+    ]
+  },
+  "dataset": {
+    "month": [
+      { "label": "01月", "value": 100 }
+    ],
+    "year": [
+      { "label": "2022", "value": 1200 }
+    ]
+  }
+}
+```
+
+#### 数据提取规则
+
+组件会按以下顺序尝试提取数组：
+
+1. 如果 `dataset` 是数组，直接使用
+2. 如果是对象：
+   - 有筛选时，用当前选中值作为 key 取子数组
+   - 无筛选时，尝试 `dataset.data`、`dataset.result`、`dataset.list` 等字段
+   - 如果仍找不到，取对象中第一个数组类型的值
+
+---
+
+### 逻辑数据 (data)
+
+通过后端逻辑获取数据，使用 `runLogic` 调用。
+
+#### 配置结构
+
+```json
+{
+  "type": "bar",
+  "data": "logicName_getBarData",
+  "dataMapping": {
+    "labelField": "xName",
+    "valueField": "totalCount"
+  }
+}
+```
+
+#### 字段说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `data` | `string` | ✅ | 逻辑名称 |
+| `dataMapping` | `object` | ❌ | 字段映射（见下方） |
+
+**dataMapping 字段：**
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `labelField` | `string` | `label` | 标签字段名 |
+| `valueField` | `string` | `value` | 数值字段名 |
+
+#### 查询参数构建
+
+逻辑数据模式会自动合并以下参数：
+
+1. `fixedQueryForm`（组件 props）
+2. `listQueryParams`（侧边列表/级联筛选的选中值）
+3. `filterQueryParams`（单选过滤的选中值）
+
+最终调用：`runLogic(config.data, queryPayload, serviceName)`
+
+#### 数据转换
+
+后端返回的数据会被 `transformData` 转换：
+
+1. 尝试从 `data`、`result`、`list`、`items`、`records` 字段提取数组
+2. 如果仍找不到，取对象中第一个数组类型的值
+3. 使用 `dataMapping` 映射字段，或自动识别 `label/name/text` + `value/count`
+
+---
+
+## 完整配置示例
+
+### 示例 1：区间折线图 + 单选过滤 + 静态数据
+
+```json
+{
+  "type": "range-line",
+  "xtitle": "现金出入",
+  "highColor": "#3362DA",
+  "lowColor": "#A8C4FF",
+  "rangeLineColor": "#3362DA",
+  "rangeLineType": "solid",
+  "highName": "经营现金流入",
+  "lowName": "经营现金流出",
+  "highField": "inflow",
+  "lowField": "outflow",
+  "valueSuffix": "万",
+  "showRangeLines": true,
+  "smooth": false,
+  "symbolSize": 10,
+  "radioFilter": {
+    "field": "dateType",
+    "defaultValue": "month",
+    "options": [
+      { "label": "年", "value": "year" },
+      { "label": "季", "value": "quarter" },
+      { "label": "月", "value": "month" }
+    ]
+  },
+  "dataset": {
+    "month": [
+      { "label": "01月", "inflow": 900, "outflow": 700 },
+      { "label": "02月", "inflow": 1500, "outflow": 920 }
+    ],
+    "quarter": [
+      { "label": "Q1", "inflow": 3450, "outflow": 2370 }
+    ],
+    "year": [
+      { "label": "2022", "inflow": 14200, "outflow": 10500 }
+    ]
+  }
+}
+```
+
+### 示例 2：柱状图 + 侧边列表 + 逻辑数据
+
+```json
+{
+  "type": "bar",
+  "xtitle": "科室就诊量",
+  "barColor": "#3E7BFA",
+  "valueSuffix": "人次",
+  "yMax": 200,
+  "sideList": {
+    "label": "科室",
+    "field": "deptCode",
+    "defaultValue": "dept01",
+    "options": [
+      { "label": "心内科", "value": "dept01" },
+      { "label": "呼吸科", "value": "dept02" }
+    ]
+  },
+  "data": "logic_getDeptVisits",
+  "dataMapping": {
+    "labelField": "date",
+    "valueField": "visitCount"
+  }
+}
+```
+
+### 示例 3：折线图 + 级联筛选 + 静态数据
+
+```json
+{
+  "type": "line",
+  "xtitle": "床位使用率趋势",
+  "smooth": true,
+  "valueSuffix": "%",
+  "highlightColor": "#1F5BFF",
+  "sideList": {
+    "mode": "cascade",
+    "label": "筛选条件",
+    "levels": [
+      {
+        "label": "院区",
+        "field": "areaCode",
+        "defaultValue": "A",
+        "options": [
+          { "label": "一院区", "value": "A" },
+          { "label": "二院区", "value": "B" }
+        ]
+      },
+      {
+        "label": "楼栋",
+        "field": "buildingCode",
+        "options": {
+          "A": [
+            { "label": "1号楼", "value": "A1" }
+          ],
+          "B": [
+            { "label": "3号楼", "value": "B3" }
+          ]
+        }
+      }
+    ]
+  },
+  "dataset": {
+    "A": {
+      "A1": [
+        { "label": "周一", "value": 85 },
+        { "label": "周二", "value": 90 }
+      ]
+    },
+    "B": {
+      "B3": [
+        { "label": "周一", "value": 75 },
+        { "label": "周二", "value": 80 }
+      ]
+    }
+  }
+}
+```
+
+### 示例 4：饼图 + 单选过滤 + 逻辑数据
+
+```json
+{
+  "type": "pie",
+  "xtitle": "患者来源占比",
+  "radioFilter": {
+    "field": "timeType",
+    "defaultValue": "month",
+    "options": [
+      { "label": "本月", "value": "month" },
+      { "label": "本年", "value": "year" }
+    ]
+  },
+  "data": "logic_getPatientSource",
+  "dataMapping": {
+    "labelField": "sourceName",
+    "valueField": "count"
+  },
+  "options": {
+    "legend": {
+      "orient": "vertical",
+      "right": 10,
+      "top": "center"
+    }
+  }
+}
+```
+
+### 示例 5：折线图 + 级联筛选 + 时间粒度筛选 + 静态数据（患者常住地数据）
+
+```json
+```
+
+**说明：**
+- 此配置包含4级级联筛选：省份 → 城市 → 区县 → 街道
+- 时间粒度筛选支持：周、月、年三种维度
+- 数据覆盖了江苏、浙江两个省份，每个省份2个城市，每个城市3个区县，每个区县4个街道，共48个街道的数据
+- 周数据：显示周一到周日的患者数量
+- 月数据：显示1-6月的患者数量
+- 年数据：显示2020-2024年的患者数量
+- 折线图配置了面积填充效果，符合图片中的视觉效果
+
+---
+
+## 高级配置
+
+### 颜色渐变
+
+当 `options.color` 为单个颜色字符串或长度为 1 的数组时，组件会自动生成渐变色数组：
+
+```json
+{
+  "type": "bar",
+  "options": {
+    "color": "#3362DA"  // 自动生成渐变数组
+  }
+}
+```
+
+如果已提供多色数组，则直接使用：
+
+```json
+{
+  "type": "bar",
+  "options": {
+    "color": ["#3362DA", "#4C7CFF", "#6898FF"]
+  }
+}
+```
+
+### ECharts 原生配置合并
+
+`options` 中的配置会与预设配置深度合并：
+
+```json
+{
+  "type": "line",
+  "options": {
+    "color": "#FF6A00",
+    "legend": {
+      "show": true,
+      "top": 10
+    },
+    "grid": {
+      "top": 60,
+      "left": 80
+    },
+    "xAxis": {
+      "axisLabel": {
+        "rotate": 45
+      }
+    },
+    "series": [
+      {
+        "name": "自定义系列",
+        "type": "line"
+      }
+    ]
+  }
+}
+```
+
+**合并规则：**
+
+- `xAxis.data`：如果用户配置为空数组或未定义，使用预设的 data
+- `series`：会与预设 series 按索引深度合并
+- 其他配置：直接覆盖预设
+
+### 样式配置
+
+```json
+{
+  "xtitle": "图表标题",
+  "xtitleAttrs": {
+    "size": "small"
+  },
+  "style": {
+    "height": "400px",
+    "width": "100%"
+  }
+}
+```
+
+---
+
+## 注意事项
+
+1. **标题字段**：使用 `xtitle`，不是 `title`
+2. **数据格式**：所有图表类型的数据都必须是 `{ label, value }` 格式（`range-line` 还需要 `highField` 和 `lowField` 对应的字段）
+3. **筛选联动**：静态 `dataset` 的 key 必须与筛选器的 `value` 匹配
+4. **级联选项**：子级的 `options` 如果是对象，key 必须与父级选中值匹配
+5. **逻辑数据**：确保后端返回的数据能被 `transformData` 正确提取和转换
+
+---
+
+## 使用方式
+
+### 方式 1：直接传入 config
+
+```vue
+<template>
+  <h-chart :config="chartConfig" />
+</template>
+
+<script setup>
+const chartConfig = {
+  type: 'bar',
+  xtitle: '示例图表',
+  dataset: [
+    { label: '一月', value: 100 }
+  ]
+}
+</script>
+```
+
+### 方式 2：通过 queryParamsName 从后端获取
+
+```vue
+<template>
+  <h-chart
+    query-params-name="his.bar.chart.config.001"
+    service-name="af-his"
+    :fixed-query-form="{ condition: '1=1', orgId: currentOrgId }"
+  />
+</template>
+```
+
+后端返回的配置结构即为本文档描述的 JSON 格式。
+
+---
+
+## 总结
+
+`HChart` 组件通过灵活的配置组合，可以满足大部分图表展示需求：
+
+- **图表类型**：4 种预设类型，支持自定义扩展
+- **筛选模式**：3 种筛选方式，可组合使用
+- **数据模式**：静态数据或逻辑数据，自动适配
+- **配置合并**：支持与 ECharts 原生配置深度合并
+
+如有疑问，请参考组件源码或联系开发团队。
+