@xq-labs/data-ui-v2 0.1.0

package/README.md

@@ -0,0 +1,141 @@
+# @xq-labs/data-ui-v2
+
+一套面向 Vue 2 项目的业务图表组件库，当前聚焦 `BaseChart`、`BarLineChart`、`PieChart` 三个公开组件，配套 `playground` 示例库、Rollup 发布构建和本地发版脚本。
+
+## 适用环境
+
+- Vue 2.6 / 2.7
+- Node 14
+- ECharts 5
+- ECharts GL 2（仅 3D 饼图需要）
+
+## 安装
+
+```bash
+npm install @xq-labs/data-ui-v2
+```
+
+组件库将 `vue` 与 `echarts` 作为外部依赖。
+
+只使用 2D 图表时不需要安装 echarts-gl；使用 3D 饼图时需要额外安装 echarts-gl。
+依赖包名为 `echarts-gl`，例如：
+
+```bash
+npm install echarts echarts-gl
+```
+
+## 整包注册
+
+```js
+import Vue from 'vue'
+import DataUI from '@xq-labs/data-ui-v2'
+
+Vue.use(DataUI)
+```
+
+整包入口会注册以下公开组件：
+
+- `BaseChart`
+- `BarLineChart`
+- `PieChart`
+
+## 按需引入
+
+```js
+import Vue from 'vue'
+import { BaseChart, BarLineChart, PieChart } from '@xq-labs/data-ui-v2'
+
+Vue.component(BaseChart.name, BaseChart)
+Vue.component(BarLineChart.name, BarLineChart)
+Vue.component(PieChart.name, PieChart)
+```
+
+如果你的构建链路需要直接引用发布子路径，也可以按 `lib` / `es` 产物接入：
+
+```js
+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'
+```
+
+## 样式说明
+
+- 发布产物默认通过入口文件关联组件样式
+- 如需显式引入样式，可单独引用 `@xq-labs/data-ui-v2/theme-chalk/index.css`
+
+```js
+import '@xq-labs/data-ui-v2/theme-chalk/index.css'
+```
+
+## 3D 饼图依赖说明
+
+只使用 2D 图表时不需要安装 echarts-gl。
+使用 3D 饼图时需要额外安装 echarts-gl，依赖包名为 `echarts-gl`，例如：
+
+```bash
+npm install echarts echarts-gl
+```
+
+当 `PieChart` 使用 `dimension="3d"` 时，组件会在运行时按需加载 `echarts-gl`。
+
+## 组件能力概览
+
+### BaseChart
+
+- 提供 ECharts 实例创建、销毁、尺寸监听与空态处理
+- 作为其他图表组件的通用基础壳
+
+### BarLineChart
+
+- 支持基础柱线组合
+- 支持圆柱、方柱、堆叠、双轴、颜色预设与自定义配置
+- 对齐 `playground` 中的正式案例与实验室案例
+
+### PieChart
+
+- 支持 2D 饼图、环图、南丁格尔图
+- 支持 3D 饼图、环图、按值映射高度等能力
+- 支持标签、引导线和 `customOption` 扩展
+
+## 示例与文档
+
+- API 总览：`docs/api/overview.md`
+- 可运行示例：`playground`
+- 示例说明：`docs/examples/pie-chart.md`
+- 示例说明：`docs/examples/bar-line-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`
+
+## 常用命令
+
+```bash
+# 启动 playground
+npm run serve
+
+# 单元测试
+npm run test:unit
+
+# 代码检查
+npm run lint
+
+# 代码格式检查
+npm run format:check
+
+# 构建发布产物
+npm run build
+
+# 检查 .release 发包内容
+npm run pack:check
+
+# 本地发版流程
+npm run release
+```
+
+## 发布说明
+
+- `vue-cli` 负责本地开发和单元测试
+- `rollup` 负责正式发布构建
+- 发布产物统一归档到 `.release/`
+- npm 包默认不包含 dist 目录下的 UMD 产物
+- `dist` 会继续构建，供独立制品分发或浏览器直引场景使用
+- 发版前要求工作区干净，发包成功后再执行 release commit、tag 和 push

