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

package/docs/api/overview.md

@@ -119,9 +119,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 +133,7 @@ import '@xq-labs/data-ui-v2/theme-chalk/index.css'
 
 ### 6.4 常见场景
 
-1. 你已经有现成的 ECharts option，只需要统一 loading、空态和实例生命周期。
+1. 你已经有现成的 ECharts option，只需要统一遮罩式 loading、空态和实例生命周期。
 2. 你在业务项目里做一个内部定制图表，但仍希望复用统一底层壳。
 
 示例：
@@ -143,11 +143,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
@@ -169,7 +200,8 @@ import '@xq-labs/data-ui-v2/theme-chalk/index.css'
 | `barWidth` | `Number` | `18` | 柱体宽度 |
 | `barGap` | `Number \| String` | `8` | 柱间距 |
 | `customOption` | `Object` | `{}` | 对 ECharts option 的补充覆盖 |
-| `loading` | `Boolean` | `false` | 是否显示 loading |
+| `loading` | `Boolean` | `false` | 是否显示统一遮罩式 loading（非 ECharts 原生 loading） |
+| `stateConfig` | `Object` | `{}` | 统一状态配置，原样透传给 `BaseChart` |
 | `height` | `String \| Number` | `320` | 容器高度 |
 
 ### 7.3 BarLineChart 数据格式
@@ -336,7 +368,8 @@ colors: ['#A8BEFA', '#6B98F8', '#3EE8FE']
 | `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 数据格式
@@ -496,6 +529,7 @@ const labelOptions = {
 - `dimension="2d"` 时，不需要安装 `echarts-gl`。
 - `dimension="3d"` 时，需要安装 `echarts-gl`。
 - 3D 模式会在运行时按需加载 `echarts-gl`。
+- 若 3D 运行时加载失败，组件会优先显示内部错误文案，但仍保留 `stateConfig.empty.image` 与 `stateConfig.loading.text`。
 
 ### 8.8 常见场景
 
@@ -532,6 +566,7 @@ const labelOptions = {
     series,
     variant: 'cylinder',
     preset: 'compare',
+    stateConfig,
     customOption
   }"
 />
@@ -550,6 +585,7 @@ const labelOptions = {
     maxHeight: 80,
     showLabelLine: true,
     labelOptions,
+    stateConfig,
     customOption
   }"
 />

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

@@ -27,7 +27,8 @@ Playground 中 `BarLineChart` 按分组路由组织：
     preset,
     barWidth,
     barGap,
-    customOption
+    customOption,
+    stateConfig
   }"
 />
 ```
@@ -41,17 +42,33 @@ Playground 中 `BarLineChart` 按分组路由组织：
 - `preset`：展示预设。
 - `barWidth`、`barGap`：柱体宽度与间距。
 - `customOption`：ECharts 展示细节覆盖。
+- `stateConfig`：统一收拢空态文案、空态图和 loading 文案。
+
+推荐结构：
+
+```js
+const stateConfig = {
+  empty: {
+    text: '暂无柱线图数据',
+    image: 'https://example.com/bar-empty.png'
+  },
+  loading: {
+    text: '柱线图加载中...'
+  }
+}
+```
 
 ## 3. 如何自定义（推荐顺序）
 
 1. **优先 `series` 表达业务语义**：先确定字段、柱线类型、双轴和堆叠关系。
 2. **用 `series.colors` 控制系列配色**：把业务色板放在系列层。
-3. **`customOption` 补充细节**：用于 tooltip、legend、grid、坐标轴样式等展示项。
+3. **`stateConfig` 收拢状态文案**：空态图、空态文案、loading 文案统一从这里传。
+4. **`customOption` 补充细节**：用于 tooltip、legend、grid、坐标轴样式等展示项。
 
 不建议用 `customOption` 直接整体替换关键业务结构。
 
 ## 4. 可执行验收要点
 
 - 页面分组名称与路由一致：基础用法、圆柱样式、方柱样式、进阶配置、customOption 与自定义、实验室。
-- 文档示例包含 `series.colors` 与 `customOption`。
-- 文档明确实验室边界与推荐自定义顺序。
+- 文档示例包含 `series.colors`、`stateConfig` 与 `customOption`。
+- 文档明确实验室边界与推荐自定义顺序。

package/docs/examples/pie-chart.md

@@ -29,7 +29,8 @@ Playground 中 `PieChart` 采用分组路由组织，按能力查阅：
     maxHeight,
     hideZeroValueSlices,
     labelOptions,
