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

package/docs/api/overview.md

@@ -193,7 +193,7 @@ const stateConfig = {
 ### 7.1 组件定位
 
 `BarLineChart` 用于承接大多数柱线组合场景。  
-推荐先通过 `data + xAxisKey + series` 表达业务数据，再用 `variant`、`preset`、`customOption` 做增强。
+推荐先通过 `data + xAxisKey + series` 表达业务数据，再用 `variant`、`preset`、`barBackground`、`customOption` 做增强。
 
 ### 7.2 Props
 
@@ -201,17 +201,36 @@ const stateConfig = {
 | --- | --- | --- | --- |
 | `data` | `Array` | `[]` | 原始业务数据数组 |
 | `xAxisKey` | `String` | `'name'` | 横轴类目字段名 |
-| `series` | `Array` | `[]` | 系列定义数组，推荐包含 `key`、`name`、`kind` |
+| `series` | `Array` | `[]` | 系列定义数组，推荐包含 `key`、`name`、`kind`、`colors`，`cube` 方柱可额外传 `cubeGradientColors` |
 | `variant` | `String` | `'flat'` | 图形风格：`flat` / `cylinder` / `cube` |
 | `preset` | `String` | `'compare'` | 预设：`compare` / `trend` / `rank` |
 | `barWidth` | `Number` | `18` | 柱体宽度 |
 | `barGap` | `Number \| String` | `8` | 柱间距 |
+| `barBackground` | `Object` | `{}` | 柱形背景配置，为当前图中的柱系列渲染整列高度背景柱 |
 | `xAxisScroll` | `Object` | `{}` | X 轴类目滚动配置，只作用于横轴 |
 | `customOption` | `Object` | `{}` | 对 ECharts option 的补充覆盖 |
 | `loading` | `Boolean` | `false` | 是否显示统一遮罩式 loading（非 ECharts 原生 loading） |
+| `showEmptyState` | `Boolean` | `true` | 数据为空时是否展示统一空状态；关闭后仍保留图表容器与坐标系渲染 |
 | `stateConfig` | `Object` | `{}` | 统一状态配置，原样透传给 `BaseChart` |
 | `height` | `String \| Number` | `320` | 容器高度 |
 
+`barBackground` 推荐写法：
+
+```js
+const barBackground = {
+  show: true,
+  colors: ['#FFFFFF', '#D8E4FF'],
+  opacity: 0.2
+}
+```
+
+说明：
+
+- `show`：是否开启柱形背景。
+- `colors`：可选背景色板，支持 1~3 个色值；建议传不带 alpha 的颜色值，不传时按当前柱形默认背景色推导。
+- `opacity`：背景柱透明度，推荐传 `0 ~ 1` 之间的小数。
+- 背景高度语义：按当前坐标轴整列高度铺满，用来强化柱槽轮廓，不跟随单个数据值缩放。
+
 ### 7.3 BarLineChart 数据格式
 
 `BarLineChart` 的数据通常拆成两部分：
@@ -280,6 +299,13 @@ const series = [
     kind: 'bar',
     colors: ['#6B98F8']
   },
+  {
+    key: 'delivery',
+    name: '交付',
+    kind: 'bar',
+    colors: ['#6B8AF7', '#5B7CF0', '#8FA6FF'],
+    cubeGradientColors: ['#B8C8FF', '#8EA7FF', '#DCE5FF']
+  },
   {
     key: 'rate',
     name: '完成率',
@@ -319,6 +345,33 @@ const series = [
 - 传 `2` 个色值：按“左侧面 / 右侧面”解释，顶面自动提亮。
 - 传 `3` 个色值：按“左侧面 / 右侧面 / 顶面”解释。
 
+### 7.6 `cubeGradientColors` 配置规则
+
+`cubeGradientColors` 只在 `variant="cube"` 且当前系列是前景 `bar` 时生效，用来补充三面的渐变终点色。
+
+规则说明：
+
+- 类型要求是 `Array`，非数组会被忽略。
+- 最多读取前 `1~3 个色值`，顺序固定为“左侧面 / 右侧面 / 顶面”。
+- 未传某一面的终点色时，会回退到该面的主色。
+- 只影响前景方柱的 `fill` 渐变，不改变 `stroke / legend / tooltip` 的主色语义。
+- 背景方柱不读取 `cubeGradientColors`，继续保持纯色 + 透明度的柱槽视觉。
+- `flat / cylinder / line` 会忽略该字段。
+
+推荐示例：
+
+```js
+const series = [
+  {
+    key: 'delivery',
+    name: '交付',
+    kind: 'bar',
+    colors: ['#6B8AF7', '#5B7CF0', '#8FA6FF'],
+    cubeGradientColors: ['#B8C8FF', '#8EA7FF', '#DCE5FF']
+  }
+]
+```
+
 示例：
 
 ```js
@@ -327,7 +380,7 @@ colors: ['#A8BEFA', '#6B98F8']
 colors: ['#A8BEFA', '#6B98F8', '#3EE8FE']
 ```
 
-### 7.6 `xAxisScroll` 字段说明
+### 7.7 `xAxisScroll` 字段说明
 
 `xAxisScroll` 用于横轴类目较多的场景。
 它底层使用 ECharts `dataZoom`，只控制 X 轴，不会影响 Y 轴。
@@ -361,14 +414,14 @@ const xAxisScroll = {
 4. 开启底部滚动条时，组件默认把 `grid.bottom` 提升到 `56`，避免滚动条挤压坐标轴。
 5. `customOption.dataZoom` 与 `customOption.grid.bottom` 优先级最高，可覆盖组件生成结果。
 
-### 7.7 Events
+### 7.8 Events
 
 | 事件名 | 参数 | 说明 |
 | --- | --- | --- |
 | `ready` | `chart` | 底层 ECharts 实例 |
 | `chart-click` | `params` | 点击图形元素时触发 |
 
-### 7.8 常见场景
+### 7.9 常见场景
 
 1. **基础柱线组合**：销售额 + 完成率双轴。
 2. **圆柱视觉**：看板类数据强调“柱体感”。
@@ -412,6 +465,7 @@ const xAxisScroll = {
 | `hideZeroValueSlices` | `Boolean` | `true` | 3D 下是否过滤 0 值扇区 |
 | `customOption` | `Object` | `{}` | 对 ECharts option 的补充覆盖 |
 | `loading` | `Boolean` | `false` | 是否显示统一遮罩式 loading（非 ECharts 原生 loading） |
+| `showEmptyState` | `Boolean` | `true` | 是否在普通空数据场景展示统一空状态；不影响 3D 运行时失败等必须提示的错误场景 |
 | `stateConfig` | `Object` | `{}` | 统一状态配置；3D 运行时失败时内部错误文案优先级更高 |
 | `height` | `String \| Number` | `320` | 容器高度 |
 
@@ -742,6 +796,7 @@ const data = [
     series,
     variant: 'cylinder',
     preset: 'compare',
+    barBackground,
     xAxisScroll,
     stateConfig,
     customOption

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

@@ -27,8 +27,10 @@ Playground 中 `BarLineChart` 按分组路由组织：
     preset,
     barWidth,
     barGap,
+    barBackground,
     xAxisScroll,
     customOption,
+    showEmptyState,
     stateConfig
   }"
 />
@@ -42,8 +44,10 @@ Playground 中 `BarLineChart` 按分组路由组织：
 - `variant`：`flat` / `cylinder` / `cube`。
 - `preset`：展示预设。
 - `barWidth`、`barGap`：柱体宽度与间距。
+- `barBackground`：柱形背景配置，用于为当前图中的柱系列补整列高度背景柱。
 - `xAxisScroll`：X 轴滚动配置，用于类目过多时默认展示最新数据窗口。
 - `customOption`：ECharts 展示细节覆盖。
+- `showEmptyState`：数据为空时是否展示统一空状态；关闭后保留图表容器与坐标系本身。
 - `stateConfig`：统一收拢空态文案、空态图和 loading 文案。
 
 推荐结构：
@@ -57,6 +61,12 @@ const xAxisScroll = {
   inside: true
 }
 
+const barBackground = {
+  show: true,
+  colors: ['#FFFFFF', '#D8E4FF'],
+  opacity: 0.2
+}
+
 const stateConfig = {
   empty: {
     text: '暂无柱线图数据',
@@ -66,6 +76,8 @@ const stateConfig = {
     text: '柱线图加载中...'
   }
 }
+
+const showEmptyState = false
 ```
 
 `xAxisScroll` 字段说明：
@@ -77,13 +89,44 @@ const stateConfig = {
 - `showSlider`：是否显示底部滚动条。
 - `inside`：是否允许鼠标滚轮 / 触控板在图表内部滚动。
 
+`barBackground` 字段说明：
+
+- `show`：是否开启柱形背景。
+- `colors`：可选背景色板，支持 1~3 个色值；建议传不带 alpha 的颜色值，不传时按当前柱形默认背景色推导。
+- `opacity`：背景柱透明度，推荐传 `0 ~ 1` 之间的小数。
+
+`cube` 方柱补充字段：
+
+- `series.colors`：继续按左/右/顶顺序提供三面的主色，兼容现有 1~3 个色值写法。
+- `cubeGradientColors`：仅 `cube` 前景柱生效，按左/右/顶顺序提供三面的渐变终点色；缺失某一面时会回退到该面的主色。
+- 背景方柱不读取 `cubeGradientColors`，继续保持纯色 + 透明度的柱槽视觉。
+
+```js
+const series = [
+  {
+    key: 'delivery',
+    name: '交付',
+    kind: 'bar',
+    colors: ['#6B8AF7', '#5B7CF0', '#8FA6FF'],
+    cubeGradientColors: ['#B8C8FF', '#8EA7FF', '#DCE5FF']
+  }
+]
+```
+
+背景高度语义：
+
+- `barBackground` 渲染的是当前坐标轴下的整列高度背景柱，不跟随单个数据值缩放。
+
 ## 3. 如何自定义（推荐顺序）
 
 1. **优先 `series` 表达业务语义**：先确定字段、柱线类型、双轴和堆叠关系。
 2. **用 `series.colors` 控制系列配色**：把业务色板放在系列层。
-3. **用 `xAxisScroll` 控制横轴窗口**：类目较多时默认展示最新 `visibleCount` 个类目。
-4. **`stateConfig` 收拢状态文案**：空态图、空态文案、loading 文案统一从这里传。
-5. **`customOption` 补充细节**：用于 tooltip、legend、grid、坐标轴样式、dataZoom 等展示项。
+3. **`cube` 方柱可再传 `cubeGradientColors`**：只补前景三面的渐变终点色，不影响背景方柱。
+4. **用 `barBackground` 强化柱槽轮廓**：需要整列高度背景时，再开启背景柱并调透明度。
+5. **用 `xAxisScroll` 控制横轴窗口**：类目较多时默认展示最新 `visibleCount` 个类目。
+6. **按需关闭 `showEmptyState`**：需要保留空图表骨架时可传 `false`，否则默认展示统一空态。
+7. **`stateConfig` 收拢状态文案**：空态图、空态文案、loading 文案统一从这里传。
+8. **`customOption` 补充细节**：用于 tooltip、legend、grid、坐标轴样式、dataZoom 等展示项。
 
 不建议用 `customOption` 直接整体替换关键业务结构。
 如果必须完全自定义滚动条，可通过 `customOption.dataZoom` 覆盖 `xAxisScroll` 生成结果。
@@ -91,5 +134,5 @@ const stateConfig = {
 ## 4. 可执行验收要点
 
 - 页面分组名称与路由一致：基础用法、圆柱样式、方柱样式、进阶配置、customOption 与自定义、实验室。
-- 文档示例包含 `series.colors`、`xAxisScroll`、`stateConfig` 与 `customOption`。
+- 文档示例包含 `series.colors`、`cubeGradientColors`、`barBackground`、`xAxisScroll`、`showEmptyState`、`stateConfig` 与 `customOption`。
 - 文档明确实验室边界与推荐自定义顺序。

package/docs/examples/pie-chart.md

@@ -30,6 +30,7 @@ Playground 中 `PieChart` 采用分组路由组织，按能力查阅：
     hideZeroValueSlices,
     labelOptions,
     customOption,
+    showEmptyState,
     stateConfig
   }"
 />
@@ -45,6 +46,7 @@ Playground 中 `PieChart` 采用分组路由组织，按能力查阅：
 - `hideZeroValueSlices`：3D 下是否隐藏 0 值扇区。
 - `labelOptions`：标签与引导线细节（格式、线长、颜色等）。
 - `customOption`：ECharts 细节覆盖（标题、提示、图例等）。
+- `showEmptyState`：普通空数据时是否展示统一空状态。
 - `stateConfig`：统一收拢空态文案、空态图和 loading 文案。
 
 推荐结构：
@@ -59,6 +61,8 @@ const stateConfig = {
     text: '饼图加载中...'
   }
 }
+
+const showEmptyState = false
 ```
 
 ## 2.1 3D 依赖说明
@@ -83,8 +87,9 @@ import '@xq-labs/data-ui-v2/pie-chart/3d-runtime'
 
 1. **优先公开 props**：先用 `variant`、`dimension`、`preset`、高度参数表达业务语义。
 2. **其次 `labelOptions`**：标签文案、引导线样式优先在这里完成。
-3. **状态文案统一交给 `stateConfig`**：空态图、空态文案、loading 文案不要分散到多个字段。
-4. **最后 `customOption`**：仅用于补充 ECharts 展示细节。
+3. **按需控制 `showEmptyState`**：需要保留空画布时传 `false`；默认继续展示统一空态。
+4. **状态文案统一交给 `stateConfig`**：空态图、空态文案、loading 文案不要分散到多个字段。
+5. **最后 `customOption`**：仅用于补充 ECharts 展示细节。
 
 不建议业务侧直接拼接或重写内部 `series`，避免覆盖组件内置能力与升级兼容性。
 
@@ -99,6 +104,7 @@ import '@xq-labs/data-ui-v2/pie-chart/3d-runtime'
 1. `PieChart` 会优先显示组件内部错误文案。
 2. `stateConfig.empty.image` 仍然生效。
 3. `stateConfig.loading.text` 仍然生效。
+4. `showEmptyState=false` 也不会关闭这类接入错误提示。
 
 也就是说，业务可以继续自定义空态图，但不能覆盖这类
 “请先在业务页面中执行 `import '@xq-labs/data-ui-v2/pie-chart/3d-runtime'`”提示。
@@ -106,5 +112,5 @@ import '@xq-labs/data-ui-v2/pie-chart/3d-runtime'
 ## 4. 可执行验收要点
 
 - 页面分组名称与路由一致：基础用法、2D 形态、3D 能力、标签与引导线、customOption 与自定义、实验室。
-- 文档示例包含 `hideZeroValueSlices`、`stateConfig` 与 `customOption`。
+- 文档示例包含 `hideZeroValueSlices`、`showEmptyState`、`stateConfig` 与 `customOption`。
 - 文档明确实验室边界与推荐自定义顺序。

package/es/bar-line-chart/index.js

@@ -1,5 +1,5 @@
 import '../../theme-chalk/index.css';
-import { B as BarLineChart } from '../index-d01ce220.js';
+import { B as BarLineChart } from '../index-1e113c13.js';
 import { w as withInstall } from '../with-install-e405b463.js';
 import 'echarts/core';
 import 'echarts/charts';