@xq-labs/data-ui-v2 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @xq-labs/data-ui-v2
 
-一套面向 Vue 2 项目的业务图表组件库，当前聚焦 `BaseChart`、`BarLineChart`、`PieChart` 三个公开组件，配套 `playground` 示例库、Rollup 发布构建和本地发版脚本。
+一套面向 Vue 2 项目的业务图表组件库，当前聚焦 `BaseChart`、`BarLineChart`、`PieChart`、`RadarChart` 四个公开组件，配套 `playground` 示例库、Rollup 发布构建和本地发版脚本。
 
 ## 适用环境
 
@@ -17,13 +17,18 @@ npm install @xq-labs/data-ui-v2
 
 组件库将 `vue` 与 `echarts` 作为外部依赖。
 
-只使用 2D 图表时不需要安装 echarts-gl；使用 3D 饼图时需要额外安装 echarts-gl。
-依赖包名为 `echarts-gl`，例如：
+宿主项目只需确保已安装 `vue` 与 `echarts`。
 
-```bash
-npm install echarts echarts-gl
+如果你要使用 `PieChart` 的 3D 能力，
+请先安装 `echarts-gl`，并在**使用 3D PieChart 的页面顶部**引入桥接入口：
+
+```js
+import '@xq-labs/data-ui-v2/pie-chart/3d-runtime'
 ```
 
+如果你的项目有多个页面都会使用 3D `PieChart`，
+也可以选择在应用入口统一引入这个桥接入口。
+
 ## 整包注册
 
 ```js
@@ -38,16 +43,18 @@ Vue.use(DataUI)
 - `BaseChart`
 - `BarLineChart`
 - `PieChart`
+- `RadarChart`
 
 ## 按需引入
 
 ```js
 import Vue from 'vue'
-import { BaseChart, BarLineChart, PieChart } from '@xq-labs/data-ui-v2'
+import { BaseChart, BarLineChart, PieChart, RadarChart } from '@xq-labs/data-ui-v2'
 
 Vue.component(BaseChart.name, BaseChart)
 Vue.component(BarLineChart.name, BarLineChart)
 Vue.component(PieChart.name, PieChart)
+Vue.component(RadarChart.name, RadarChart)
 ```
 
 如果你的构建链路需要直接引用发布子路径，也可以按 `lib` / `es` 产物接入：
@@ -56,6 +63,7 @@ Vue.component(PieChart.name, PieChart)
 import BaseChart from '@xq-labs/data-ui-v2/es/base-chart'
 import BarLineChart from '@xq-labs/data-ui-v2/es/bar-line-chart'
 import PieChart from '@xq-labs/data-ui-v2/es/pie-chart'
+import RadarChart from '@xq-labs/data-ui-v2/es/radar-chart'
 ```
 
 ## 样式说明
@@ -67,16 +75,27 @@ import PieChart from '@xq-labs/data-ui-v2/es/pie-chart'
 import '@xq-labs/data-ui-v2/theme-chalk/index.css'
 ```
 
-## 3D 饼图依赖说明
+## 3D 饼图运行时说明
 
-只使用 2D 图表时不需要安装 echarts-gl。
-使用 3D 饼图时需要额外安装 echarts-gl，依赖包名为 `echarts-gl`，例如：
+`PieChart` 使用 `dimension="3d"` 时，
+组件库主入口**不会**代替业务项目自动加载 `echarts-gl`。
 
-```bash
-npm install echarts echarts-gl
+推荐接入方式：
+
+```js
+import '@xq-labs/data-ui-v2/pie-chart/3d-runtime'
 ```
 
-当 `PieChart` 使用 `dimension="3d"` 时，组件会在运行时按需加载 `echarts-gl`。
+建议直接写在**使用 3D PieChart 的页面顶部**。
+该入口只负责把 `SurfaceChart` 与 `Grid3DComponent` 注册到 `echarts/core`，
+不会注册组件，也不会影响 2D 场景。
+
+包内同时保留 `pie-chart/3d-runtime.js` 物理入口，
+用于兼容不识别 `package.json#exports` 的老 webpack / Vue CLI 链路。
+
+如果 3D runtime 未就绪，
+组件会进入可读空态，并通过 `runtime-error` 事件抛出异常，
+同时提示你先引入 `@xq-labs/data-ui-v2/pie-chart/3d-runtime`。
 
 ## 组件能力概览
 
