大数据平台-通用组件库

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

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

功能特性

• TypeScript 类型支持
• esbuild 打包，产物体积小、构建速度快
• ESLint 代码规范检查
• Sass / PostCSS 样式预处理
• BrowserSync 本地热更新预览
• 内置 7 套主题：default / light / dark / cyanlime / custom / simpleWhite / keycap
• 键帽主题 keycap：与 @gyyxds/zy-ui 的实色键帽（solid）风格对齐
• 可视化主题编辑器（GyySetupTheme）

组件列表

导航类

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

基础展示类

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

数据展示类

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

Element Plus 增强类

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

工具与指令

| 导出项 | 说明 | | --- | --- | | 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 GyyUI, { useStorageTheme } from '@gyyxds/gyy-web-components'
import 'element-plus/dist/index.css'

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

按需引入：

import { GyyContainer, GyyElTablePage, 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 的增强组件
├── GyyChart/               # 图表组件
├── 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 | 自定义主题（可通过 GyySetupTheme 可视化配置 CSS 变量） | | simpleWhite | 简约白主题 | | keycap | 实色键帽主题（浅色档），与 @gyyxds/zy-ui 的 solid 对齐 |

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

键帽主题 keycap

实色键帽是「能按的件是凸的、装东西的件是凹的」的实物语言，与 @gyyxds/zy-ui 的 data-zy-theme="solid"（浅色档）同源：键面 / 挤出底座 / 槽 / 桌面四级阶梯取自 zy-ui 的 themes/solid.css，品牌色用机构蓝 #0066a9（不再是旧库的 #0066ff）。

import { useTheme } from '@gyyxds/gyy-web-components'
import 'element-plus/dist/index.css'
import '@gyyxds/gyy-web-components/lib/gyy-web-components.css'

// 顺序：Element 样式 → 组件库样式（键帽的 Element 桥要压过 Element 默认值）
useTheme('keycap')

三条边界：

1. 只做浅色档：keycap 不叠加深色，深色请继续用 dark；后续若补，按 zy-ui 的做法只加一组令牌。
2. 只换材质，不动尺寸：控件高度、内边距、间距全部沿用旧库寸法（30–50px）， 避免存量仪表盘排版位移；圆角按新库分两档（键一级 6px / 小件 4px）。
3. Element Plus 基线 ≥ 2.5：输入框 el-select__wrapper、日期面板 el-date-table-cell__text 等选择器以 2.14 为验收基线，同时保留了旧版 select 的 .el-select .el-input__wrapper 兜底。

主题令牌（只在 body.theme-keycap 下定义，可被业务覆盖）：

| 令牌 | 值 | 用途 | | --- | --- | --- | | --gyy-desk | #e6ecf3 | 桌面（页面底） | | --gyy-key-face / --gyy-key-base | #ffffff / #d5dfea | 键面 / 挤出底座 | | --gyy-key-lift / --gyy-key-lift-sm | 4px / 2px | 正常档 / 小件档厚度 | | --gyy-slot-face / --gyy-slot-shadow | #e9eef4 / 内阴影 | 槽（输入、托盘、轨道） | | --gyy-brand | #0066a9 | 品牌蓝（对齐 zy-ui） |

组件侧只吃材质、不认主题名：新增主题全部在 packages/theme-keycap/ （tokens.scss / material.scss / element.scss），改样式不必改组件。 GyyChart 另有 gyy-keycap-theme（packages/GyyChart/src/theme-keycap.js），随主题自动切换。

改了 light.scss 的布局要同步键帽层，可用 npm run check:keycap 自查漏项。