package/docs/api/overview.md

@@ -0,0 +1,571 @@
+# 组件库 API 总览
+
+> 这份文档是当前组件库面向使用方的统一入口。  
+> 如果你只想先知道“怎么装、怎么注册、有哪些组件、每个组件怎么传参”，先看这里。
+
+> 发包后，如果你希望在本地离线查看文档，可以直接打开
+> `node_modules/@xq-labs/data-ui-v2/docs/api/overview.md`，
+> 示例说明位于 `node_modules/@xq-labs/data-ui-v2/docs/examples/`。
+
+---
+
+## 1. 安装
+
+组件库包名：
+
+```bash
+npm install @xq-labs/data-ui-v2
+```
+
+宿主项目需要自行安装 `vue` 与 `echarts`。
+
+如果你只使用 2D 图表，不需要安装 `echarts-gl`。  
+如果你要启用 `PieChart` 的 3D 能力，需要额外安装：
+
+```bash
+npm install echarts echarts-gl
+```
+
+---
+
+## 2. 注册方式
+
+### 2.1 整包注册
+
+适合后台项目快速接入：
+
+```js
+import Vue from 'vue'
+import DataUI from '@xq-labs/data-ui-v2'
+
+Vue.use(DataUI)
+```
+
+### 2.2 按需引入
+
+适合只使用少数组件的业务页面：
+
+```js
+import Vue from 'vue'
+import { BaseChart, BarLineChart, PieChart } from '@xq-labs/data-ui-v2'
+
+Vue.component(BaseChart.name, BaseChart)
+Vue.component(BarLineChart.name, BarLineChart)
+Vue.component(PieChart.name, PieChart)
+```
+
+### 2.3 子路径引入
+
+如果你的工程更偏向显式接入发布产物，可以直接引用 `lib` / `es` 子路径：
+
+```js
+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'
+```
+
+---
+
+## 3. 样式说明
+
+- 默认情况下，整包入口和组件级入口都会关联全量样式。
+- 大多数业务项目 **不需要** 再单独手动引入样式文件。
+- 如果你希望显式控制样式加载，也可以手动引入：
+
+```js
+import '@xq-labs/data-ui-v2/theme-chalk/index.css'
+```
+
+---
+
+## 4. 组件清单
+
+| 组件名 | 作用 | 适用场景 |
+| --- | --- | --- |
+| `BaseChart` | 通用 ECharts 渲染壳 | 已有完整 option，只需要统一渲染、空态、loading |
+| `BarLineChart` | 标准柱线图组件 | 基础柱图、圆柱、方柱、堆叠、双轴、柱线组合 |
+| `PieChart` | 标准饼图组件 | 2D 饼图 / 环图 / 玫瑰图，3D 饼图 / 环图 / 标签引导线 |
+
+> 当前公开组件只有 `BaseChart`、`BarLineChart`、`PieChart`。
+
+---
+
+## 5. 版本兼容说明
+
+| 项目 | 当前要求 | 说明 |
+| --- | --- | --- |
+| Vue | `^2.6.14 \|\| ^2.7.0` | 组件库面向 Vue 2 项目 |
+| ECharts | `^5.5.0` | 所有图表组件都依赖 |
+| ECharts GL | `^2.0.9` | 仅 `PieChart dimension="3d"` 需要 |
+| Node | `>=14 <15` | 当前仓库开发、构建、测试链路按 Node 14 验证 |
+
+补充说明：
+
+- 2D 图表使用方不需要安装 `echarts-gl`。
+- 3D 饼图在运行时会按需加载 `echarts-gl`。
+- 如果启用 3D 但项目未安装 `echarts-gl`，`PieChart` 会进入可读空态，并抛出 `runtime-error` 事件。
+
+---
+
+## 6. `BaseChart` API
+
+### 6.1 组件定位
+
+`BaseChart` 是所有业务图表组件的基础渲染壳。  
+如果你的业务侧已经能直接生成 ECharts option，可以直接使用它。
+
+### 6.2 Props
+
+| Prop | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `option` | `Object` | `{}` | 已构建完成的 ECharts option |
+| `loading` | `Boolean` | `false` | 是否显示 loading |
+| `empty` | `Boolean` | `false` | 是否显示空态 |
+| `emptyText` | `String` | `'暂无数据'` | 空态文案 |
+| `height` | `String \| Number` | `320` | 容器高度，数字按 px 处理 |
+
+### 6.3 Events
+
+| 事件名 | 参数 | 说明 |
+| --- | --- | --- |
+| `ready` | `chart` | ECharts 实例初始化完成 |
+| `chart-click` | `params` | 图表点击事件透出 |
+
+### 6.4 常见场景
+
+1. 你已经有现成的 ECharts option，只需要统一 loading、空态和实例生命周期。
+2. 你在业务项目里做一个内部定制图表，但仍希望复用统一底层壳。
+
+示例：
+
+```vue
+<BaseChart
+  :option="option"
+  :loading="loading"
+  :empty="!option.series || option.series.length === 0"
+  empty-text="暂无可展示数据"
+  :height="360"
+/>
+```
+
+---
+
+## 7. `BarLineChart` API
+
+### 7.1 组件定位
+
+`BarLineChart` 用于承接大多数柱线组合场景。  
+推荐先通过 `data + xAxisKey + series` 表达业务数据，再用 `variant`、`preset`、`customOption` 做增强。
+
+### 7.2 Props
+
+| Prop | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `data` | `Array` | `[]` | 原始业务数据数组 |
+| `xAxisKey` | `String` | `'name'` | 横轴类目字段名 |
+| `series` | `Array` | `[]` | 系列定义数组，推荐包含 `key`、`name`、`kind` |
+| `variant` | `String` | `'flat'` | 图形风格：`flat` / `cylinder` / `cube` |
+| `preset` | `String` | `'compare'` | 预设：`compare` / `trend` / `rank` |
+| `barWidth` | `Number` | `18` | 柱体宽度 |
+| `barGap` | `Number \| String` | `8` | 柱间距 |
+| `customOption` | `Object` | `{}` | 对 ECharts option 的补充覆盖 |
+| `loading` | `Boolean` | `false` | 是否显示 loading |
+| `height` | `String \| Number` | `320` | 容器高度 |
+
+### 7.3 BarLineChart 数据格式
+
+`BarLineChart` 的数据通常拆成两部分：
+
+1. `data`：原始业务数据数组。
+2. `series`：告诉组件“从哪些字段取值、每个字段按什么图形渲染”。
+
+推荐写法：
+
+```js
+const data = [
+  {
+    month: '1月',
+    sales: 120,
+    target: 150,
+    rate: 0.8
+  },
+  {
+    month: '2月',
+    sales: 168,
+    target: 180,
+    rate: 0.93
+  }
+]
+```
+
+```js
+const series = [
+  {
+    key: 'sales',
+    name: '销售额',
+    kind: 'bar',
+    colors: ['#6B98F8']
+  },
+  {
+    key: 'target',
+    name: '目标值',
+    kind: 'bar',
+    colors: ['#A8BEFA', '#6B98F8', '#3EE8FE']
+  },
+  {
+    key: 'rate',
+    name: '完成率',
+    kind: 'line',
+    yAxisIndex: 1,
+    colors: ['#FF8A5B']
+  }
+]
+```
+
+关键规则：
+
+- `xAxisKey` 用来告诉组件“哪一个字段是横轴类目”，默认是 `name`。
+- `series[i].key` 必须能在 `data` 的每一项中找到对应字段。
+- `kind` 当前只识别 `bar` / `line`，其他值会回退成 `bar`。
+- `stack` 传字符串时表示堆叠组名；不传或非法值会回退为空字符串。
+- `yAxisIndex` 只接受大于等于 `0` 的整数，非法值会回退到主轴。
+
+### 7.4 `series` 推荐结构
+
+```js
+[
+  {
+    key: 'sales',
+    name: '销售额',
+    kind: 'bar',
+    colors: ['#6B98F8']
+  },
+  {
+    key: 'rate',
+    name: '完成率',
+    kind: 'line',
+    yAxisIndex: 1
+  }
+]
+```
+
+### 7.5 `series.colors` 配置规则
+
+`series.colors` 是 `BarLineChart` 最重要的配色入口之一，类型要求是 `Array`。
+
+基础规则：
+
+- 只接受数组，非数组会被忽略并回退到组件内置色板。
+- 会过滤空值，最多只读取前 `1~3 个色值`。
+- 线图只使用第一个色值。
+
+不同 `variant` 下的含义：
+
+#### `flat`
+
+- 传 `1` 个色值：自动推导为“顶部 / 主体 / 底部”三段渐变。
+- 传 `2` 个色值：按“顶部 / 主体”解释，底部会基于主体色自动加深。
+- 传 `3` 个色值：按“顶部 / 主体 / 底部”解释。
+
+#### `cylinder`
+
+- 传 `1` 个色值：作为柱身主色，顶部和底部会自动派生。
+- 传 `2` 个色值：按“顶部 / 柱身”解释，底部会基于柱身色自动加深。
+- 传 `3` 个色值：按“顶部 / 柱身 / 底部”解释。
+
+#### `cube`
+
+- 传 `1` 个色值：作为主色，左侧面、右侧面会自动派生，顶面使用主色。
+- 传 `2` 个色值：按“左侧面 / 右侧面”解释，顶面自动提亮。
+- 传 `3` 个色值：按“左侧面 / 右侧面 / 顶面”解释。
+
+示例：
+
+```js
+colors: ['#6B98F8']
+colors: ['#A8BEFA', '#6B98F8']
+colors: ['#A8BEFA', '#6B98F8', '#3EE8FE']
+```
+
+### 7.6 Events
+
+| 事件名 | 参数 | 说明 |
+| --- | --- | --- |
+| `ready` | `chart` | 底层 ECharts 实例 |
+| `chart-click` | `params` | 点击图形元素时触发 |
+
+### 7.7 常见场景
+
+1. **基础柱线组合**：销售额 + 完成率双轴。
+2. **圆柱视觉**：看板类数据强调“柱体感”。
+3. **方柱视觉**：更偏装饰型、品牌型大屏风格。
+4. **堆叠柱图**：多个系列共享一组类目。
+5. **自定义展示细节**：通过 `customOption` 补 tooltip、legend、grid。
+
+推荐查阅：
+
+- `docs/examples/bar-line-chart.md`
+- Playground 路由：`/bar-line-chart/basic`
+- Playground 路由：`/bar-line-chart/cylinder`
+- Playground 路由：`/bar-line-chart/cube`
+- Playground 路由：`/bar-line-chart/advanced`
+- Playground 路由：`/bar-line-chart/custom`
+
+---
+
+## 8. `PieChart` API
+
+### 8.1 组件定位
+
+`PieChart` 用于承接标准饼图类场景，并统一 2D / 3D、普通 / 环形、普通 / 玫瑰 这些公开能力。
+
+### 8.2 Props
+
+| Prop | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `data` | `Array` | `[]` | 饼图数据源，推荐项结构至少包含 `name`、`value` |
+| `variant` | `String` | `'pie'` | 形态：`pie` / `ring` / `rose-pie` / `rose-ring` |
+| `dimension` | `String` | `'2d'` | 维度：`2d` / `3d` |
+| `preset` | `String` | `'ratio'` | 预设：`ratio` / `rank` |
+| `heightMode` | `String` | `'equal'` | 3D 高度：`equal` / `value` |
+| `minHeight` | `Number` | `20` | 3D 最小扇区高度 |
+| `maxHeight` | `Number` | `80` | 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 |
+| `height` | `String \| Number` | `320` | 容器高度 |
+
+### 8.3 PieChart 数据格式
+
+`PieChart` 的 `data` 直接传扇区数组即可，每一项至少建议包含：
+
+- `name`：扇区名称。
+- `value`：扇区数值。
+
+推荐写法：
+
+```js
+const data = [
+  {
+    name: '华东',
+    value: 120,
+    itemStyle: {
+      color: '#6B98F8',
+      opacity: 0.9
+    }
+  },
+  {
+    name: '华南',
+    value: 98,
+    itemStyle: {
+      color: '#36CFC9'
+    }
+  }
+]
+```
+
+关键规则：
+
+- `name` 缺失时，组件会自动补成 `数据1`、`数据2` 这类默认名称。
+- `value` 会统一做 `Number(...)` 转换，非法值会回退成 `0`。
+- 除 `name`、`value` 之外，其余字段会保留，方便业务侧自己挂扩展信息。
+- 3D 模式下，如果 `hideZeroValueSlices = true`，值小于等于 `0` 的扇区会被过滤。
+
+### 8.4 PieChart 配色规则
+
+`PieChart` 当前没有单独暴露 `colors` prop。
+
+推荐的外部配色方式是：
+
+1. 直接在 `data` 的每一项里写 `itemStyle.color`
+2. 如有需要，再通过 `itemStyle.opacity` 控制透明度
+
+颜色规则：
+
+- `itemStyle.color` 是最直接、最稳定的配色方式。
+- `itemStyle.opacity` 不传时默认是 `0.85`。
+- 如果某一项没有写 `itemStyle.color`，组件会按内置色板顺序自动分配颜色。
+
+示例：
+
+```js
+const data = [
+  {
+    name: '已完成',
+    value: 76,
+    itemStyle: {
+      color: '#6B98F8'
+    }
+  },
+  {
+    name: '处理中',
+    value: 18,
+    itemStyle: {
+      color: '#FF8A5B',
+      opacity: 0.75
+    }
+  }
+]
+```
+
+### 8.5 labelOptions 字段说明
+
+`labelOptions` 用来控制饼图标签与引导线的展示细节。
+
+它通常和顶层 `showLabelLine` 一起使用：
+
+- `showLabelLine = false`：不显示引导线。
+- `showLabelLine = true`：显示引导线，并读取 `labelOptions` 中的线长、颜色、文字等配置。
+
+字段说明：
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `show` | `Boolean` | `true` | 是否显示标签文本，主要影响 2D 饼图标签 |
+| `formatter` | `String \| Function` | `'{b}\n{d}%'` | 标签文案格式 |
+| `fontSize` | `Number` | `14` | 标签文字字号 |
+| `color` | `String` | `'#333'` | 标签文字颜色 |
+| `lineColor` | `String \| null` | `null` | 引导线颜色，不传时使用 `color` |
+| `lineWidth` | `Number` | `1` | 引导线宽度 |
+| `lineLength1` | `Number` | `18` | 第一段引导线长度 |
+| `lineLength2` | `Number` | `24` | 第二段引导线长度 |
+| `minShowLabelAngle` | `Number` | `0` | 小于该角度的扇区不显示标签 |
+| `edgePadding` | `Number` | `12` | 标签距离画布左右边缘的最小距离 |
+| `textGap` | `Number` | `6` | 标签文字与引导线末端的间距 |
+| `verticalGap` | `Number` | `8` | 多个标签垂直避让时的最小间距 |
+| `radialOffset` | `Number` | `0.12` | 3D 引导线从扇区外侧向外延伸的径向偏移 |
+
+`formatter` 支持字符串模板和函数。
+
+字符串模板支持：
+
+- `{b}`：名称，对应 `name`
+- `{c}`：数值，对应 `value`
+- `{d}`：百分比，对应内部计算后的 `percent`
+
+示例：
+
+```js
+const labelOptions = {
+  formatter: '{b}：{c}\n占比 {d}%',
+  fontSize: 13,
+  color: '#1F2937',
+  lineColor: '#6B98F8',
+  lineWidth: 1,
+  lineLength1: 22,
+  lineLength2: 32,
+  minShowLabelAngle: 5,
+  edgePadding: 16,
+  textGap: 8,
+  verticalGap: 10,
+  radialOffset: 0.16
+}
+```
+
+如果需要更复杂的文案，可以传函数：
+
+```js
+const labelOptions = {
+  formatter({ name, value, percent, data }) {
+    return `${name}\n${value} / ${percent}%`
+  }
+}
+```
+
+函数参数说明：
+
+- `name`：扇区名称。
+- `value`：扇区数值。
+- `percent`：组件内部计算出来的百分比。
+- `data`：当前扇区对应的原始数据项。
+
+### 8.6 Events
+
+| 事件名 | 参数 | 说明 |
+| --- | --- | --- |
+| `ready` | `chart` | 底层 ECharts 实例 |
+| `chart-click` | `params` | 点击图形元素时触发 |
+| `runtime-error` | `error` | 3D 运行时缺少 `echarts-gl` 等异常时触发 |
+
+### 8.7 3D 依赖说明
+
+- `dimension="2d"` 时，不需要安装 `echarts-gl`。
+- `dimension="3d"` 时，需要安装 `echarts-gl`。
+- 3D 模式会在运行时按需加载 `echarts-gl`。
+
+### 8.8 常见场景
+
+1. **普通饼图**：`variant="pie"`，适合占比展示。
+2. **环图**：`variant="ring"`，适合中心留白展示关键指标。
+3. **玫瑰图**：`variant="rose-pie"` 或 `variant="rose-ring"`，适合强调差异。
+4. **3D 饼图**：`dimension="3d"`，适合大屏或品牌展示。
+5. **按值映射高度**：`dimension="3d" + heightMode="value"`。
+6. **标签与引导线**：`showLabelLine + labelOptions`。
+7. **零值过滤**：3D 下使用 `hideZeroValueSlices` 控制是否过滤 0 值扇区。
+
+推荐查阅：
+
+- `docs/examples/pie-chart.md`
+- Playground 路由：`/pie-chart/basic`
+- Playground 路由：`/pie-chart/shape-2d`
+- Playground 路由：`/pie-chart/three-d`
+- Playground 路由：`/pie-chart/label`
+- Playground 路由：`/pie-chart/custom`
+
+---
+
+## 9. 外部配置怎么传
+
+推荐用 `v-bind` 传一个清晰的配置对象，而不是在模板里零散写大量字面量。
+
+### 9.1 `BarLineChart`
+
+```vue
+<BarLineChart
+  v-bind="{
+    data,
+    xAxisKey: 'month',
+    series,
+    variant: 'cylinder',
+    preset: 'compare',
+    customOption
+  }"
+/>
+```
+
+### 9.2 `PieChart`
+
+```vue
+<PieChart
+  v-bind="{
+    data,
+    variant: 'ring',
+    dimension: '3d',
+    heightMode: 'value',
+    minHeight: 20,
+    maxHeight: 80,
+    showLabelLine: true,
+    labelOptions,
+    customOption
+  }"
+/>
+```
+
+---
+
+## 10. 文档与示例导航
+
+- API 总览：`docs/api/overview.md`
+- 柱线图示例说明：`docs/examples/bar-line-chart.md`
+- 饼图示例说明：`docs/examples/pie-chart.md`
+- 可运行 Demo 库：`playground`
+
+建议阅读顺序：
+
+1. 先看这份 API 总览，确认组件和 props。
+2. 再看对应的示例说明文档，理解推荐传参方式。
+3. 最后打开 Playground，对照具体案例调参。