大数据平台-通用组件库

基于 Vue 3 + TypeScript + esbuild 构建的大数据平台通用 UI 组件库，提供导航、基础展示、数据卡片、配置化表单/表格、图表等能力，并内置多主题切换与可视化主题配置。

| 属性 | 说明 | | --- | --- | | 包名 | @gyyxds/gyy-web-components | | 技术栈 | Vue 3、TypeScript、Element Plus、ECharts、Sass | | 构建工具 | esbuild |

功能特性

• TypeScript 类型支持
• esbuild 打包，产物体积小、构建速度快
• ESLint 代码规范检查
• Sass / PostCSS 样式预处理
• BrowserSync 本地热更新预览
• 内置 6 套主题：default / light / dark / cyanlime / custom / simpleWhite
• 可视化主题编辑器（ZgSetupTheme）

组件列表

导航类

| 组件 | 说明 | | --- | --- | | ZgButtonMenu | 按钮组式导航菜单，支持字符串数组或 { name, code } 字典列表，可配置默认选中项 | | ZgUnderlineMenu | 下划线高亮 Tab 导航，支持自定义每项宽度 | | ZgElTabMenu | 基于 Element Plus 的横向 Tab 菜单，支持标签状态展示 |

基础展示类

| 组件 | 说明 | | --- | --- | | ZgContainer | 带标题栏的容器，支持图标、标题标记线、标题/右侧插槽，可控制阴影 | | ZgTitleBar | 页面标题栏，支持主标题、副标题及渐变背景色配置 | | ZgSvgIcon | SVG 图标组件（基于 iconpark），支持颜色、阴影、自定义 class | | ZgStatusDot | 状态圆点 + 文字，支持多种状态类型与边框样式 | | ZgStatusTag | 状态标签，带圆点指示，支持闪烁、圆角、隐藏背景等 | | ZgPidInfoVO | 数值信息展示，支持单位、涨跌幅三角标识、多字段列表、自定义格式化 | | ZgCountTo | 数字滚动动画，支持小数位、前后缀、千分位分隔符 | | ZgCountByFlip | 翻牌式数字动画，逐位翻转展示数值 | | ZgFlipNumber | 单个翻牌数字（ZgCountByFlip 内部子组件，可单独预览） | | ZgSetupTheme | 可视化主题配置面板，支持搜索/编辑 CSS 变量、颜色选择、代码编辑与组件预览 |

数据展示类

| 组件 | 说明 | | --- | --- | | ZgDataStatCard | 数据统计卡片，展示多指标数据，支持翻牌/滚动动画、趋势箭头、主次指标分区 | | ZgChart | 基于 ECharts 的图表组件，自动适配容器尺寸，随全局主题切换图表皮肤 |

Element Plus 增强类

| 组件 | 说明 | | --- | --- | | ZgElBasicForm | 配置化表单，通过 formItems 声明字段，支持编辑/新增/搜索/查看模式，内置输入框、下拉、日期、级联、区域选择、上传等多种控件 | | ZgElBasicTable | 配置化表格，支持多选/单选、序号列、嵌套表头、操作列、排序、自定义列插槽 | | ZgElTablePage | 表格页面组合组件，集成搜索表单 + 数据表格 + 分页，可包裹在 ZgContainer 中 | | ZgElTestButton | Element Plus 按钮样式演示组件，用于主题/样式调试 | | ZgUpload | 图片上传组件（源码位于 packages/element-plus/Form/ZgUpload，供表单内部使用） |

工具与指令

| 导出项 | 说明 | | --- | --- | | install | 全局注册所有组件及 v-theme 指令 | | useTheme / useStorageTheme / useDefaultTheme | 主题切换，支持本地缓存 | | appTheme | 当前主题响应式变量 | | vTheme（指令名 theme） | 使元素随全局主题自动切换 CSS 类 | | chartUtil | 图表相关工具函数 | | useModelAgent | 表单/表格数据模型相关 hooks | | hanldleFileUrl | 文件 URL 拼接处理 | | utils | 加密等通用工具函数 | | configInfo | 组件库版本信息（getVersion()） | | listenI18n / setDefault$t | 国际化支持 |