@@ -97,12 +116,19 @@ npm install echarts echarts-gl
 - 支持 3D 饼图、环图、按值映射高度等能力
 - 支持标签、引导线和 `customOption` 扩展
 
+### RadarChart
+
+- 支持 2D 雷达图
+- 支持字段映射式指标配置，避免 ECharts 原生 value 数组顺序错位
+- 支持面积雷达图、折线雷达图、系列色板和 `customOption` 扩展
+
 ## 示例与文档
 
 - API 总览：`docs/api/overview.md`
 - 可运行示例：`playground`
 - 示例说明：`docs/examples/pie-chart.md`
 - 示例说明：`docs/examples/bar-line-chart.md`
+- 示例说明：`docs/examples/radar-chart.md`
 - npm 包内离线文档：`node_modules/@xq-labs/data-ui-v2/docs/api/overview.md`
 - npm 包内示例说明：`node_modules/@xq-labs/data-ui-v2/docs/examples/*.md`
 

package/docs/api/overview.md

@@ -19,13 +19,16 @@ npm install @xq-labs/data-ui-v2
 
 宿主项目需要自行安装 `vue` 与 `echarts`。
 
-如果你只使用 2D 图表，不需要安装 `echarts-gl`。  
-如果你要启用 `PieChart` 的 3D 能力，需要额外安装：
+如果你启用 `PieChart` 的 `dimension="3d"`，  
+请先安装 `echarts-gl`，并在**业务页面**中引入 3D 桥接入口：
 
-```bash
-npm install echarts echarts-gl
+```js
+import '@xq-labs/data-ui-v2/pie-chart/3d-runtime'
 ```
 
+如果项目多个页面都会使用 3D `PieChart`，  
+也可以在应用入口统一引入这个桥接入口。
+
 ---
 
 ## 2. 注册方式
@@ -47,11 +50,12 @@ Vue.use(DataUI)
 
 ```js
 import Vue from 'vue'
-import { BaseChart, BarLineChart, PieChart } from '@xq-labs/data-ui-v2'
+import { BaseChart, BarLineChart, PieChart, RadarChart } from '@xq-labs/data-ui-v2'
 
 Vue.component(BaseChart.name, BaseChart)
 Vue.component(BarLineChart.name, BarLineChart)
 Vue.component(PieChart.name, PieChart)
+Vue.component(RadarChart.name, RadarChart)
 ```
 
 ### 2.3 子路径引入
@@ -62,6 +66,7 @@ Vue.component(PieChart.name, PieChart)
 import BaseChart from '@xq-labs/data-ui-v2/es/base-chart'
 import BarLineChart from '@xq-labs/data-ui-v2/es/bar-line-chart'
 import PieChart from '@xq-labs/data-ui-v2/es/pie-chart'
+import RadarChart from '@xq-labs/data-ui-v2/es/radar-chart'
 ```
 
 ---
@@ -85,8 +90,9 @@ import '@xq-labs/data-ui-v2/theme-chalk/index.css'
 | `BaseChart` | 通用 ECharts 渲染壳 | 已有完整 option，只需要统一渲染、空态、loading |
 | `BarLineChart` | 标准柱线图组件 | 基础柱图、圆柱、方柱、堆叠、双轴、柱线组合 |
 | `PieChart` | 标准饼图组件 | 2D 饼图 / 环图 / 玫瑰图，3D 饼图 / 环图 / 标签引导线 |
+| `RadarChart` | 标准雷达图组件 | 能力画像、指标评分、多对象指标对比 |
 
-> 当前公开组件只有 `BaseChart`、`BarLineChart`、`PieChart`。
+> 当前公开组件只有 `BaseChart`、`BarLineChart`、`PieChart`、`RadarChart`。
 
 ---
 
