GBUI（guabiui）

面向桌面级 Web 应用的 Vue 3 组件库。不是后台管理模板那一套——它解决的是编辑器/办公软件里那些 Element Plus 不覆盖的东西：自绘浮层、右键菜单、查找栏、取色面板、表格浮层、Excel 式批量录入、全屏看图。

• 零运行时依赖：只要 vue（peer），不引任何 UI 库、CSS 框架、日期库；库内共用的小工具构建时打进 dist
• 纯 CSS + 令牌：没有 scss / tailwind，颜色、间距、字号、层级全部走 --gb-* 自定义属性
• 明暗双主题：换令牌值即可，组件源码里没有主题分支
• 键盘可达：浮层焦点管理、Esc/Enter 语义、Tab 顺序都在组件内处理
• 设计语言可执行：npm run lint:design 把设计规则当 lint 跑，裸色值、裸字号、!important 直接失败

安装

npm install guabiui

快速开始

全量注册：

import { createApp } from 'vue';
import Gbui from 'guabiui';
import 'guabiui/styles';

createApp(App).use(Gbui).mount('#app');

按需引入：

<script setup>
import { GbButton, GbPopover } from 'guabiui';
import 'guabiui/styles';
</script>

样式只有一份 dist/gbui.css（cssCodeSplit: false），按需引入也必须整体引入一次。

主题

两套主题只差一组令牌值，挂在根元素的 data-gb-theme 上：

document.documentElement.dataset.gbTheme = 'dark';   // 缺省（不设）为浅色

要换品牌色，覆盖同名令牌即可，不要改组件：

:root {
  --gb-accent: #4f46e5;
  --gb-accent-hover: #6366f1;
}

完整令牌表见 DESIGN.md，唯一数据源是 src/styles/tokens.css。

组件

16 个组件登记在 src/catalog.js（文档站侧边栏、总览表格、搜索索引都从这张表生成）：

| 分类 | 组件 | | --- | --- | | 基础 | GbIcon、GbButton | | 弹层 | GbPopupHost、GbPopover、GbContextMenu | | 数据展示 | GbCalendarHeatmap、GbImageAlbum、GbOrderableList | | 数据录入 | GbBatchEntry | | 编辑器浮件 | GbFindBar、GbColorPanel、GbAppearancePanel、GbTableOverlay、GbTableSizePicker | | 反馈 | GbInProgressOverlay | | 媒体 | GbImageViewer |

另有两个随库导出但未登记在目录里的组件：GbMenuItemIcon（菜单项图标渲染）、GbBatchEntryTable（GbBatchEntry 的表格内核，单独用时可接管已有数据源）。

几个值得单独说的：

• GbPopupHost —— 同一处调用在侧边抽屉与居中弹窗之间切换，形态与宽高按场景记忆，省掉「这个表单该弹窗还是抽屉」的反复决定。
• GbBatchEntry —— Excel 式批量录入：选区、粘贴、键盘导航、撤销重做、列定义进 / 扁平行记录出。
• GbFindBar —— 查找替换浮条，命中高亮走 CSS Custom Highlight API，搜索引擎以适配器注入（不绑定具体编辑器）。
• GbTableOverlay —— 挂在标准 <table> 上的浮件层：框选覆盖、边缘插入把手、列宽提示线。

工具函数

组件之外还有一批纯函数，可脱离组件单独用：

import { clampFloatPosition, computeMenuPosition, eventAnchor } from 'guabiui';   // 浮层定位
import { normalizeHex, isSameColor } from 'guabiui';                              // 颜色归一
import { dateKey, monthKey } from 'guabiui';                                      // 日期键
import { gbToast } from 'guabiui';                                                // 轻提示

本地开发

npm install
npm run dev          # 文档站 http://localhost:5180（含每个组件的 demo 与 API 表）
npm test             # 单测 + 设计语言检查
npm run lint:design  # 只跑设计语言检查
npm run build        # 产出 dist/gbui.js + dist/gbui.umd.cjs + dist/gbui.css

文档站用别名 gbui 指向 src/index.js，不需要先 link；新增组件时 catalog.js、文档页、demo 三处要同步（见 DESIGN.md 末尾的自检清单）。

浏览器要求

常青浏览器即可（Chrome / Edge 111+、Safari 16.4+、Firefox 113+）。依赖的是这几样：

| 特性 | 用在哪 | 不支持时 | | --- | --- | --- | | CSS color-mix() | --gb-tint / --gb-shade 混合锚点 | 悬浮/选中底色失效 | | ResizeObserver | 浮层尺寸测量与自动翻转 | 定位不跟随尺寸变化 | | CSS Custom Highlight API | GbFindBar 命中高亮 | 查找仍可用，只是不高亮（已做能力检测） |

没有用 popover、dialog、:has() 这些还在铺开的特性，浮层是自绘 + position: fixed 的。

License

MIT