安装使用

yarn add @gyyxds/gyy-web-components

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import ZgUI, { useStorageTheme } from '@gyyxds/gyy-web-components'
import 'element-plus/dist/index.css'

const app = createApp(App)
app.use(ZgUI)
app.use(ElementPlus)
useStorageTheme() // 恢复缓存主题
app.mount('#app')

按需引入：

import { ZgContainer, ZgElTablePage, useTheme } from '@gyyxds/gyy-web-components'

注意：vue、element-plus、echarts 为 peer 依赖，需在业务项目中自行安装。

本地调试

1. 安装依赖

yarn

2. 启动开发服务

yarn dev

该命令会：

1. 清理 examples/static 目录
2. 使用 esbuild 打包 examples/ 预览页面（watch 模式）
3. 启动 BrowserSync 开发服务器，默认端口 5000

3. 访问预览页

浏览器打开 http://localhost:5000

左侧菜单可切换各组件 Demo，顶部下拉框可切换主题皮肤进行预览。

4. 其他常用命令

# 生产打包组件库（输出到 lib/）
yarn build

# 生成 TypeScript 类型声明（输出到 types/）
yarn dts

# 类型检查（不输出文件）
yarn dts:check

# 代码规范检查
yarn lint

# 自动修复 ESLint 问题
yarn lint:fix

5. 新增组件调试流程

1. 在 packages/ 下对应分类目录中创建组件源码
2. 在 packages/index.ts 中注册并导出
3. 在 examples/packages/ 下创建对应 Demo 页面
4. 在 examples/App.vue 的 componentsList 中引入 Demo 组件
5. 执行 yarn dev 在预览页中验证

发布到 npm

前置条件

• 拥有 @gyyxds 组织下的发布权限
• 已登录 npm 账号：

yarn login

发布步骤

1. 更新版本号

根据改动类型选择版本递增方式：

# 修复 bug（0.7.8 → 0.7.9）
yarn version --patch

# 新增功能（0.7.8 → 0.8.0）
yarn version --minor

# 破坏性变更（0.7.8 → 1.0.0）
yarn version --major

也可手动修改 package.json 中的 version 字段。

2. 生成类型声明

yarn dts

3. 构建组件库

yarn build

yarn publish 前会自动执行 prepublishOnly 钩子触发 build，但类型声明需手动执行 yarn dts。

4. 发布

yarn publish

包将发布到 https://www.npmjs.com/package/@gyyxds/gyy-web-components，publishConfig.access 已配置为 public。

5. 验证发布结果

yarn info @gyyxds/gyy-web-components version

或在业务项目中更新依赖：

yarn add @gyyxds/gyy-web-components@latest

目录结构

packages/                  # 组件库源码
├── components/            # 基础 & 导航 & 数据组件
│   ├── Basic/             # 基础展示组件
│   ├── Navigation/        # 导航组件
│   └── Data/              # 数据展示组件
├── element-plus/          # 基于 Element Plus 的增强组件
├── ZgChart/               # 图表组件
├── assets/                # 静态资源 & 全局样式
├── helper/                # 主题、文件等工具
├── directive/             # 自定义指令
├── i18n/                  # 国际化
└── index.ts               # 组件库入口

examples/                  # 本地预览页面
├── main.ts                # 预览入口
├── App.vue                # 预览布局（组件切换 + 主题切换）
├── index.html             # HTML 模板
└── packages/              # 各组件 Demo

lib/                       # 构建产物（yarn publish 包含）
types/                     # TypeScript 类型声明（yarn publish 包含）

esbuild.config.js          # esbuild 构建配置
components.js              # 单组件映射表
tsconfig.json              # TypeScript 配置

主题说明

组件库支持以下主题，通过 useTheme('主题名') 切换：

| 主题 | 说明 | | --- | --- | | default | 默认主题 | | light | 浅色主题 | | dark | 深色主题 | | cyanlime | 青柠色主题 | | custom | 自定义主题（可通过 ZgSetupTheme 可视化配置 CSS 变量） | | simpleWhite | 简约白主题 |

自定义主题的 CSS 变量编码规则详见 readme2.md。