@xq-labs/data-ui-v2

一套面向 Vue 2 项目的业务图表组件库，当前聚焦 BaseChart、BarLineChart、PieChart、RadarChart 四个公开组件，配套 playground 示例库、Rollup 发布构建和本地发版脚本。

适用环境

• Vue 2.6 / 2.7
• Node 14
• ECharts 5
• ECharts GL 2（仅 3D 饼图需要）

安装

npm install @xq-labs/data-ui-v2

组件库将 vue 与 echarts 作为外部依赖。

宿主项目只需确保已安装 vue 与 echarts。

如果你要使用 PieChart 的 3D 能力， 请先安装 echarts-gl，并在使用 3D PieChart 的页面顶部引入桥接入口：

import '@xq-labs/data-ui-v2/pie-chart/3d-runtime'

如果你的项目有多个页面都会使用 3D PieChart， 也可以选择在应用入口统一引入这个桥接入口。

整包注册

import Vue from 'vue'
import DataUI from '@xq-labs/data-ui-v2'

Vue.use(DataUI)

整包入口会注册以下公开组件：

• BaseChart
• BarLineChart
• PieChart
• RadarChart

按需引入

import Vue from 'vue'
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 产物接入：

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'

样式说明

• 发布产物默认通过入口文件关联组件样式
• 如需显式引入样式，可单独引用 @xq-labs/data-ui-v2/theme-chalk/index.css

import '@xq-labs/data-ui-v2/theme-chalk/index.css'

3D 饼图运行时说明

PieChart 使用 dimension="3d" 时， 组件库主入口不会代替业务项目自动加载 echarts-gl。

推荐接入方式：

import '@xq-labs/data-ui-v2/pie-chart/3d-runtime'

建议直接写在使用 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。

组件能力概览

BaseChart

• 提供 ECharts 实例创建、销毁、尺寸监听与空态处理
• 作为其他图表组件的通用基础壳

BarLineChart

• 支持基础柱线组合
• 支持圆柱、方柱、堆叠、双轴、颜色预设与自定义配置
• 对齐 playground 中的正式案例与实验室案例

PieChart

• 支持 2D 饼图、环图、南丁格尔图
• 支持 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

常用命令

# 启动 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