-    customOption
+    customOption,
+    stateConfig
   }"
 />
 ```
@@ -44,6 +45,21 @@ Playground 中 `PieChart` 采用分组路由组织，按能力查阅：
 - `hideZeroValueSlices`：3D 下是否隐藏 0 值扇区。
 - `labelOptions`：标签与引导线细节（格式、线长、颜色等）。
 - `customOption`：ECharts 细节覆盖（标题、提示、图例等）。
+- `stateConfig`：统一收拢空态文案、空态图和 loading 文案。
+
+推荐结构：
+
+```js
+const stateConfig = {
+  empty: {
+    text: '暂无占比数据',
+    image: 'https://example.com/pie-empty.png'
+  },
+  loading: {
+    text: '饼图加载中...'
+  }
+}
+```
 
 ## 2.1 3D 依赖说明
 
@@ -61,12 +77,23 @@ npm install echarts-gl
 
 1. **优先公开 props**：先用 `variant`、`dimension`、`preset`、高度参数表达业务语义。
 2. **其次 `labelOptions`**：标签文案、引导线样式优先在这里完成。
-3. **最后 `customOption`**：仅用于补充 ECharts 展示细节。
+3. **状态文案统一交给 `stateConfig`**：空态图、空态文案、loading 文案不要分散到多个字段。
+4. **最后 `customOption`**：仅用于补充 ECharts 展示细节。
 
 不建议业务侧直接拼接或重写内部 `series`，避免覆盖组件内置能力与升级兼容性。
 
+## 3.1 3D 运行时失败的空态优先级
+
+当 `dimension="3d"` 且业务未安装 `echarts-gl` 时：
+
+1. `PieChart` 会优先显示组件内部错误文案。
+2. `stateConfig.empty.image` 仍然生效。
+3. `stateConfig.loading.text` 仍然生效。
+
+也就是说，业务可以继续自定义空态图，但不能覆盖这类运行时错误提示。
+
 ## 4. 可执行验收要点
 
 - 页面分组名称与路由一致：基础用法、2D 形态、3D 能力、标签与引导线、customOption 与自定义、实验室。
-- 文档示例包含 `hideZeroValueSlices` 与 `customOption`。
-- 文档明确实验室边界与推荐自定义顺序。
+- 文档示例包含 `hideZeroValueSlices`、`stateConfig` 与 `customOption`。
+- 文档明确实验室边界与推荐自定义顺序。

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

@@ -1,6 +1,6 @@
 import '../../theme-chalk/index.css';
-import { B as BarLineChart } from '../index-6128787e.js';
-import { w as withInstall } from '../with-install-befebea5.js';
+import { B as BarLineChart } from '../index-017ccf86.js';
+import { w as withInstall } from '../with-install-e405b463.js';
 import 'echarts/core';
 import 'echarts/charts';
 import 'echarts/components';

package/es/base-chart/index.js

@@ -1,5 +1,5 @@
 import '../../theme-chalk/index.css';
-import { w as withInstall, B as BaseChart } from '../with-install-befebea5.js';
+import { w as withInstall, B as BaseChart } from '../with-install-e405b463.js';
 import 'echarts/core';
 
 var BaseChartComponent = withInstall(BaseChart);

package/es/{index-6128787e.js → index-017ccf86.js}

@@ -3,7 +3,7 @@ import { graphic } from 'echarts/core';
 import { BarChart, LineChart, CustomChart } from 'echarts/charts';
 import { TooltipComponent, LegendComponent, GridComponent, TitleComponent } from 'echarts/components';
 import { CanvasRenderer } from 'echarts/renderers';
-import { B as BaseChart, s as styleInject, n as normalizeComponent } from './with-install-befebea5.js';
+import { B as BaseChart, s as styleInject, n as normalizeComponent } from './with-install-e405b463.js';
 import { _ as _objectSpread2, D as DEFAULT_COLORS, a as _toConsumableArray, m as mergeChartOption, i as isEmptyData } from './colors-ca059479.js';
 
 var DEFAULT_SERIES = {
@@ -1153,6 +1153,7 @@ function buildBarLineOption() {
 //
 //
 //
+//
 
 
 /**
@@ -1249,12 +1250,22 @@ var script = {
     },
     /**
      * 图表 loading 状态。
-     * 由 BaseChart 统一接管具体的 loading UI。
+     * 由 BaseChart 统一接管组件层遮罩式 loading UI。
      */
     loading: {
       type: Boolean,
       "default": false
     },
+    /**
+     * 统一状态展示配置。
+     * 组件层只负责原样透传给 BaseChart，不参与文案计算。
+     */
+    stateConfig: {
+      type: Object,
+      "default": function _default() {
+        return {};
+      }
+    },
     /**
      * 图表容器高度。
      * 支持数字像素值或原样透传的 CSS 高度字符串。
@@ -1291,7 +1302,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";
+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";
 styleInject(css_248z);
 
 /* script */
@@ -1306,6 +1317,7 @@ var __vue_render__ = function __vue_render__() {
       option: _vm.chartOption,
       loading: _vm.loading,
       empty: _vm.isEmpty,
+      "state-config": _vm.stateConfig,
       height: _vm.height
     },
     on: {
@@ -1324,7 +1336,7 @@ __vue_render__._withStripped = true;
 /* style */
 var __vue_inject_styles__ = undefined;
 /* scoped */
-var __vue_scope_id__ = "data-v-e33b855e";
+var __vue_scope_id__ = "data-v-1ad2414e";
 /* module identifier */
 var __vue_module_identifier__ = undefined;
 /* functional template */

package/es/{index-6af2ada7.js → index-d151eeca.js}

@@ -3,7 +3,7 @@ import * as echarts from 'echarts/core';
 import { PieChart as PieChart$1 } from 'echarts/charts';
 import { TooltipComponent, LegendComponent, GridComponent, TitleComponent, GraphicComponent } from 'echarts/components';
 import { CanvasRenderer } from 'echarts/renderers';
-import { B as BaseChart, s as styleInject, n as normalizeComponent } from './with-install-befebea5.js';
+import { B as BaseChart, s as styleInject, n as normalizeComponent } from './with-install-e405b463.js';
 
 /**
  * 将输入值转换为安全数值。
@@ -1096,12 +1096,22 @@ var script = {
     },
     /**
      * 图表 loading 状态。
-     * 由底层 BaseChart 统一负责 showLoading / hideLoading。
+     * 由底层 BaseChart 统一负责组件层遮罩式 loading UI。
      */
     loading: {
       type: Boolean,
       "default": false
     },
+    /**
+     * 统一状态展示配置。
+     * 负责收拢空态文案、空态图片与 loading 文案。
+     */
+    stateConfig: {
+      type: Object,
+      "default": function _default() {
+        return {};
+      }
+    },
     /**
      * 图表容器高度。
      * 支持数字（按 px 处理）或原样透传的字符串高度值。
@@ -1156,14 +1166,25 @@ var script = {
       return this.isEmpty || this.is3D && this.echartsGlStatus === 'failed';
     },
     /**
-     * 统一传给 BaseChart 的空态文案。
-     * 3D 缺少运行时时给出可执行的安装提示，普通空态仍保留默认文案。
+     * 统一归一化传给 BaseChart 的状态配置。
+     * 3D 运行时失败时，内部错误文案优先级最高，但仍保留业务自定义图片和 loading 文案。
      */
-    chartEmptyText: function chartEmptyText() {
+    resolvedStateConfig: function resolvedStateConfig() {
+      var stateConfig = this.stateConfig || {};
+      var emptyConfig = stateConfig.empty || {};
+      var loadingConfig = stateConfig.loading || {};
       if (this.is3D && this.echartsGlStatus === 'failed') {
-        return this.echartsGlErrorMessage || '使用 3D 饼图需要安装 echarts-gl';
+        return {
+          empty: _objectSpread2(_objectSpread2({}, emptyConfig), {}, {
+            text: this.echartsGlErrorMessage || '使用 3D 饼图需要安装 echarts-gl'
+          }),
+          loading: _objectSpread2({}, loadingConfig)
+        };
       }
-      return '暂无数据';
+      return {
+        empty: _objectSpread2({}, emptyConfig),
+        loading: _objectSpread2({}, loadingConfig)
+      };
     },
     /**
      * 将组件公开 props 统一汇总后交给 builder。
@@ -1281,7 +1302,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\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\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\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\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 */
@@ -1296,7 +1317,7 @@ var __vue_render__ = function __vue_render__() {
       option: _vm.chartOption,
       loading: _vm.chartLoading,
       empty: _vm.chartEmpty,
-      "empty-text": _vm.chartEmptyText,
+      "state-config": _vm.resolvedStateConfig,
       height: _vm.height
     },
     on: {
@@ -1313,7 +1334,7 @@ __vue_render__._withStripped = true;
 /* style */
 var __vue_inject_styles__ = undefined;
 /* scoped */
-var __vue_scope_id__ = "data-v-815905b6";
+var __vue_scope_id__ = "data-v-19bfc774";
 /* module identifier */
 var __vue_module_identifier__ = undefined;
 /* functional template */

package/es/index.js

@@ -1,7 +1,7 @@
 import '../theme-chalk/index.css';
-import { w as withInstall, B as BaseChart } from './with-install-befebea5.js';
-import { B as BarLineChart } from './index-6128787e.js';
-import { P as PieChart } from './index-6af2ada7.js';
+import { w as withInstall, B as BaseChart } from './with-install-e405b463.js';
+import { B as BarLineChart } from './index-017ccf86.js';
+import { P as PieChart } from './index-d151eeca.js';
 import 'echarts/core';
 import 'echarts/charts';
 import 'echarts/components';

package/es/pie-chart/index.js

@@ -1,6 +1,6 @@
 import '../../theme-chalk/index.css';
-import { P as PieChart } from '../index-6af2ada7.js';
-import { w as withInstall } from '../with-install-befebea5.js';
+import { P as PieChart } from '../index-d151eeca.js';
+import { w as withInstall } from '../with-install-e405b463.js';
 import '../colors-ca059479.js';
 import 'echarts/core';
 import 'echarts/charts';