@@ -101,9 +107,10 @@ import '@xq-labs/data-ui-v2/theme-chalk/index.css'
 
 补充说明：
 
-- 2D 图表使用方不需要安装 `echarts-gl`。
-- 3D 饼图在运行时会按需加载 `echarts-gl`。
-- 如果启用 3D 但项目未安装 `echarts-gl`，`PieChart` 会进入可读空态，并抛出 `runtime-error` 事件。
+- 2D 图表不会触发 3D runtime 接入要求。
+- 3D 饼图需要业务项目安装 `echarts-gl`，并引入 3D 桥接入口。
+- 当前推荐在使用 3D `PieChart` 的业务页面中引入。
+- 如果 3D runtime 未就绪，`PieChart` 会进入可读空态，并抛出 `runtime-error` 事件。
 
 ---
 
@@ -119,9 +126,9 @@ import '@xq-labs/data-ui-v2/theme-chalk/index.css'
 | Prop | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
 | `option` | `Object` | `{}` | 已构建完成的 ECharts option |
-| `loading` | `Boolean` | `false` | 是否显示 loading |
+| `loading` | `Boolean` | `false` | 是否显示统一遮罩式 loading（非 ECharts 原生 loading） |
 | `empty` | `Boolean` | `false` | 是否显示空态 |
-| `emptyText` | `String` | `'暂无数据'` | 空态文案 |
+| `stateConfig` | `Object` | `{}` | 统一状态配置，收拢空态文案、空态图和 loading 文案 |
 | `height` | `String \| Number` | `320` | 容器高度，数字按 px 处理 |
 
 ### 6.3 Events
@@ -133,7 +140,7 @@ import '@xq-labs/data-ui-v2/theme-chalk/index.css'
 
 ### 6.4 常见场景
 
-1. 你已经有现成的 ECharts option，只需要统一 loading、空态和实例生命周期。
+1. 你已经有现成的 ECharts option，只需要统一遮罩式 loading、空态和实例生命周期。
 2. 你在业务项目里做一个内部定制图表，但仍希望复用统一底层壳。
 
 示例：
@@ -143,11 +150,42 @@ import '@xq-labs/data-ui-v2/theme-chalk/index.css'
   :option="option"
   :loading="loading"
   :empty="!option.series || option.series.length === 0"
-  empty-text="暂无可展示数据"
+  :state-config="{
+    empty: {
+      text: '暂无可展示数据',
+      image: 'https://example.com/chart-empty.png'
+    },
+    loading: {
+      text: '图表加载中...'
+    }
+  }"
   :height="360"
 />
 ```
 
+### 6.5 `stateConfig` 结构
+
+推荐结构：
+
+```js
+const stateConfig = {
+  empty: {
+    text: '暂无数据',
+    image: 'https://example.com/empty.png'
+  },
+  loading: {
+    text: '加载中...'
+  }
+}
+```
+
+默认与优先级：
+
+1. `BaseChart` 优先读取 `stateConfig.empty.text`。
+2. 未传空态文案时回退到默认值 `暂无数据`。
+3. 空态图未传时，`BaseEmpty` 会展示组件库内置默认图。
+4. `loading` 布尔值仍只负责“是否显示加载态”，不放进 `stateConfig`。
+
 ---
 
 ## 7. `BarLineChart` API
@@ -168,8 +206,10 @@ import '@xq-labs/data-ui-v2/theme-chalk/index.css'
 | `preset` | `String` | `'compare'` | 预设：`compare` / `trend` / `rank` |
 | `barWidth` | `Number` | `18` | 柱体宽度 |
 | `barGap` | `Number \| String` | `8` | 柱间距 |
+| `xAxisScroll` | `Object` | `{}` | X 轴类目滚动配置，只作用于横轴 |
 | `customOption` | `Object` | `{}` | 对 ECharts option 的补充覆盖 |
-| `loading` | `Boolean` | `false` | 是否显示 loading |
+| `loading` | `Boolean` | `false` | 是否显示统一遮罩式 loading（非 ECharts 原生 loading） |
+| `stateConfig` | `Object` | `{}` | 统一状态配置，原样透传给 `BaseChart` |
 | `height` | `String \| Number` | `320` | 容器高度 |
 
 ### 7.3 BarLineChart 数据格式
@@ -287,20 +327,55 @@ colors: ['#A8BEFA', '#6B98F8']
 colors: ['#A8BEFA', '#6B98F8', '#3EE8FE']
 ```
 
