@xq-labs/data-ui-v2 0.3.0 → 0.4.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
 
@@ -206,12 +206,30 @@ const stateConfig = {
 | `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） |
 | `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` 的数据通常拆成两部分：
@@ -742,6 +760,7 @@ const data = [
     series,
     variant: 'cylinder',
     preset: 'compare',
+    barBackground,
     xAxisScroll,
     stateConfig,
     customOption

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

@@ -27,6 +27,7 @@ Playground 中 `BarLineChart` 按分组路由组织：
     preset,
     barWidth,
     barGap,
+    barBackground,
     xAxisScroll,
     customOption,
     stateConfig
@@ -42,6 +43,7 @@ Playground 中 `BarLineChart` 按分组路由组织：
 - `variant`：`flat` / `cylinder` / `cube`。
 - `preset`：展示预设。
 - `barWidth`、`barGap`：柱体宽度与间距。
+- `barBackground`：柱形背景配置，用于为当前图中的柱系列补整列高度背景柱。
 - `xAxisScroll`：X 轴滚动配置，用于类目过多时默认展示最新数据窗口。
 - `customOption`：ECharts 展示细节覆盖。
 - `stateConfig`：统一收拢空态文案、空态图和 loading 文案。
@@ -57,6 +59,12 @@ const xAxisScroll = {
   inside: true
 }
 
+const barBackground = {
+  show: true,
+  colors: ['#FFFFFF', '#D8E4FF'],
+  opacity: 0.2
+}
+
 const stateConfig = {
   empty: {
     text: '暂无柱线图数据',
@@ -77,13 +85,24 @@ const stateConfig = {
 - `showSlider`：是否显示底部滚动条。
 - `inside`：是否允许鼠标滚轮 / 触控板在图表内部滚动。
 
+`barBackground` 字段说明：
+
+- `show`：是否开启柱形背景。
+- `colors`：可选背景色板，支持 1~3 个色值；建议传不带 alpha 的颜色值，不传时按当前柱形默认背景色推导。
+- `opacity`：背景柱透明度，推荐传 `0 ~ 1` 之间的小数。
+
+背景高度语义：
+
+- `barBackground` 渲染的是当前坐标轴下的整列高度背景柱，不跟随单个数据值缩放。
+
 ## 3. 如何自定义（推荐顺序）
 
 1. **优先 `series` 表达业务语义**：先确定字段、柱线类型、双轴和堆叠关系。
 2. **用 `series.colors` 控制系列配色**：把业务色板放在系列层。
-3. **用 `xAxisScroll` 控制横轴窗口**：类目较多时默认展示最新 `visibleCount` 个类目。
-4. **`stateConfig` 收拢状态文案**：空态图、空态文案、loading 文案统一从这里传。
-5. **`customOption` 补充细节**：用于 tooltip、legend、grid、坐标轴样式、dataZoom 等展示项。
+3. **用 `barBackground` 强化柱槽轮廓**：需要整列高度背景时，再开启背景柱并调透明度。
+4. **用 `xAxisScroll` 控制横轴窗口**：类目较多时默认展示最新 `visibleCount` 个类目。
+5. **`stateConfig` 收拢状态文案**：空态图、空态文案、loading 文案统一从这里传。
+6. **`customOption` 补充细节**：用于 tooltip、legend、grid、坐标轴样式、dataZoom 等展示项。
 
 不建议用 `customOption` 直接整体替换关键业务结构。
 如果必须完全自定义滚动条，可通过 `customOption.dataZoom` 覆盖 `xAxisScroll` 生成结果。
@@ -91,5 +110,5 @@ const stateConfig = {
 ## 4. 可执行验收要点
 
 - 页面分组名称与路由一致：基础用法、圆柱样式、方柱样式、进阶配置、customOption 与自定义、实验室。
-- 文档示例包含 `series.colors`、`xAxisScroll`、`stateConfig` 与 `customOption`。
+- 文档示例包含 `series.colors`、`barBackground`、`xAxisScroll`、`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-914fbae3.js';
 import { w as withInstall } from '../with-install-e405b463.js';
 import 'echarts/core';
 import 'echarts/charts';

package/es/{index-d01ce220.js → index-914fbae3.js}

@@ -129,6 +129,19 @@ function resolveSeriesColor$1(item, index) {
   }
   return DEFAULT_COLORS[index % DEFAULT_COLORS.length];
 }
