@xq-labs/data-ui-v3

一套面向 Vue 3 项目的业务图表组件库，当前公开 BaseChart、BarLineChart、PieChart、RadarChart 四个组件，配套 playground 示例站点、离线文档、Rollup 发布构建和本地发布脚本。

适用环境

• Vue 3.4+
• Node 18、20、22（当前开发基线为 22.17.1）
• ECharts 5
• ECharts GL 2（仅 PieChart 3D 能力需要）

安装

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

组件库将 vue、echarts 作为外部依赖暴露给业务项目。

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

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

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

如果项目有多个页面都会使用 3D PieChart，也可以统一放到应用入口中引入。

整包注册

import { createApp } from 'vue'
import DataUI from '@xq-labs/data-ui-v3'

const app = createApp({})
app.use(DataUI)

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

• BaseChart
• BarLineChart
• PieChart
• RadarChart

按需引入

import { createApp } from 'vue'
import { BaseChart, BarLineChart, PieChart, RadarChart } from '@xq-labs/data-ui-v3'

const app = createApp({})

app.component(BaseChart.name, BaseChart)
app.component(BarLineChart.name, BarLineChart)
app.component(PieChart.name, PieChart)
app.component(RadarChart.name, RadarChart)

如果你的构建链路需要直接引用发布子路径，也可以按 lib / es 产物接入：

import BaseChart from '@xq-labs/data-ui-v3/es/base-chart'
import BarLineChart from '@xq-labs/data-ui-v3/es/bar-line-chart'
import PieChart from '@xq-labs/data-ui-v3/es/pie-chart'
import RadarChart from '@xq-labs/data-ui-v3/es/radar-chart'

样式说明

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

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

3D PieChart 运行时说明

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

推荐接入方式：

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

建议直接写在使用 3D PieChart 的页面顶部。该入口只负责注册 3D 运行时依赖，不会注册组件，也不会影响 2D 场景。

包内同时保留 pie-chart/3d-runtime.js 物理入口，用于兼容不识别 package.json#exports 的老链路。

如果 3D runtime 未就绪，组件会进入可读空态，并通过 runtime-error 事件抛出异常，同时提示你先引入 @xq-labs/data-ui-v3/pie-chart/3d-runtime。

组件能力概览

BaseChart

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

BarLineChart

• 支持基础柱线组合。
• 支持圆柱、方柱、堆叠、双轴、颜色预设与自定义配置。
• 支持 xAxisScroll 横轴滚动窗口配置。

PieChart

• 支持 2D 饼图、环图、玫瑰饼图、玫瑰环图。
• 支持 3D 饼图、3D 环图、按值映射高度、零值过滤等能力。
• 支持标签、引导线、customOption 与 runtime-error 运行时兜底。

RadarChart

• 支持面积雷达图与折线雷达图。
• 支持字段映射式指标配置，避免 ECharts 原生 value 数组顺序错位。
• 支持系列色板和 customOption 扩展。

示例与文档

• API 总览：docs/api/overview.md
• 可运行示例：playground
• 本地联调说明：docs/examples/local-development.md
• 示例说明：docs/examples/pie-chart.md
• 示例说明：docs/examples/bar-line-chart.md
• 示例说明：docs/examples/radar-chart.md
• npm 包内离线文档：node_modules/@xq-labs/data-ui-v3/docs/api/overview.md
• npm 包内示例说明：node_modules/@xq-labs/data-ui-v3/docs/examples/*.md

常用命令

# 启动 playground
npm run serve

# 单元测试
npm run test

# 类型检查
npm run typecheck

# 代码检查
npm run lint

# 代码格式检查
npm run format:check

# 构建发布产物
npm run build

# 检查 .release 发包内容
npm run pack:check

# 本地发布流程
npm run release

发布说明

• vite 负责本地开发与 playground 启动。
• vitest 与 vue-tsc 负责测试、类型检查和回归验证。
• rollup 负责正式发布构建。
• 发布产物统一归档到 .release/。
• npm 包默认不包含 dist 目录下的 UMD 产物。
• dist 会继续构建，供独立制品分发或浏览器直引场景使用。
• 发布前要求工作区干净。
• 发包成功后还会继续执行 release commit、tag 和 push，保证仓库版本历史与 CHANGELOG.md 同步。

npm 鉴权说明

推荐在仓库根目录使用本地 .npmrc 保存 _authToken，避免每次发布都手动输入 OTP。

注意：

• 根目录 .npmrc 已加入 .gitignore，不要把真实 token 提交到仓库。
• 推荐使用 npm automation token 或具备 publish 权限的专用 token。
• token 轮换后，记得同步更新本地 .npmrc。

参考配置：

registry=https://registry.npmjs.org/
always-auth=true
//registry.npmjs.org/:_authToken=你的 npm token

配置完成后，维护者可以继续沿用现有发布命令：

npm run release -- patch

如果只想跳过 release 流程、直接把当前 .release/ 推到 npm，也可以执行：

npm publish .release --access public