-### 7.6 Events
+### 7.6 `xAxisScroll` 字段说明
+
+`xAxisScroll` 用于横轴类目较多的场景。
+它底层使用 ECharts `dataZoom`，只控制 X 轴，不会影响 Y 轴。
+
+推荐写法：
+
+```js
+const xAxisScroll = {
+  enabled: true,
+  visibleCount: 8,
+  startPosition: 'end',
+  showSlider: true,
+  inside: true
+}
+```
+
+字段说明：
+
+- `enabled`：是否开启 X 轴滚动；默认不开启。
+- `visibleCount`：初始窗口展示的类目数量，默认按 `8` 处理。
+- `startPosition`：初始窗口位置，支持 `start` / `end`，默认 `end`，即展示最新一段数据。
+- `startIndex`：初始窗口起始索引；传入合法数字时，优先级高于 `startPosition`。
+- `showSlider`：是否显示底部滚动条，默认 `true`。
+- `inside`：是否开启鼠标滚轮 / 触控板内部滚动，默认 `true`。
+
+默认行为：
+
+1. 当类目数量大于 `visibleCount` 时，组件生成 `dataZoom`。
+2. 默认从数据末尾向前取 `visibleCount` 个类目，适合“最新数据优先展示”。
+3. 当类目数量小于等于 `visibleCount` 时，不生成 `dataZoom`。
+4. 开启底部滚动条时，组件默认把 `grid.bottom` 提升到 `56`，避免滚动条挤压坐标轴。
+5. `customOption.dataZoom` 与 `customOption.grid.bottom` 优先级最高，可覆盖组件生成结果。
+
+### 7.7 Events
 
 | 事件名 | 参数 | 说明 |
 | --- | --- | --- |
 | `ready` | `chart` | 底层 ECharts 实例 |
 | `chart-click` | `params` | 点击图形元素时触发 |
 
-### 7.7 常见场景
+### 7.8 常见场景
 
 1. **基础柱线组合**：销售额 + 完成率双轴。
 2. **圆柱视觉**：看板类数据强调“柱体感”。
 3. **方柱视觉**：更偏装饰型、品牌型大屏风格。
 4. **堆叠柱图**：多个系列共享一组类目。
-5. **自定义展示细节**：通过 `customOption` 补 tooltip、legend、grid。
+5. **横轴类目滚动**：通过 `xAxisScroll` 默认展示最新一段数据。
+6. **自定义展示细节**：通过 `customOption` 补 tooltip、legend、grid、dataZoom。
 
 推荐查阅：
 
@@ -328,15 +403,16 @@ colors: ['#A8BEFA', '#6B98F8', '#3EE8FE']
 | `dimension` | `String` | `'2d'` | 维度：`2d` / `3d` |
 | `preset` | `String` | `'ratio'` | 预设：`ratio` / `rank` |
 | `heightMode` | `String` | `'equal'` | 3D 高度：`equal` / `value` |
-| `minHeight` | `Number` | `20` | 3D 最小扇区高度 |
-| `maxHeight` | `Number` | `80` | 3D 最大扇区高度 |
+| `minHeight` | `Number` | `10` | 3D 最小扇区高度 |
+| `maxHeight` | `Number` | `25` | 3D 最大扇区高度 |
 | `internalDiameterRatio` | `Number` | `0.6` | 环图内径比例 |
 | `roseRadiusRange` | `Array` | `[0.75, 1.15]` | 玫瑰图外半径映射范围 |
 | `showLabelLine` | `Boolean` | `false` | 是否显示标签引导线 |
 | `labelOptions` | `Object` | `{}` | 标签与引导线配置 |
 | `hideZeroValueSlices` | `Boolean` | `true` | 3D 下是否过滤 0 值扇区 |
 | `customOption` | `Object` | `{}` | 对 ECharts option 的补充覆盖 |