+function collectBarSeries(normalizedSeries) {
+  return normalizedSeries.map(function (item, originalIndex) {
+    return _objectSpread2(_objectSpread2({}, item), {}, {
+      originalIndex: originalIndex
+    });
+  }).filter(function (item) {
+    return item.kind === 'bar';
+  }).map(function (item, barSeriesIndex) {
+    return _objectSpread2(_objectSpread2({}, item), {}, {
+      barSeriesIndex: barSeriesIndex
+    });
+  });
+}
 
 /**
  * 归一化颜色入参。
@@ -479,6 +492,53 @@ function createBarLayout(barSeries, barWidth, barGap) {
     barGap: resolvedBarGap
   };
 }
+function pickBackgroundSlotSeries(barSeries) {
+  var renderedStacks = new Set();
+  return barSeries.filter(function (item) {
+    if (!item.stack) {
+      return true;
+    }
+    if (renderedStacks.has(item.stack)) {
+      return false;
+    }
+    renderedStacks.add(item.stack);
+    return true;
+  });
+}
+function createBackgroundSeriesData(rawData) {
+  return rawData.map(function (row, rowIndex) {
+    return {
+      value: [rowIndex]
+    };
+  });
+}
+function resolveBackgroundFaceAlpha(key, opacity) {
+  var alphaMap = {
+    left: 0.82,
+    right: 1,
+    top: 1.8,
+    middle: 0.82,
+    bottom: 1.28,
+    legend: 1
+  };
+  var ratio = alphaMap[key] || 1;
+  return Math.max(0, Math.min(1, opacity * ratio));
+}
+function applyBackgroundFaceAlphaToColorMap(colorMap, opacity) {
+  return Object.keys(colorMap || {}).reduce(function (result, key) {
+    result[key] = applyAlphaToColor(colorMap[key], resolveBackgroundFaceAlpha(key, opacity));
+    return result;
+  }, {});
+}
+function normalizeBackgroundColors(barBackground, item) {
+  if (Array.isArray(barBackground && barBackground.colors) && barBackground.colors.length > 0) {
+    return barBackground.colors;
+  }
+  if (Array.isArray(item && item.colors) && item.colors.length > 0) {
+    return item.colors;
+  }
+  return undefined;
+}
 
 /**
  * 创建堆叠累加器。
@@ -607,13 +667,7 @@ function buildCustomBarSeries(_ref) {
     barGap = _ref.barGap,
     createRenderItem = _ref.createRenderItem,
     resolveColorMap = _ref.resolveColorMap;
-  var barSeries = normalizedSeries.map(function (item, originalIndex) {
-    return _objectSpread2(_objectSpread2({}, item), {}, {
-      originalIndex: originalIndex
-    });
-  }).filter(function (item) {
-    return item.kind === 'bar';
-  });
+  var barSeries = collectBarSeries(normalizedSeries);
   var layout = createBarLayout(barSeries, barWidth, barGap);
   var barSeriesWithData = buildBarSeriesData(rawData, barSeries);
   return barSeriesWithData.map(function (item, index) {
@@ -642,6 +696,57 @@ function buildCustomBarSeries(_ref) {
     };
   });
 }
+function buildBackgroundCustomBarSeries(_ref2) {
+  var rawData = _ref2.rawData,
+    normalizedSeries = _ref2.normalizedSeries,
+    barWidth = _ref2.barWidth,
+    barGap = _ref2.barGap,
+    _ref2$barBackground = _ref2.barBackground,
+    barBackground = _ref2$barBackground === void 0 ? {} : _ref2$barBackground,
+    createRenderItem = _ref2.createRenderItem,
+    resolveColorMap = _ref2.resolveColorMap;
+  if (!barBackground.show) {
+    return [];
+  }
+  var barSeries = collectBarSeries(normalizedSeries);
+  if (!barSeries.length) {
+    return [];
+  }
+  var layout = createBarLayout(barSeries, barWidth, barGap);
+  var backgroundSeriesData = createBackgroundSeriesData(rawData);
+  return pickBackgroundSlotSeries(barSeries).map(function (item) {
+    var slotKey = item.stack || "__slot_".concat(item.barSeriesIndex);
+    var slotIndex = layout.slotMap[slotKey];
+    var fallbackColor = resolveSeriesColor$1(item, item.originalIndex);
+    var palette = normalizeBackgroundColors(barBackground, item);
+    var baseColorMap = resolveColorMap ? resolveColorMap(palette, fallbackColor) : {
+      legend: fallbackColor
+    };
+    var backgroundColorMap = applyBackgroundFaceAlphaToColorMap(baseColorMap, barBackground.opacity);
+    return {
+      name: item.name,
+      type: 'custom',
+      stack: item.stack,
+      yAxisIndex: item.yAxisIndex || 0,
+      isBackground: true,
+      silent: true,
+      tooltip: {
+        show: false
+      },
+      renderItem: createRenderItem(layout, slotIndex, backgroundColorMap, _objectSpread2(_objectSpread2({}, item), {}, {
+        isBackground: true
+      })),
+      encode: {
+        x: 0
+      },
+      itemStyle: {
+        color: backgroundColorMap.legend || applyAlphaToColor(fallbackColor, barBackground.opacity)
+      },
+      data: backgroundSeriesData,
+      z: 0
+    };
+  });
+}
 
 /**
  * 归一化 flat 模式下的 `barGap`。
@@ -705,6 +810,27 @@ function resolveFlatBarColors(item, index) {
     end: darkenColor(fallbackColor, 0.12)
   };
 }
+function resolveFlatBackgroundColors(item, index, barBackground) {
+  var paletteSource = Array.isArray(barBackground.colors) && barBackground.colors.length > 0 ? {
+    colors: barBackground.colors
+  } : item;
+  var colorMap = resolveFlatBarColors(paletteSource, index);
+  return {
+    start: applyAlphaToColor(colorMap.start, barBackground.opacity),
+    middle: applyAlphaToColor(colorMap.middle, barBackground.opacity),
+    end: applyAlphaToColor(colorMap.end, barBackground.opacity)
+  };
+}
+function shouldEnableBackground(item, renderedStacks) {
+  if (!item.stack) {
+    return true;
+  }
+  if (renderedStacks.has(item.stack)) {
+    return false;
+  }
+  renderedStacks.add(item.stack);
+  return true;
+}
 
 /**
  * 创建柱体纵向渐变。
@@ -736,9 +862,12 @@ function createFlatBarLineSeries(_ref) {
   var normalizedSeries = _ref.normalizedSeries,
     rawData = _ref.rawData,
     barWidth = _ref.barWidth,
-    barGap = _ref.barGap;
+    barGap = _ref.barGap,
+    _ref$barBackground = _ref.barBackground,
+    barBackground = _ref$barBackground === void 0 ? {} : _ref$barBackground;
   var resolvedBarWidth = Number.isFinite(Number(barWidth)) ? Number(barWidth) : 18;
   var resolvedBarGap = toBarGapValue(barGap);
+  var renderedStacks = new Set();
   return normalizedSeries.map(function (item, index) {
     var isLine = item.kind === 'line';
     var color = resolveSeriesColor(item, index);
@@ -759,11 +888,18 @@ function createFlatBarLineSeries(_ref) {
         yAxisIndex: item.yAxisIndex
       });
     }
+    var showBackground = barBackground.show && shouldEnableBackground(item, renderedStacks);
+    var backgroundColors = resolveFlatBackgroundColors(item, index, barBackground);
     return _objectSpread2(_objectSpread2({}, baseSeries), {}, {
       stack: item.stack,
       barWidth: resolvedBarWidth,
-      barGap: resolvedBarGap
-    });
+      barGap: resolvedBarGap,
+      showBackground: showBackground
+    }, showBackground ? {
+      backgroundStyle: {
+        color: createBarGradient(backgroundColors)
+      }
+    } : {});
   });
 }
 
@@ -827,9 +963,63 @@ function createFaceGradient(x0, y0, x1, y1, startColor, endColor) {
  * 创建方柱渲染器。
  * 参考案例使用三块 polygon 拼接成立方体，而不是“正面 rect + 顶面/侧面”。
  */