-| `loading` | `Boolean` | `false` | 是否显示 loading |
+| `loading` | `Boolean` | `false` | 是否显示统一遮罩式 loading（非 ECharts 原生 loading） |
+| `stateConfig` | `Object` | `{}` | 统一状态配置；3D 运行时失败时内部错误文案优先级更高 |
 | `height` | `String \| Number` | `320` | 容器高度 |
 
 ### 8.3 PieChart 数据格式
@@ -483,21 +559,35 @@ const labelOptions = {
 - `percent`：组件内部计算出来的百分比。
 - `data`：当前扇区对应的原始数据项。
 
-### 8.6 Events
+### 8.6 hover tooltip 说明
+
+`PieChart` 默认 hover tooltip 使用白底阴影卡片，
+内容为“彩色圆点 + 名称:值”，例如 `● 已完成:140`。
+
+3D 饼图的 surface hover 参数不是业务值，
+组件会自动回退到扇区原始数据，避免显示参数方程采样值。
+
+如果业务需要展示百分比、单位或多行内容，
+可通过 `customOption.tooltip.formatter` 自定义。
+
+### 8.7 Events
 
 | 事件名 | 参数 | 说明 |
 | --- | --- | --- |
 | `ready` | `chart` | 底层 ECharts 实例 |
 | `chart-click` | `params` | 点击图形元素时触发 |
-| `runtime-error` | `error` | 3D 运行时缺少 `echarts-gl` 等异常时触发 |
+| `runtime-error` | `error` | 3D 运行时未就绪或接入失败时触发 |
 
-### 8.7 3D 依赖说明
+### 8.8 3D 依赖说明
 
-- `dimension="2d"` 时，不需要安装 `echarts-gl`。
-- `dimension="3d"` 时，需要安装 `echarts-gl`。
-- 3D 模式会在运行时按需加载 `echarts-gl`。
+- `dimension="2d"` 时，不需要引入 `echarts-gl`。
+- `dimension="3d"` 时，需要业务项目先安装 `echarts-gl`。
+- 当前推荐直接在使用 3D `PieChart` 的业务页面中写 `import '@xq-labs/data-ui-v2/pie-chart/3d-runtime'`。
+- 如果多个页面都用 3D，也可以在应用入口统一引入这个桥接入口。
+- 包内保留 `pie-chart/3d-runtime.js` 物理入口，用于兼容不识别 `package.json#exports` 的老 webpack / Vue CLI 链路。
+- 若 3D 运行时未就绪，组件会优先显示内部错误文案，但仍保留 `stateConfig.empty.image` 与 `stateConfig.loading.text`。
 
-### 8.8 常见场景
+### 8.9 常见场景
 
 1. **普通饼图**：`variant="pie"`，适合占比展示。
 2. **环图**：`variant="ring"`，适合中心留白展示关键指标。
@@ -518,11 +608,131 @@ const labelOptions = {
 
 ---
 
-## 9. 外部配置怎么传
+## 9. `RadarChart` API
+
+### 9.1 组件定位
+
+`RadarChart` 用于承接能力画像、指标评分、多对象指标对比等场景。
+推荐通过 `data + indicators` 表达业务数据，由组件内部把字段映射为 ECharts `value` 数组。
+
+### 9.2 Props
+
+| Prop | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `data` | `Array` | `[]` | 雷达图业务数据数组 |
+| `indicators` | `Array` | `[]` | 雷达指标配置数组 |
+| `nameKey` | `String` | `'name'` | 系列名称字段 |
+| `variant` | `String` | `'area'` | 形态：`area` / `line` |
+| `preset` | `String` | `'compare'` | 预设：`compare` / `score` |
+| `colors` | `Array` | `[]` | 组件级系列色板，按数据顺序分配 |
+| `customOption` | `Object` | `{}` | 对 ECharts option 的补充覆盖 |
+| `loading` | `Boolean` | `false` | 是否显示统一遮罩式 loading |
+| `stateConfig` | `Object` | `{}` | 统一状态配置，原样透传给 `BaseChart` |
+| `height` | `String \| Number` | `320` | 容器高度 |
+
+### 9.3 RadarChart 数据格式
+
+`RadarChart` 的数据由两部分组成：
+
+1. `indicators`：定义雷达轴，`key` 决定从数据中取哪个字段。
+2. `data`：每一项代表一个雷达系列，例如本月、上月、目标值。
+
+推荐写法：
+
+```js
+const indicators = [
+  { key: 'quality', name: '质量', max: 100 },
+  { key: 'efficiency', name: '效率', max: 100 },
+  { key: 'cost', name: '成本控制', max: 100 },
+  { key: 'risk', name: '风险控制', max: 100 }
+]
+
+const data = [
+  {
+    name: '本月',
+    quality: 86,
+    efficiency: 78,
+    cost: 92,
+    risk: 70
+  },
+  {
+    name: '上月',
+    quality: 80,
+    efficiency: 72,
+    cost: 88,
+    risk: 76
+  }
+]
+```
+
+关键规则：
+
+- `indicators[i].key` 必须是非空字符串，非法指标会被过滤。
+- `indicators[i].name` 只负责展示，不参与取值。
+- `indicators[i].max` 非法时回退为 `100`，`min` 非法时回退为 `0`。
+- `data[i][nameKey]` 用于系列名称，缺失时回退为 `数据1`、`数据2`。
+- `data[i][indicator.key]` 会转为数值，非法值回退为 `0`。
+
+### 9.4 颜色配置
+
+`RadarChart` 支持组件级色板和单系列颜色覆盖。
+
+颜色优先级：
+
+```text
+data[i].color → colors[index] → DEFAULT_COLORS[index]
+```
+
+示例：
+
+```js
+const colors = ['#6B98F8', '#FF8A5B']
+
+const data = [
+  {
+    name: '本月',
+    color: '#6B98F8',
+    quality: 86,
+    efficiency: 78
+  }
+]
+```
+
+说明：
+
+- `data[i].color` 适合单个系列特殊强调。
+- `colors` 适合页面统一传业务色板。
+- `variant="area"` 会使用系列色生成半透明面积填充。
+- `variant="line"` 只使用系列色绘制折线和拐点，不生成面积填充。
+
+### 9.5 Events
+
+| 事件名 | 参数 | 说明 |
+| --- | --- | --- |
+| `ready` | `chart` | 底层 ECharts 实例 |
+| `chart-click` | `params` | 点击图形元素时触发 |
+
+### 9.6 常见场景
+
+1. **能力画像**：多个能力维度综合展示。
+2. **指标评分**：单个对象的健康度或成熟度评分。
+3. **多对象对比**：本月/上月、团队 A/团队 B 对比。
+4. **颜色强调**：通过 `colors` 或 `data[i].color` 控制系列色。
+5. **自定义展示细节**：通过 `customOption` 补 title、tooltip、radar 样式。
+
+推荐查阅：
+
+- `docs/examples/radar-chart.md`
+- Playground 路由：`/radar-chart/basic`
+- Playground 路由：`/radar-chart/custom`
+
+---
+
+## 10. 外部配置怎么传
 
 推荐用 `v-bind` 传一个清晰的配置对象，而不是在模板里零散写大量字面量。
 
-### 9.1 `BarLineChart`
+### 10.1 `BarLineChart`
 
 ```vue
 <BarLineChart
@@ -532,12 +742,14 @@ const labelOptions = {
     series,
     variant: 'cylinder',
     preset: 'compare',
+    xAxisScroll,
+    stateConfig,
     customOption
   }"
 />
 ```
 
-### 9.2 `PieChart`
+### 10.2 `PieChart`
 
 ```vue
 <PieChart
@@ -546,10 +758,27 @@ const labelOptions = {
     variant: 'ring',
     dimension: '3d',
     heightMode: 'value',
-    minHeight: 20,
-    maxHeight: 80,
+    minHeight: 10,
+    maxHeight: 25,
     showLabelLine: true,
     labelOptions,
+    stateConfig,
+    customOption
+  }"
+/>
+```
+
+### 10.3 `RadarChart`
+
+```vue
+<RadarChart
+  v-bind="{
+    data,
+    indicators,
+    variant: 'area',
+    preset: 'compare',
+    colors,
+    stateConfig,
     customOption
   }"
 />
@@ -557,11 +786,12 @@ const labelOptions = {
 
 ---
 
-## 10. 文档与示例导航
+## 11. 文档与示例导航
 
 - API 总览：`docs/api/overview.md`
 - 柱线图示例说明：`docs/examples/bar-line-chart.md`
 - 饼图示例说明：`docs/examples/pie-chart.md`
+- 雷达图示例说明：`docs/examples/radar-chart.md`
 - 可运行 Demo 库：`playground`
 
 建议阅读顺序：

package/docs/examples/bar-line-chart.md

@@ -27,7 +27,9 @@ Playground 中 `BarLineChart` 按分组路由组织：
     preset,
     barWidth,
     barGap,
-    customOption
+    xAxisScroll,
+    customOption,
+    stateConfig
   }"
 />
 ```
@@ -40,18 +42,54 @@ Playground 中 `BarLineChart` 按分组路由组织：
 - `variant`：`flat` / `cylinder` / `cube`。
 - `preset`：展示预设。
 - `barWidth`、`barGap`：柱体宽度与间距。
+- `xAxisScroll`：X 轴滚动配置，用于类目过多时默认展示最新数据窗口。
 - `customOption`：ECharts 展示细节覆盖。
+- `stateConfig`：统一收拢空态文案、空态图和 loading 文案。
+
+推荐结构：
+
+```js
+const xAxisScroll = {
+  enabled: true,
+  visibleCount: 8,
+  startPosition: 'end',
+  showSlider: true,
+  inside: true
+}
+
+const stateConfig = {
+  empty: {
+    text: '暂无柱线图数据',
+    image: 'https://example.com/bar-empty.png'
+  },
+  loading: {
+    text: '柱线图加载中...'
+  }
+}
+```
+
+`xAxisScroll` 字段说明：
+
+- `enabled`：是否开启 X 轴滚动；默认不开启。
+- `visibleCount`：窗口内展示的类目数量，默认按 `8` 处理。
+- `startPosition`：初始窗口位置，`end` 表示从末尾展示最新数据，`start` 表示从开头展示。
+- `startIndex`：指定窗口起始索引；传入合法数字时优先级高于 `startPosition`。
+- `showSlider`：是否显示底部滚动条。
+- `inside`：是否允许鼠标滚轮 / 触控板在图表内部滚动。
 
 ## 3. 如何自定义（推荐顺序）
 
 1. **优先 `series` 表达业务语义**：先确定字段、柱线类型、双轴和堆叠关系。
 2. **用 `series.colors` 控制系列配色**：把业务色板放在系列层。
-3. **`customOption` 补充细节**：用于 tooltip、legend、grid、坐标轴样式等展示项。
+3. **用 `xAxisScroll` 控制横轴窗口**：类目较多时默认展示最新 `visibleCount` 个类目。
+4. **`stateConfig` 收拢状态文案**：空态图、空态文案、loading 文案统一从这里传。
+5. **`customOption` 补充细节**：用于 tooltip、legend、grid、坐标轴样式、dataZoom 等展示项。
 
 不建议用 `customOption` 直接整体替换关键业务结构。
+如果必须完全自定义滚动条，可通过 `customOption.dataZoom` 覆盖 `xAxisScroll` 生成结果。
 
 ## 4. 可执行验收要点
 
 - 页面分组名称与路由一致：基础用法、圆柱样式、方柱样式、进阶配置、customOption 与自定义、实验室。
-- 文档示例包含 `series.colors` 与 `customOption`。
-- 文档明确实验室边界与推荐自定义顺序。
+- 文档示例包含 `series.colors`、`xAxisScroll`、`stateConfig` 与 `customOption`。
+- 文档明确实验室边界与推荐自定义顺序。