-function createCubeRenderItem(layout, slotIndex, colorMap) {
+function createCubeRenderItem(layout, slotIndex, colorMap, seriesItem) {
   return function renderItem(params, api) {
     var rowIndex = api.value(0);
+    var offsetX = getBarOffset(layout, slotIndex);
+    var centerPoint = api.coord([rowIndex, 0]);
+    var centerX = centerPoint[0] + offsetX;
+    var halfWidth = layout.barWidth / 2;
+    var offsetY = Math.tan(Math.PI / 9) * halfWidth;
+    var leftFaceGradient = createFaceGradient(0, 0, 0, 1, colorMap.left, colorMap.left);
+    var rightFaceGradient = createFaceGradient(0, 0, 0, 1, colorMap.right, colorMap.right);
+    var topFaceGradient = createFaceGradient(0, 0, 1, 0, colorMap.top, colorMap.top);
+    if (seriesItem && seriesItem.isBackground === true) {
+      var coordSys = params.coordSys || {};
+      var clipX = coordSys.x || 0;
+      var _topY = coordSys.y || 0;
+      var width = coordSys.width || 0;
+      var _baseY = _topY + (coordSys.height || 0);
+      var _topSurfaceY = _topY + Math.abs(offsetY - 1);
+      return {
+        type: 'group',
+        clipPath: {
+          type: 'rect',
+          shape: {
+            x: clipX,
+            y: _topY,
+            width: width,
+            height: coordSys.height || 0
+          }
+        },
+        children: [{
+          type: 'polygon',
+          shape: {
+            points: [[centerX, _topSurfaceY + offsetY - 1], [centerX - halfWidth, _topSurfaceY], [centerX - halfWidth, _baseY - offsetY], [centerX, _baseY - 1]]
+          },
+          style: {
+            fill: leftFaceGradient
+          }
+        }, {
+          type: 'polygon',
+          shape: {
+            points: [[centerX, _topSurfaceY + offsetY - 1], [centerX + halfWidth, _topSurfaceY], [centerX + halfWidth, _baseY - offsetY], [centerX, _baseY - 1]]
+          },
+          style: {
+            fill: rightFaceGradient
+          }
+        }, {
+          type: 'polygon',
+          shape: {
+            points: [[centerX, _topSurfaceY + offsetY - 1], [centerX + halfWidth, _topSurfaceY], [centerX, _topSurfaceY - offsetY + 1], [centerX - halfWidth, _topSurfaceY]]
+          },
+          style: {
+            fill: topFaceGradient
+          },
+          z2: 2
+        }]
+      };
+    }
     var endValue = api.value(1);
     var baseValue = api.value(2);
     var rawValue = api.value(3);
@@ -840,20 +1030,13 @@ function createCubeRenderItem(layout, slotIndex, colorMap) {
     }
     var endPoint = api.coord([rowIndex, endValue]);
     var basePoint = api.coord([rowIndex, baseValue]);
-    var offsetX = getBarOffset(layout, slotIndex);
-    var centerX = endPoint[0] + offsetX;
     var topY = endPoint[1];
     var baseY = basePoint[1];
-    var halfWidth = layout.barWidth / 2;
-    var offsetY = Math.tan(Math.PI / 9) * halfWidth;
     var isPositive = rawValue >= 0;
     var connectorOverlap = stackStart ? 0 : Math.max(2, Math.round(offsetY));
     var connectorCapOffset = stackEnd ? 0 : Math.min(2, offsetY * 0.45);
     var connectBaseY = isPositive ? baseY + connectorOverlap : baseY - connectorOverlap;
     var topSurfaceY = topY + connectorCapOffset;
-    var leftFaceGradient = createFaceGradient(0, 0, 0, 1, colorMap.left, colorMap.left);
-    var rightFaceGradient = createFaceGradient(0, 0, 0, 1, colorMap.right, colorMap.right);
-    var topFaceGradient = createFaceGradient(0, 0, 1, 0, colorMap.top, colorMap.top);
     return {
       type: 'group',
       children: [{
@@ -899,6 +1082,15 @@ function createCubeRenderItem(layout, slotIndex, colorMap) {
 function createCubeBarLineOption(normalizedInput) {
   var flatOption = createFlatBarLineOption(normalizedInput);
   var flatSeries = createFlatBarLineSeries(normalizedInput);
+  var backgroundSeries = buildBackgroundCustomBarSeries({
+    rawData: normalizedInput.rawData,
+    normalizedSeries: normalizedInput.normalizedSeries,
+    barWidth: normalizedInput.barWidth,
+    barGap: normalizedInput.barGap,
+    barBackground: normalizedInput.barBackground,
+    createRenderItem: createCubeRenderItem,
+    resolveColorMap: resolveCubeColors
+  });
   var customBarSeries = buildCustomBarSeries({
     rawData: normalizedInput.rawData,
     normalizedSeries: normalizedInput.normalizedSeries,
@@ -917,7 +1109,7 @@ function createCubeBarLineOption(normalizedInput) {
     return flatSeries[index];
   });
   return _objectSpread2(_objectSpread2({}, flatOption), {}, {
-    series: series
+    series: [].concat(_toConsumableArray(series), _toConsumableArray(backgroundSeries))
   });
 }
 
@@ -941,6 +1133,20 @@ function createEllipsePolygon(cx, cy, rx, ry) {
   }
   return polygonPoints;
 }
+function createEllipseArcPoints(cx, cy, rx, ry, startAngle, endAngle) {
+  var points = arguments.length > 6 && arguments[6] !== undefined ? arguments[6] : 12;
+  var arcPoints = [];
+  for (var index = 0; index <= points; index += 1) {
+    var angle = startAngle + (endAngle - startAngle) * index / points;
+    arcPoints.push([cx + Math.cos(angle) * rx, cy + Math.sin(angle) * ry]);
+  }
+  return arcPoints;
+}
+function createCylinderSidePolygon(cx, topCy, bottomCy, rx, ry) {
+  var topLowerArc = createEllipseArcPoints(cx, topCy, rx, ry, Math.PI, 0);
+  var bottomUpperArc = createEllipseArcPoints(cx, bottomCy, rx, ry, 0, -Math.PI);
+  return [].concat(_toConsumableArray(topLowerArc), _toConsumableArray(bottomUpperArc));
+}
 
 /**
  * 创建圆柱渲染器。
@@ -949,9 +1155,76 @@ function createEllipsePolygon(cx, cy, rx, ry) {
  * 2. 主体用纵向渐变矩形模拟曲面；
  * 3. 堆叠连接处保留底片，但不绘制深色描边和弧线，避免形成脏色带。
  */
-function createCylinderRenderItem(layout, slotIndex, colorMap) {
+function createCylinderRenderItem(layout, slotIndex, colorMap, seriesItem) {
   return function renderItem(params, api) {
     var rowIndex = api.value(0);
+    var offsetX = getBarOffset(layout, slotIndex);
+    var centerPoint = api.coord([rowIndex, 0]);
+    var centerX = centerPoint[0] + offsetX;
+    var radiusX = layout.barWidth / 2;
+    var radiusY = radiusX * 0.4;
+    var createSideGradient = function createSideGradient(topColor, middleColor, bottomColor) {
+      var opacity = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : CYLINDER_SIDE_OPACITY;
+      return new graphic.LinearGradient(0, 0, 0, 1, [{
+        offset: 0,
+        color: opacity === null ? topColor : applyAlphaToColor(topColor, opacity)
+      }, {
+        offset: 0.55,
+        color: opacity === null ? middleColor : applyAlphaToColor(middleColor, opacity)
+      }, {
+        offset: 1,
+        color: opacity === null ? bottomColor : applyAlphaToColor(bottomColor, opacity)
+      }]);
+    };
+    if (seriesItem && seriesItem.isBackground === true) {
+      var coordSys = params.coordSys || {};
+      var clipX = coordSys.x || 0;
+      var topY = coordSys.y || 0;
+      var width = coordSys.width || 0;
+      var height = coordSys.height || 0;
+      var _topEllipseY = topY + radiusY;
+      var bottomEllipseY = topY + height - radiusY;
+      return {
+        type: 'group',
+        clipPath: {
+          type: 'rect',
+          shape: {
+            x: clipX,
+            y: topY,
+            width: width,
+            height: height
+          }
+        },
+        children: [{
+          type: 'polygon',
+          shape: {
+            points: createEllipsePolygon(centerX, bottomEllipseY, radiusX, radiusY)
+          },
+          style: {
+            fill: colorMap.bottom
+          },
+          z: 0
+        }, {
+          type: 'polygon',
+          shape: {
+            points: createCylinderSidePolygon(centerX, _topEllipseY, bottomEllipseY, radiusX, radiusY)
+          },
+          style: {
+            fill: createSideGradient(colorMap.middle, colorMap.middle, colorMap.bottom, null)
+          },
+          z: 1
+        }, {
+          type: 'polygon',
+          shape: {
+            points: createEllipsePolygon(centerX, _topEllipseY, radiusX, radiusY)
+          },
+          style: {
+            fill: colorMap.top
+          },
+          z2: 2
+        }]
+      };
+    }
     var endValue = api.value(1);
     var baseValue = api.value(2);
     var rawValue = api.value(3);
@@ -962,10 +1235,6 @@ function createCylinderRenderItem(layout, slotIndex, colorMap) {
     }
     var endPoint = api.coord([rowIndex, endValue]);
     var basePoint = api.coord([rowIndex, baseValue]);
-    var offsetX = getBarOffset(layout, slotIndex);
-    var centerX = endPoint[0] + offsetX;
-    var radiusX = layout.barWidth / 2;
-    var radiusY = radiusX * 0.4;
     var isPositive = rawValue >= 0;
     var barHeight = Math.abs(endPoint[1] - basePoint[1]);
     var visibleEllipseY = endPoint[1];
@@ -980,16 +1249,7 @@ function createCylinderRenderItem(layout, slotIndex, colorMap) {
     var gradientTopColor = isPositive ? colorMap.middle : darkenColor(colorMap.bottom, 0.05);
     var gradientMiddleColor = colorMap.middle;
     var gradientBottomColor = isPositive ? colorMap.bottom : colorMap.middle;
-    var sideGradient = new graphic.LinearGradient(0, 0, 0, 1, [{
-      offset: 0,
-      color: applyAlphaToColor(gradientTopColor, CYLINDER_SIDE_OPACITY)
-    }, {
-      offset: 0.55,
-      color: applyAlphaToColor(gradientMiddleColor, CYLINDER_SIDE_OPACITY)
-    }, {
-      offset: 1,
-      color: applyAlphaToColor(gradientBottomColor, CYLINDER_SIDE_OPACITY)
-    }]);
+    var sideGradient = createSideGradient(gradientTopColor, gradientMiddleColor, gradientBottomColor);
     return {
       type: 'group',
       children: [].concat(_toConsumableArray(showBottomPlate ? [{
@@ -1036,6 +1296,15 @@ function createCylinderRenderItem(layout, slotIndex, colorMap) {
 function createCylinderBarLineOption(normalizedInput) {
   var flatOption = createFlatBarLineOption(normalizedInput);
   var flatSeries = createFlatBarLineSeries(normalizedInput);
+  var backgroundSeries = buildBackgroundCustomBarSeries({
+    rawData: normalizedInput.rawData,
+    normalizedSeries: normalizedInput.normalizedSeries,
+    barWidth: normalizedInput.barWidth,
+    barGap: normalizedInput.barGap,
+    barBackground: normalizedInput.barBackground,
+    createRenderItem: createCylinderRenderItem,
+    resolveColorMap: resolveCylinderColors
+  });
   var customBarSeries = buildCustomBarSeries({
     rawData: normalizedInput.rawData,
     normalizedSeries: normalizedInput.normalizedSeries,
@@ -1054,13 +1323,18 @@ function createCylinderBarLineOption(normalizedInput) {
     return flatSeries[index];
   });
   return _objectSpread2(_objectSpread2({}, flatOption), {}, {
-    series: series
+    series: [].concat(_toConsumableArray(series), _toConsumableArray(backgroundSeries))
   });
 }
 
 var DEFAULT_VARIANT = 'flat';
 var DEFAULT_X_AXIS_SCROLL_VISIBLE_COUNT = 8;
 var DEFAULT_X_AXIS_SCROLL_GRID_BOTTOM = 56;
+var DEFAULT_BAR_BACKGROUND = {
+  show: false,
+  colors: [],
+  opacity: 1
+};
 var BAR_LINE_PUBLIC_VARIANTS = ['flat', 'cylinder', 'cube'];
 
 // 公开 variant 能力在此处收口：只允许 flat / cylinder / cube。
@@ -1144,6 +1418,21 @@ function normalizeXAxisScrollConfig() {
   };
 }
 
+/**
+ * 归一化柱形背景配置。
+ * 这里统一收敛开关、颜色数量和透明度范围，避免变体层重复兜底。
+ */
+function normalizeBarBackgroundConfig() {
+  var barBackground = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  var config = barBackground && _typeof(barBackground) === 'object' ? barBackground : {};
+  var opacity = Number(config.opacity);
+  return _objectSpread2(_objectSpread2({}, DEFAULT_BAR_BACKGROUND), {}, {
+    show: config.show === true,
+    colors: Array.isArray(config.colors) ? config.colors.filter(Boolean).slice(0, 3) : [],
+    opacity: Number.isFinite(opacity) ? Math.max(0, Math.min(1, opacity)) : 1
+  });
+}
+
 /**
  * 根据横轴类目数量生成 ECharts dataZoom。
  * 默认从末尾向前取 `visibleCount` 个类目，满足“最新数据优先展示”的看板诉求。
@@ -1214,6 +1503,7 @@ function buildBarLineOption() {
     variant = _ref$variant === void 0 ? 'flat' : _ref$variant,
     barWidth = _ref.barWidth,
     barGap = _ref.barGap,
+    barBackground = _ref.barBackground,
     xAxisScroll = _ref.xAxisScroll,
     customOption = _ref.customOption;
   var normalizedInput = normalizeBarLineInput({
@@ -1225,10 +1515,12 @@ function buildBarLineOption() {
   var presetOption = getBarLinePreset(preset);
   var resolvedVariant = resolveVariantName(variant);
   var createVariantOption = variantFactory[resolvedVariant] || variantFactory[DEFAULT_VARIANT];
+  var normalizedBarBackground = normalizeBarBackgroundConfig(barBackground);
   var variantOption = createVariantOption(_objectSpread2(_objectSpread2({}, normalizedInput), {}, {
     includeXAxis: false,
     barWidth: barWidth,
-    barGap: barGap
+    barGap: barGap,
+    barBackground: normalizedBarBackground
   }));
   var xAxisScrollOption = createXAxisScrollOption(normalizedInput.categories, xAxisScroll);
   return mergeChartOption(mergeChartOption(mergeChartOption(baseOption, presetOption, variantOption), xAxisScrollOption), customOption);
@@ -1330,6 +1622,17 @@ var script = {
       type: [Number, String],
       "default": 8
     },
+    /**
+     * 柱形背景配置。
+     * 仅对支持背景柱的柱系列生效，builder 会负责归一化 `show/colors/opacity`
+     * 并交由具体变体决定最终渲染策略。
+     */
+    barBackground: {
+      type: Object,
+      "default": function _default() {
+        return {};
+      }
+    },
     /**
      * 额外透传给 ECharts option 的自定义配置。
      * 会在 base / preset / variant option 合并完成后再覆盖。
@@ -1404,6 +1707,7 @@ var script = {
         preset: this.preset,
         barWidth: this.barWidth,
         barGap: this.barGap,
+        barBackground: this.barBackground,
         xAxisScroll: this.xAxisScroll,
         customOption: this.customOption
       });
@@ -1411,7 +1715,7 @@ var script = {
   }
 };
 
-var css_248z = "\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n";
+var css_248z = "\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n";
 styleInject(css_248z);
 
 /* script */
@@ -1445,7 +1749,7 @@ __vue_render__._withStripped = true;
 /* style */
 var __vue_inject_styles__ = undefined;
 /* scoped */
-var __vue_scope_id__ = "data-v-0c9a6292";
+var __vue_scope_id__ = "data-v-4e3be95d";
 /* module identifier */
 var __vue_module_identifier__ = undefined;
 /* functional template */

package/es/index.js

@@ -1,6 +1,6 @@
 import '../theme-chalk/index.css';
 import { w as withInstall, B as BaseChart } from './with-install-e405b463.js';
-import { B as BarLineChart } from './index-d01ce220.js';
+import { B as BarLineChart } from './index-914fbae3.js';
 import { P as PieChart } from './index-78b6b881.js';
 import { R as RadarChart } from './index-788e473f.js';
 import 'echarts/core';

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

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 require('../../theme-chalk/index.css');
-var index = require('../index-cc49894a.js');
+var index = require('../index-3d9f6fe7.js');
 var withInstall = require('../with-install-4304a8ea.js');
 require('echarts/core');
 require('echarts/charts');

package/lib/{index-cc49894a.js → index-3d9f6fe7.js}

@@ -149,6 +149,19 @@ function resolveSeriesColor$1(item, index) {
   }
   return colors.DEFAULT_COLORS[index % colors.DEFAULT_COLORS.length];
 }
+function collectBarSeries(normalizedSeries) {
+  return normalizedSeries.map(function (item, originalIndex) {
+    return colors._objectSpread2(colors._objectSpread2({}, item), {}, {
+      originalIndex: originalIndex
+    });
+  }).filter(function (item) {
+    return item.kind === 'bar';
+  }).map(function (item, barSeriesIndex) {
+    return colors._objectSpread2(colors._objectSpread2({}, item), {}, {
+      barSeriesIndex: barSeriesIndex
+    });
+  });
+}
 
 /**
  * 归一化颜色入参。
@@ -499,6 +512,53 @@ function createBarLayout(barSeries, barWidth, barGap) {
     barGap: resolvedBarGap
   };
 }
+function pickBackgroundSlotSeries(barSeries) {
+  var renderedStacks = new Set();
+  return barSeries.filter(function (item) {
+    if (!item.stack) {
+      return true;
+    }
+    if (renderedStacks.has(item.stack)) {
+      return false;
+    }
+    renderedStacks.add(item.stack);
+    return true;
+  });
+}
+function createBackgroundSeriesData(rawData) {
+  return rawData.map(function (row, rowIndex) {
+    return {
+      value: [rowIndex]
+    };
+  });
+}
+function resolveBackgroundFaceAlpha(key, opacity) {
+  var alphaMap = {
+    left: 0.82,
+    right: 1,
+    top: 1.8,
+    middle: 0.82,
+    bottom: 1.28,
+    legend: 1
+  };
+  var ratio = alphaMap[key] || 1;
+  return Math.max(0, Math.min(1, opacity * ratio));
+}
+function applyBackgroundFaceAlphaToColorMap(colorMap, opacity) {
+  return Object.keys(colorMap || {}).reduce(function (result, key) {
+    result[key] = applyAlphaToColor(colorMap[key], resolveBackgroundFaceAlpha(key, opacity));
+    return result;
+  }, {});
+}
+function normalizeBackgroundColors(barBackground, item) {
+  if (Array.isArray(barBackground && barBackground.colors) && barBackground.colors.length > 0) {
+    return barBackground.colors;
+  }
+  if (Array.isArray(item && item.colors) && item.colors.length > 0) {
+    return item.colors;
+  }
+  return undefined;
+}
 
 /**
  * 创建堆叠累加器。
@@ -627,13 +687,7 @@ function buildCustomBarSeries(_ref) {
     barGap = _ref.barGap,
     createRenderItem = _ref.createRenderItem,
     resolveColorMap = _ref.resolveColorMap;
-  var barSeries = normalizedSeries.map(function (item, originalIndex) {
-    return colors._objectSpread2(colors._objectSpread2({}, item), {}, {
-      originalIndex: originalIndex
-    });
-  }).filter(function (item) {
-    return item.kind === 'bar';
-  });
+  var barSeries = collectBarSeries(normalizedSeries);
   var layout = createBarLayout(barSeries, barWidth, barGap);
   var barSeriesWithData = buildBarSeriesData(rawData, barSeries);
   return barSeriesWithData.map(function (item, index) {
@@ -662,6 +716,57 @@ function buildCustomBarSeries(_ref) {
     };
   });
 }
+function buildBackgroundCustomBarSeries(_ref2) {
+  var rawData = _ref2.rawData,
+    normalizedSeries = _ref2.normalizedSeries,
+    barWidth = _ref2.barWidth,
+    barGap = _ref2.barGap,
+    _ref2$barBackground = _ref2.barBackground,
+    barBackground = _ref2$barBackground === void 0 ? {} : _ref2$barBackground,
+    createRenderItem = _ref2.createRenderItem,
+    resolveColorMap = _ref2.resolveColorMap;
+  if (!barBackground.show) {
+    return [];
+  }
+  var barSeries = collectBarSeries(normalizedSeries);
+  if (!barSeries.length) {
+    return [];
+  }
+  var layout = createBarLayout(barSeries, barWidth, barGap);
+  var backgroundSeriesData = createBackgroundSeriesData(rawData);
+  return pickBackgroundSlotSeries(barSeries).map(function (item) {
+    var slotKey = item.stack || "__slot_".concat(item.barSeriesIndex);
+    var slotIndex = layout.slotMap[slotKey];
+    var fallbackColor = resolveSeriesColor$1(item, item.originalIndex);
+    var palette = normalizeBackgroundColors(barBackground, item);
+    var baseColorMap = resolveColorMap ? resolveColorMap(palette, fallbackColor) : {
+      legend: fallbackColor
+    };
+    var backgroundColorMap = applyBackgroundFaceAlphaToColorMap(baseColorMap, barBackground.opacity);
+    return {
+      name: item.name,
+      type: 'custom',
+      stack: item.stack,
+      yAxisIndex: item.yAxisIndex || 0,
+      isBackground: true,
+      silent: true,
+      tooltip: {
+        show: false
+      },
+      renderItem: createRenderItem(layout, slotIndex, backgroundColorMap, colors._objectSpread2(colors._objectSpread2({}, item), {}, {
+        isBackground: true
+      })),
+      encode: {
+        x: 0
+      },
+      itemStyle: {
+        color: backgroundColorMap.legend || applyAlphaToColor(fallbackColor, barBackground.opacity)
+      },
+      data: backgroundSeriesData,
+      z: 0
+    };
+  });
+}
 
 /**
  * 归一化 flat 模式下的 `barGap`。
@@ -725,6 +830,27 @@ function resolveFlatBarColors(item, index) {
     end: darkenColor(fallbackColor, 0.12)
   };
 }
+function resolveFlatBackgroundColors(item, index, barBackground) {
+  var paletteSource = Array.isArray(barBackground.colors) && barBackground.colors.length > 0 ? {
+    colors: barBackground.colors
+  } : item;
+  var colorMap = resolveFlatBarColors(paletteSource, index);
+  return {
+    start: applyAlphaToColor(colorMap.start, barBackground.opacity),
+    middle: applyAlphaToColor(colorMap.middle, barBackground.opacity),
+    end: applyAlphaToColor(colorMap.end, barBackground.opacity)
+  };
+}
+function shouldEnableBackground(item, renderedStacks) {
+  if (!item.stack) {
+    return true;
+  }
+  if (renderedStacks.has(item.stack)) {
+    return false;
+  }
+  renderedStacks.add(item.stack);
+  return true;
+}
 
 /**
  * 创建柱体纵向渐变。
@@ -756,9 +882,12 @@ function createFlatBarLineSeries(_ref) {
   var normalizedSeries = _ref.normalizedSeries,
     rawData = _ref.rawData,
     barWidth = _ref.barWidth,
-    barGap = _ref.barGap;
+    barGap = _ref.barGap,
+    _ref$barBackground = _ref.barBackground,
+    barBackground = _ref$barBackground === void 0 ? {} : _ref$barBackground;
   var resolvedBarWidth = Number.isFinite(Number(barWidth)) ? Number(barWidth) : 18;
   var resolvedBarGap = toBarGapValue(barGap);
+  var renderedStacks = new Set();
   return normalizedSeries.map(function (item, index) {
     var isLine = item.kind === 'line';
     var color = resolveSeriesColor(item, index);
@@ -779,11 +908,18 @@ function createFlatBarLineSeries(_ref) {
         yAxisIndex: item.yAxisIndex
       });
     }
+    var showBackground = barBackground.show && shouldEnableBackground(item, renderedStacks);
+    var backgroundColors = resolveFlatBackgroundColors(item, index, barBackground);
     return colors._objectSpread2(colors._objectSpread2({}, baseSeries), {}, {
       stack: item.stack,
       barWidth: resolvedBarWidth,
-      barGap: resolvedBarGap
-    });
+      barGap: resolvedBarGap,
+      showBackground: showBackground
+    }, showBackground ? {
+      backgroundStyle: {
+        color: createBarGradient(backgroundColors)
+      }
+    } : {});
   });
 }
 
@@ -847,9 +983,63 @@ function createFaceGradient(x0, y0, x1, y1, startColor, endColor) {
  * 创建方柱渲染器。
  * 参考案例使用三块 polygon 拼接成立方体，而不是“正面 rect + 顶面/侧面”。
  */
-function createCubeRenderItem(layout, slotIndex, colorMap) {
+function createCubeRenderItem(layout, slotIndex, colorMap, seriesItem) {
   return function renderItem(params, api) {
     var rowIndex = api.value(0);
+    var offsetX = getBarOffset(layout, slotIndex);
+    var centerPoint = api.coord([rowIndex, 0]);
+    var centerX = centerPoint[0] + offsetX;
+    var halfWidth = layout.barWidth / 2;
+    var offsetY = Math.tan(Math.PI / 9) * halfWidth;
+    var leftFaceGradient = createFaceGradient(0, 0, 0, 1, colorMap.left, colorMap.left);
+    var rightFaceGradient = createFaceGradient(0, 0, 0, 1, colorMap.right, colorMap.right);
+    var topFaceGradient = createFaceGradient(0, 0, 1, 0, colorMap.top, colorMap.top);
+    if (seriesItem && seriesItem.isBackground === true) {
+      var coordSys = params.coordSys || {};
+      var clipX = coordSys.x || 0;
+      var _topY = coordSys.y || 0;
+      var width = coordSys.width || 0;
+      var _baseY = _topY + (coordSys.height || 0);
+      var _topSurfaceY = _topY + Math.abs(offsetY - 1);
+      return {
+        type: 'group',
+        clipPath: {
+          type: 'rect',
+          shape: {
+            x: clipX,
+            y: _topY,
+            width: width,
+            height: coordSys.height || 0
+          }
+        },
+        children: [{
+          type: 'polygon',
+          shape: {
+            points: [[centerX, _topSurfaceY + offsetY - 1], [centerX - halfWidth, _topSurfaceY], [centerX - halfWidth, _baseY - offsetY], [centerX, _baseY - 1]]
+          },
+          style: {
+            fill: leftFaceGradient
+          }
+        }, {
+          type: 'polygon',
+          shape: {
+            points: [[centerX, _topSurfaceY + offsetY - 1], [centerX + halfWidth, _topSurfaceY], [centerX + halfWidth, _baseY - offsetY], [centerX, _baseY - 1]]
+          },
+          style: {
+            fill: rightFaceGradient
+          }
+        }, {
+          type: 'polygon',
+          shape: {
+            points: [[centerX, _topSurfaceY + offsetY - 1], [centerX + halfWidth, _topSurfaceY], [centerX, _topSurfaceY - offsetY + 1], [centerX - halfWidth, _topSurfaceY]]
+          },
+          style: {
+            fill: topFaceGradient
+          },
+          z2: 2
+        }]
+      };
+    }
     var endValue = api.value(1);
     var baseValue = api.value(2);
     var rawValue = api.value(3);
@@ -860,20 +1050,13 @@ function createCubeRenderItem(layout, slotIndex, colorMap) {
     }
     var endPoint = api.coord([rowIndex, endValue]);
     var basePoint = api.coord([rowIndex, baseValue]);
-    var offsetX = getBarOffset(layout, slotIndex);
-    var centerX = endPoint[0] + offsetX;
     var topY = endPoint[1];
     var baseY = basePoint[1];
-    var halfWidth = layout.barWidth / 2;
-    var offsetY = Math.tan(Math.PI / 9) * halfWidth;
     var isPositive = rawValue >= 0;
     var connectorOverlap = stackStart ? 0 : Math.max(2, Math.round(offsetY));
     var connectorCapOffset = stackEnd ? 0 : Math.min(2, offsetY * 0.45);
     var connectBaseY = isPositive ? baseY + connectorOverlap : baseY - connectorOverlap;
     var topSurfaceY = topY + connectorCapOffset;
-    var leftFaceGradient = createFaceGradient(0, 0, 0, 1, colorMap.left, colorMap.left);
-    var rightFaceGradient = createFaceGradient(0, 0, 0, 1, colorMap.right, colorMap.right);
-    var topFaceGradient = createFaceGradient(0, 0, 1, 0, colorMap.top, colorMap.top);
     return {
       type: 'group',
       children: [{
@@ -919,6 +1102,15 @@ function createCubeRenderItem(layout, slotIndex, colorMap) {
 function createCubeBarLineOption(normalizedInput) {
   var flatOption = createFlatBarLineOption(normalizedInput);
   var flatSeries = createFlatBarLineSeries(normalizedInput);
+  var backgroundSeries = buildBackgroundCustomBarSeries({
+    rawData: normalizedInput.rawData,
+    normalizedSeries: normalizedInput.normalizedSeries,
+    barWidth: normalizedInput.barWidth,
+    barGap: normalizedInput.barGap,
+    barBackground: normalizedInput.barBackground,
+    createRenderItem: createCubeRenderItem,
+    resolveColorMap: resolveCubeColors
+  });
   var customBarSeries = buildCustomBarSeries({
     rawData: normalizedInput.rawData,
     normalizedSeries: normalizedInput.normalizedSeries,
@@ -937,7 +1129,7 @@ function createCubeBarLineOption(normalizedInput) {
     return flatSeries[index];
   });
   return colors._objectSpread2(colors._objectSpread2({}, flatOption), {}, {
-    series: series
+    series: [].concat(colors._toConsumableArray(series), colors._toConsumableArray(backgroundSeries))
   });
 }
 
@@ -961,6 +1153,20 @@ function createEllipsePolygon(cx, cy, rx, ry) {
   }
   return polygonPoints;
 }
+function createEllipseArcPoints(cx, cy, rx, ry, startAngle, endAngle) {
+  var points = arguments.length > 6 && arguments[6] !== undefined ? arguments[6] : 12;
+  var arcPoints = [];
+  for (var index = 0; index <= points; index += 1) {
+    var angle = startAngle + (endAngle - startAngle) * index / points;
+    arcPoints.push([cx + Math.cos(angle) * rx, cy + Math.sin(angle) * ry]);
+  }
+  return arcPoints;
+}
+function createCylinderSidePolygon(cx, topCy, bottomCy, rx, ry) {
+  var topLowerArc = createEllipseArcPoints(cx, topCy, rx, ry, Math.PI, 0);
+  var bottomUpperArc = createEllipseArcPoints(cx, bottomCy, rx, ry, 0, -Math.PI);
+  return [].concat(colors._toConsumableArray(topLowerArc), colors._toConsumableArray(bottomUpperArc));
+}
 
 /**
  * 创建圆柱渲染器。
@@ -969,9 +1175,76 @@ function createEllipsePolygon(cx, cy, rx, ry) {
  * 2. 主体用纵向渐变矩形模拟曲面；
  * 3. 堆叠连接处保留底片，但不绘制深色描边和弧线，避免形成脏色带。
  */
-function createCylinderRenderItem(layout, slotIndex, colorMap) {
+function createCylinderRenderItem(layout, slotIndex, colorMap, seriesItem) {
   return function renderItem(params, api) {
     var rowIndex = api.value(0);
+    var offsetX = getBarOffset(layout, slotIndex);
+    var centerPoint = api.coord([rowIndex, 0]);
+    var centerX = centerPoint[0] + offsetX;
+    var radiusX = layout.barWidth / 2;
+    var radiusY = radiusX * 0.4;
+    var createSideGradient = function createSideGradient(topColor, middleColor, bottomColor) {
+      var opacity = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : CYLINDER_SIDE_OPACITY;
+      return new echarts.graphic.LinearGradient(0, 0, 0, 1, [{
+        offset: 0,
+        color: opacity === null ? topColor : applyAlphaToColor(topColor, opacity)
+      }, {
+        offset: 0.55,
+        color: opacity === null ? middleColor : applyAlphaToColor(middleColor, opacity)
+      }, {
+        offset: 1,
+        color: opacity === null ? bottomColor : applyAlphaToColor(bottomColor, opacity)
+      }]);
+    };
+    if (seriesItem && seriesItem.isBackground === true) {
+      var coordSys = params.coordSys || {};
+      var clipX = coordSys.x || 0;
+      var topY = coordSys.y || 0;
+      var width = coordSys.width || 0;
+      var height = coordSys.height || 0;
+      var _topEllipseY = topY + radiusY;
+      var bottomEllipseY = topY + height - radiusY;
+      return {
+        type: 'group',
+        clipPath: {
+          type: 'rect',
+          shape: {
+            x: clipX,
+            y: topY,
+            width: width,
+            height: height
+          }
+        },
+        children: [{
+          type: 'polygon',
+          shape: {
+            points: createEllipsePolygon(centerX, bottomEllipseY, radiusX, radiusY)
+          },
+          style: {
+            fill: colorMap.bottom
+          },
+          z: 0
+        }, {
+          type: 'polygon',
+          shape: {
+            points: createCylinderSidePolygon(centerX, _topEllipseY, bottomEllipseY, radiusX, radiusY)
+          },
+          style: {
+            fill: createSideGradient(colorMap.middle, colorMap.middle, colorMap.bottom, null)
+          },
+          z: 1
+        }, {
+          type: 'polygon',
+          shape: {
+            points: createEllipsePolygon(centerX, _topEllipseY, radiusX, radiusY)
+          },
+          style: {
+            fill: colorMap.top
+          },
+          z2: 2
+        }]
+      };
+    }
     var endValue = api.value(1);
     var baseValue = api.value(2);
     var rawValue = api.value(3);
@@ -982,10 +1255,6 @@ function createCylinderRenderItem(layout, slotIndex, colorMap) {
     }
     var endPoint = api.coord([rowIndex, endValue]);
     var basePoint = api.coord([rowIndex, baseValue]);
-    var offsetX = getBarOffset(layout, slotIndex);
-    var centerX = endPoint[0] + offsetX;
-    var radiusX = layout.barWidth / 2;
-    var radiusY = radiusX * 0.4;
     var isPositive = rawValue >= 0;
     var barHeight = Math.abs(endPoint[1] - basePoint[1]);
     var visibleEllipseY = endPoint[1];
@@ -1000,16 +1269,7 @@ function createCylinderRenderItem(layout, slotIndex, colorMap) {
     var gradientTopColor = isPositive ? colorMap.middle : darkenColor(colorMap.bottom, 0.05);
     var gradientMiddleColor = colorMap.middle;
     var gradientBottomColor = isPositive ? colorMap.bottom : colorMap.middle;
-    var sideGradient = new echarts.graphic.LinearGradient(0, 0, 0, 1, [{
-      offset: 0,
-      color: applyAlphaToColor(gradientTopColor, CYLINDER_SIDE_OPACITY)
-    }, {
-      offset: 0.55,
-      color: applyAlphaToColor(gradientMiddleColor, CYLINDER_SIDE_OPACITY)
-    }, {
-      offset: 1,
-      color: applyAlphaToColor(gradientBottomColor, CYLINDER_SIDE_OPACITY)
-    }]);
+    var sideGradient = createSideGradient(gradientTopColor, gradientMiddleColor, gradientBottomColor);
     return {
       type: 'group',
       children: [].concat(colors._toConsumableArray(showBottomPlate ? [{
@@ -1056,6 +1316,15 @@ function createCylinderRenderItem(layout, slotIndex, colorMap) {
 function createCylinderBarLineOption(normalizedInput) {
   var flatOption = createFlatBarLineOption(normalizedInput);
   var flatSeries = createFlatBarLineSeries(normalizedInput);
+  var backgroundSeries = buildBackgroundCustomBarSeries({
+    rawData: normalizedInput.rawData,
+    normalizedSeries: normalizedInput.normalizedSeries,
+    barWidth: normalizedInput.barWidth,
+    barGap: normalizedInput.barGap,
+    barBackground: normalizedInput.barBackground,
+    createRenderItem: createCylinderRenderItem,
+    resolveColorMap: resolveCylinderColors
+  });
   var customBarSeries = buildCustomBarSeries({
     rawData: normalizedInput.rawData,
     normalizedSeries: normalizedInput.normalizedSeries,
@@ -1074,13 +1343,18 @@ function createCylinderBarLineOption(normalizedInput) {
     return flatSeries[index];
   });
   return colors._objectSpread2(colors._objectSpread2({}, flatOption), {}, {
-    series: series
+    series: [].concat(colors._toConsumableArray(series), colors._toConsumableArray(backgroundSeries))
   });
 }
 
 var DEFAULT_VARIANT = 'flat';
 var DEFAULT_X_AXIS_SCROLL_VISIBLE_COUNT = 8;
 var DEFAULT_X_AXIS_SCROLL_GRID_BOTTOM = 56;
+var DEFAULT_BAR_BACKGROUND = {
+  show: false,
+  colors: [],
+  opacity: 1
+};
 var BAR_LINE_PUBLIC_VARIANTS = ['flat', 'cylinder', 'cube'];
 
 // 公开 variant 能力在此处收口：只允许 flat / cylinder / cube。
@@ -1164,6 +1438,21 @@ function normalizeXAxisScrollConfig() {
   };
 }
 
+/**
+ * 归一化柱形背景配置。
+ * 这里统一收敛开关、颜色数量和透明度范围，避免变体层重复兜底。
+ */
+function normalizeBarBackgroundConfig() {
+  var barBackground = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  var config = barBackground && colors._typeof(barBackground) === 'object' ? barBackground : {};
+  var opacity = Number(config.opacity);
+  return colors._objectSpread2(colors._objectSpread2({}, DEFAULT_BAR_BACKGROUND), {}, {
+    show: config.show === true,
+    colors: Array.isArray(config.colors) ? config.colors.filter(Boolean).slice(0, 3) : [],
+    opacity: Number.isFinite(opacity) ? Math.max(0, Math.min(1, opacity)) : 1
+  });
+}
+
 /**
  * 根据横轴类目数量生成 ECharts dataZoom。
  * 默认从末尾向前取 `visibleCount` 个类目，满足“最新数据优先展示”的看板诉求。
@@ -1234,6 +1523,7 @@ function buildBarLineOption() {
     variant = _ref$variant === void 0 ? 'flat' : _ref$variant,
     barWidth = _ref.barWidth,
     barGap = _ref.barGap,
+    barBackground = _ref.barBackground,
     xAxisScroll = _ref.xAxisScroll,
     customOption = _ref.customOption;
   var normalizedInput = normalizeBarLineInput({
@@ -1245,10 +1535,12 @@ function buildBarLineOption() {
   var presetOption = getBarLinePreset(preset);
   var resolvedVariant = resolveVariantName(variant);
   var createVariantOption = variantFactory[resolvedVariant] || variantFactory[DEFAULT_VARIANT];
+  var normalizedBarBackground = normalizeBarBackgroundConfig(barBackground);
   var variantOption = createVariantOption(colors._objectSpread2(colors._objectSpread2({}, normalizedInput), {}, {
     includeXAxis: false,
     barWidth: barWidth,
-    barGap: barGap
+    barGap: barGap,
+    barBackground: normalizedBarBackground
   }));
   var xAxisScrollOption = createXAxisScrollOption(normalizedInput.categories, xAxisScroll);
   return colors.mergeChartOption(colors.mergeChartOption(colors.mergeChartOption(baseOption, presetOption, variantOption), xAxisScrollOption), customOption);
@@ -1350,6 +1642,17 @@ var script = {
       type: [Number, String],
       "default": 8
     },
+    /**
+     * 柱形背景配置。
+     * 仅对支持背景柱的柱系列生效，builder 会负责归一化 `show/colors/opacity`
+     * 并交由具体变体决定最终渲染策略。
+     */
+    barBackground: {
+      type: Object,
+      "default": function _default() {
+        return {};
+      }
+    },
     /**
      * 额外透传给 ECharts option 的自定义配置。
      * 会在 base / preset / variant option 合并完成后再覆盖。
@@ -1424,6 +1727,7 @@ var script = {
         preset: this.preset,
         barWidth: this.barWidth,
         barGap: this.barGap,
+        barBackground: this.barBackground,
         xAxisScroll: this.xAxisScroll,
         customOption: this.customOption
       });
@@ -1431,7 +1735,7 @@ var script = {
   }
 };
 
-var css_248z = "\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n";
+var css_248z = "\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n";
 withInstall.styleInject(css_248z);
 
 /* script */
@@ -1465,7 +1769,7 @@ __vue_render__._withStripped = true;
 /* style */
 var __vue_inject_styles__ = undefined;
 /* scoped */
-var __vue_scope_id__ = "data-v-0c9a6292";
+var __vue_scope_id__ = "data-v-4e3be95d";
 /* module identifier */
 var __vue_module_identifier__ = undefined;
 /* functional template */

package/lib/index.js

@@ -4,7 +4,7 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 require('../theme-chalk/index.css');
 var withInstall = require('./with-install-4304a8ea.js');
-var index$1 = require('./index-cc49894a.js');
+var index$1 = require('./index-3d9f6fe7.js');
 var index$2 = require('./index-a0ecafa1.js');
 var index$3 = require('./index-6039f724.js');
 require('echarts/core');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xq-labs/data-ui-v2",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "main": "lib/index.js",
   "module": "es/index.js",
   "style": "theme-chalk/index.css",