yd-admin

yd-admin

🎨 基于 Vue 3 的后台管理框架通用组件库

✨ 特性

• 📦 轻量高效 - Tree-shaking 支持，按需引入
• 🎯 类型安全 - 完整的 TypeScript 类型定义
• 🎨 主题定制 - CSS 变量设计，支持暗色模式
• ⚡ 性能优化 - 虚拟滚动、防抖节流、位置缓存
• 🔌 即插即用 - 零配置，简单 API

📦 安装

vp add yd-admin

🚀 快速开始

完整引入

import { createApp } from "vue";
import YdAdmin from "yd-admin";
import "yd-admin/style.css"; // 引入样式
import App from "./App.vue";

const app = createApp(App);
app.use(YdAdmin);
app.mount("#app");

按需引入

import { YdButton, YdInput, YdSelect } from "yd-admin";
import "yd-admin/style.css";

按模块引入

// 只引入组件
import { YdButton, YdTable } from "yd-admin/components";

// 只引入组合式函数
import { useTableVirtual } from "yd-admin/composables";

// 只引入工具函数
import { cn, debounce } from "yd-admin/utils";

// 只引入类型
import type { YdTableProps } from "yd-admin/types";

Vite 配置（自动导入）

// vite.config.ts
import Components from "unplugin-vue-components/vite";
import { YdAdminResolver } from "yd-admin/resolver";

export default {
  plugins: [
    Components({
      resolvers: [YdAdminResolver()],
    }),
  ],
};

📚 组件列表

基础组件 (Base)

AI 组件 (AI Components)

表单组件 (Form)

布局组件 (Layout)

数据存储 (Stores)

使用示例:

import { createPinia } from "pinia";
import { secureStoragePlugin, initSecureStorage } from "yd-admin";

const pinia = createPinia();
pinia.use(secureStoragePlugin);

// 应用启动时初始化
await initSecureStorage();

数据展示 (Data Display)

导航组件 (Navigation)

反馈组件 (Feedback)

配置组件 (Config)

路由 (Router)

🎨 主题定制

组件库使用 CSS 变量构建，支持全局主题覆盖：

:root {
  --yd-color-primary: #1890ff;
  --yd-border-radius: 4px;
  /* 更多变量见 tokens.css */
}

或使用 YdConfigProvider：

<template>
  <YdConfigProvider :theme="darkTheme">
    <App />
  </YdConfigProvider>
</template>

🛠️ 工具函数

import { cn, debounce, throttle, generateId, deepClone } from "yd-admin";

// 合并 class
const classes = cn("base-class", condition && "conditional-class");

// 防抖
const debouncedFn = debounce(() => console.log("debounced"), 300);

// 节流
const throttledFn = throttle(() => console.log("throttled"), 100);

// 生成唯一 ID
const id = generateId("prefix");

// 深拷贝
const cloned = deepClone(obj);

📐 组件尺寸

所有组件支持统一尺寸配置：

🌐 开发

环境要求

• Node.js ^22.18.0 || ^24.11.0 || >=26.0.0（与工具链 vite-plus 的 engines 一致）
• Vite+ (vp)

安装依赖

vp install

开发预览

# 启动 Demo
vp dev

# 监视模式构建
vp build --watch

代码检查

# 类型检查和格式化检查
vp check

# 格式化修复
vp fmt

构建发布

vp build

运行测试

vp test

✅ 代码质量状态

项目已通过以下检查：

• ✅ TypeScript 类型检查（src / demo / docs 三项门禁）
• ✅ Oxlint 代码检查（源码 src/**，0 error）
• ✅ 格式化检查（Prettier / Biome）
• ✅ 单元 + 组件测试 8194 项全部通过（含 emits 双守卫门禁）

📊 Bundle 信息

📋 更新日志

v0.4.5

• 🐛 收口 5 个「文档承诺但从未发射」的死事件（emits 审计延续）：YdTable 的 cell-focus / cell-validate / import / proxy-data-load 在各自自然完成点补发真实 emit（由对应 composable 的可选回调驱动，不破坏既有调用方）；chat-page.update-conversation 因组件是受控透传、无自然发射点且零消费方，从 API 与文档下线。
• 🆕 YdPagination 新增语义事件 page-change(page, pageSize) / size-change(pageSize, page)：与 update:currentPage / update:pageSize（v-model 通道）在同一次交互中同时触发，语义通道给业务查询、v-model 通道给受控绑定（同一件事请二选一监听，同时监听会重复请求）。
• 🔧 启用并修复 lint：vp lint / vp check 此前完全不读 oxlintrc.json，整套规则从未生效；配置迁入 vite.config.ts，源码 src/** 余 134 条 warning（0 error），作为可见债务保留。
• 📖 YdTable 可展开行文档补全：明确 #expand 插槽用法与作用域参数（{ row, index }），并写清一条容易踩的限制 —— expandable 会默认关掉虚拟滚动（虚拟模式把展开行绝对定位在 (i+1)*rowHeight，而 totalHeight 不计展开行高度 → 展开后与下一行重叠），需要同时用时必须显式 :virtualScroll="true" 并自行控制展开内容高度。
• 🔒 表格综合审计结案（P0×2 / P1×9 / P2×13）：修掉远程分页总数快照失效、#expand 插槽静默丢弃两条 P0；CSV 导出公式注入中和 + 文件名消毒、CSV 解析重写为字符级状态机、校验错误按行稳定键跟随、分页除零与越界回收；spanMethod 覆盖判定从 O(n²m) 降到增量单遍（800 行挂载 ~11.5s → 2.56s）、auto 列宽批量测量（真机探针 19/19）、虚拟横切改二分、合并跨度极端输入归一。审查报告与分批执行记录见 docs/reviews/。

v0.2.1

• 🆕 新增 AI 组件: YdChatMessage 富消息、YdChatWelcome 欢迎屏、YdFeedbackButtons 反馈按钮、YdMessageActions 消息操作、YdConversationSidebar 会话列表、YdVoiceInput 语音输入、YdAudioMessage 语音消息、YdSourcePanel 来源面板、YdKnowledgeChip 知识库指示器
• 🎨 AI 组件视觉统一: 主色收敛为蓝色（#3b82f6/#2563eb）、去除玻璃拟态与冗余动效、状态图标改用 outline 描边风格、--yd-ai-* 语义化 Token
• 💬 Chat UI 重构: YdChatPage 三栏布局（侧边栏+会话+输入区）、大输入框+底部工具栏、#welcome/#header-right/#message 插槽
• ♻️ 图标收敛: 32+ 图标注册进 YdIcon 注册表，内联 SVG 统一替换为 <YdIcon>
• 🔒 安全加固: DOMPurify XSS 防护、URL 协议校验；markdown 高亮按需加载（highlight.js/lib/common）、流式渲染 50ms 防抖
• ♿ 无障碍增强: aria-hidden/aria-pressed/role 语义、focus-visible、prefers-reduced-motion
• 📖 文档: 上述 AI 组件文档与 VitePress 侧边栏同步

v0.1.58

• ♿ 全局无障碍修复（38+ 组件）: data-display, layout, feedback, base, navigation — 添加 role, tabindex, aria-label, aria-expanded, 键盘事件
• 🌙 暗色模式全面修复: themes.css neutral/semantic palette 暗色覆盖，flow-chart.css --fc-* 暗色覆盖，menu.css Glass 暗色覆盖
• 📱 响应式布局修复: shortcut-help-overlay, date-range-picker, notification 等6个组件添加 max-width 约束
• 🔧 CSS 质量修复: --yd-transition-normal bug 修复，4处重复规则清理，7处冗余 box-sizing 移除
• ♻️ Menu/Dropdown 优化: box-sizing 重置，a11y roles，Classic 布局响应式，transition 清理，z-index token 统一

v0.1.57

• 🐛 LoadingBar 单例模式修复: 修复 instance.start is not a function 错误，直接挂载组件替代包装组件
• 🐛 LoadingBar Pinia 修复: 修复 getActivePinia() was called but there was no active Pinia 错误
• 🐛 LoadingBar 组件状态修复: 添加 internalSize/internalColor 响应式变量，暴露 size/color getter/setter
• ♻️ Message 组件优化: 直接挂载组件，移除不必要的包装组件，更新 MessageInstance 接口
• ♻️ Modal 组件优化: 使用 defineComponent 创建 TempWrapper，新增 slots 生成函数，更新 ModalInstance 接口

v0.1.56

• 🐛 Form 尺寸传递修复: 修复 Form 组件 size 属性无法自动传递给子组件，25 个组件正确注入 Form 上下文
• 🐛 TreeSelect 虚拟滚动位置修复: 修复虚拟滚动模式下节点定位错误
• 🐛 TreeSelect 搜索结果未扁平化修复: 修复搜索模式下 filteredNodes 返回树结构而非扁平数组
• 🐛 TreeSelect 搜索时父级节点未自动展开: 搜索包含匹配子节点的父级节点现在会自动展开
• 🐛 TreeSelect 空状态显示修复: 搜索过滤后无匹配结果时正确显示空状态提示
• 🐛 TreeSelect 单选模式首次展开优化: 首次打开下拉框时只展开根节点
• ⚡ 搜索防抖优化: TreeSelect 和 Select 远程搜索防抖延迟从 300ms 降低至 150ms

v0.1.55

• 📝 版本号更新: 版本号更新至 v0.1.55
• ✅ 构建验证: vp check / vp build / vp pack / vp dev 全部验证通过
• 🔧 代码质量: 修复 use-login-form.ts 中未处理的 Promise 警告

v0.1.54

• 🔧 Markdown 组件全面增强: 新增工具栏、撤销重做、同步滚动、全屏、图片拖拽上传、字数统计、查找替换、Emoji、目录、导出打印、主题切换等 19 项功能
• ♻️ Markdown 工具栏 UI 对标优化: 工具栏按钮缩至 28px、移除边框阴影、单行布局、模式切换/全屏合并至顶部、修复 namespace 前缀 CSS 未生效问题
• 🔧 Menu 瀑布流布局增强: 新增 layout prop，支持 auto/classic/masonry 三种瀑布流布局算法
• 🔧 Login 组件方法暴露: YdLogin/YdLoginCentered 新增 refreshCaptcha() 和 resetForm() 方法
• 🐛 Dropdown 虚拟滚动修复: 修复虚拟滚动使用未注册 DropdownItem 组件的警告
• 🐛 useNamespace 方法补充: 新增 is() 和 em() 方法，修复 Markdown 组件 TypeError

v0.1.52

• 📝 版本号更新: 版本号更新至 v0.1.52
• ✅ 构建验证: vp check / vp build / vp pack / vp dev 全部验证通过

v0.1.51

• 🔧 FlowChart 流程图组件增强: 虚拟渲染 prop 控制激活、圆形布局根节点分布优化、Manhattan 全局路由算法实现
• 🔧 Form 表单组件增强: 新增表单标签布局支持、提交失败时滚动定位首个错误字段
• 🐛 FlowChart 修复: Toast 定时器清理、右键菜单 readonly 模式守卫、曼哈顿路由 A* 可达性修复
• ♻️ FlowChart 优化: 小地图节点缓存优化、提取共享 NodeBounds/computeExitEntry 至 utils
• ✅ 测试补充: 新增 context-menu / circular-layout / virtual-render 测试

v0.1.50

• 📝 版本号更新: 版本号更新至 v0.1.50
• ✅ 构建验证: vp check / vp build / vp pack / vp dev 全部验证通过

v0.1.49

• 📝 版本号更新: 版本号更新至 v0.1.49
• ✅ 构建验证: vp check / vp build / vp pack / vp dev 全部验证通过

v0.1.48

• 🔧 组件尺寸系统扩展：CheckboxGroup/DatePicker/DateRangePicker/TimePicker/PinInput 新增 size 属性，支持 mini/small/medium/large 四种尺寸
• 🔧 Rate 评分组件：图标大小改为根据尺寸自适应
• 🔧 Table 行高控制：新增 headerHeight 和 cellHeight 属性，支持数字或 CSS 字符串自定义表格行高
• ♻️ 输入框内边距 Token 优化：调整 --yd-input-padding-* 系列变量优化视觉比例
• 📦 依赖升级：happy-dom/marked/vite-plus/vue-i18n/vue-tsc 版本更新

v0.1.47

• 🔧 Empty 空状态组件增强：新增 title 标题、imageUrl 自定义图片、icon 自定义图标、imageStyle 图片样式，新增 success/warning/error 语义类型预设（带颜色）
• 🌐 国际化增强：新增 captcha.unavailable、empty.search/network/success/warning/error 翻译
• ♻️ 组件 i18n 优化：Button/Captcha/Cascader/DatePicker/TimePicker/Transfer/List 硬编码文案改用 i18n
• 📝 Empty 文档完善：新增类型预设、尺寸、自定义图片/图标、标题、操作按钮等示例

v0.1.46

• 🐛 TreeSelect 缓存修复：修复 visibleNodesCache 缓存问题，加入 nodesRef 追踪防止 stale slice
• 🐛 Table 虚拟滚动修复：虚拟模式使用固定 height 替代 maxHeight，修复虚拟滚动高度异常
• 🐛 List 虚拟滚动修复：虚拟模式使用固定 height 替代 maxHeight，修复虚拟滚动高度异常
• 🐛 Tree 组件全面审计：修复展开错乱、勾选传播、DFS 顺序、缓存失效、RAF 泄漏等 13 项问题

v0.1.45

• ♻️ Composables & Config Provider 优化：新增 usePopperPosition 组合式函数统一 Popper 位置计算，新增 BREAKPOINT_VALUES 断点常量
• ♻️ Table Composables 优化：15 个表格相关组合式函数全面优化（clipboard/column-resize/context-menu/export/filter/fixed/import/keyboard/selection/sort/tooltip/tree/validation/virtual）
• ♻️ 反馈组件优化：Popover / Tooltip / Popconfirm 统一重构使用 usePopperPosition

v0.1.42

• 📝 版本号更新: 版本号更新至 v0.1.42
• ✅ 构建验证: vp check / vp build / vp pack / vp staged 全部验证通过
• 🔍 TypeScript 类型检查: vue-tsc --noEmit 零错误通过

v0.1.41

• 🆕 新增 BackTop 返回顶部组件 (YdBackTop)：支持 height/bottom/right/duration/target 配置，平滑滚动动画（easeInOutCubic + requestAnimationFrame），可指定滚动容器，暴露 back/scrollToTop/visible 方法
• 🏗️ 新增 Popper 定位系统：抽取 use-popper + popper-position 组合式函数，Tooltip / Popover / Popconfirm 统一重构复用，移除冗余定位逻辑，提升定位精度与可维护性
• 🌗 系统级暗色模式：themes.css 新增 @media (prefers-color-scheme: dark)，未显式设置 data-theme 时跟随操作系统暗色偏好（纯 CSS、SSR 安全）
• 🔒 Markdown 安全增强：移除 DOMPurify 配置中的 target 属性，防御 target="_blank" 标签页劫持（tabnabbing），同步更新 markdown-security.test.ts
• ✅ 测试补充：新增 back-top、use-popper、popper-position 单元测试

v0.1.32

• ContextMenu 增强: 鼠标悬停自动展开子菜单，单子菜单同时只展开一个
• Watermark SSR 兼容: Canvas 懒加载，zIndex 默认值改为 9999
• 事件监听迁移: DateRangePicker/DatePicker/TimePicker/Watermark 统一迁移至 onEvent 注册表
• Table 展开行修复: expandedRows Set 每次变更创建新实例确保 Vue 响应式追踪
• 构建优化: vite manualChunks 路径修复、oxlint 规则增强、CI 新增 validate 步骤
• 工具函数: tree-utils mapTree 迭代式后序遍历、crypto HMAC 简化
• Bug 修复: Tree expandedRows 响应式、Watermark SSR 报错、ContextMenu 交互、vite 路径

v0.1.31

• Watermark 防篡改: MutationObserver 监听防止水印被删除/修改，图片加载失败自动回退文本
• Tree 优化: TreeNode 新增 level 属性，use-tree-data 递归改迭代
• TypeScript 类型修复: Input/Radio/TreeSelect/Form/Layout/Menu/Chart 等全面类型修复
• 事件监听优化: DatePicker/TimePicker/DateRangePicker 统一使用 onEvent
• Bug 修复: Watermark 图片回退、Form pattern 校验、TreeSelect level undefined、表格粘贴 NaN

v0.1.30

• 组件优化: Select 虚拟滚动、Markdown 独立实例、Icon XSS 安全验证、ConfigProvider 内存泄漏修复、Drawer/Modal/Notification i18n
• 工具函数增强: debounce 新增 cancel/flush、deepClone 循环引用检测、tree-utils 递归改迭代
• 类型增强: DeepPartial/DeepRequired/DeepReadonly/DeepFrozen 正确处理 Builtin 类型
• 安全: Resolver 对齐 unplugin-vue-components 标准接口，crypto 密钥缓存 SHA-256 哈希
• 国际化: 新增 drawer/notification/tabs 语言键
• 样式: 新增 Login 渐变主题 CSS 变量
• 配置优化: sideEffects 新增 locales，oxlintrc 规则优化

v0.1.28

• 项目配置优化: 修复 README 中 dist/index.mjs 引用，修复 VitePress 页脚版权年份，清理 Windows nul 伪文件
• 构建验证: vp check/vp build/vp pack/vp staged 验证通过

v0.1.27

• 组件库配置优化: 新增 subpath exports 支持按模块独立引入（components/composables/utils/types/resolver），ESM+CJS 双格式输出，DTS 类型自动生成
• 测试配置: 新增 vitest 测试配置及 80% 覆盖率阈值
• 文档更新: README 新增按模块引入示例，Bundle 信息更新
• 依赖升级: vite-plus 0.2.1, happy-dom 20.10.6, oxc-minify 0.137, vue 3.5.38

v0.1.26

• Bug 修复: 修复 Captcha、Cascader、Icon、Markdown、Select、Upload、Image、Watermark、ContextMenu 等多个组件报错问题
• 国际化: 新增 en-US.json 和 zh-CN.json 语言包
• 功能增强: 保存 size 配置和 tabs 显示功能，size 格式化优化
• 文档更新: CHANGELOG、README、VitePress 首页版本记录更新

v0.1.25

• 版本更新: 版本号更新至 v0.1.25
• 文档更新: CHANGELOG、README、VitePress 首页版本记录更新

v0.1.24

• Table 增强: 新增列筛选、列拖拽、列宽调整、单元格 tooltip、全选功能
• Tree 增强: 重构配置结构，新增键盘导航、更多插槽、条纹/边框样式
• CrudPage 增强: 重新设计按钮布局，新增筛选条件折叠/展开功能
• 组件优化: Chart、Menu、Tabs、LoadingBar 等组件优化

v0.1.23

• 版本更新: 版本号更新至 v0.1.23
• 文档更新: CHANGELOG、README、VitePress 首页版本记录更新

v0.1.22

• 版本更新: 版本号更新至 v0.1.22
• 文档更新: CHANGELOG、README、VitePress 首页版本记录更新

v0.1.21

• 版本更新: 版本号更新至 v0.1.21
• 文档更新: CHANGELOG、README、VitePress 首页版本记录更新

v0.1.20

• 版本更新: 版本号更新至 v0.1.20
• 文档更新: CHANGELOG、README、VitePress 首页版本记录更新

v0.1.19

• 版本更新: 版本号更新至 v0.1.19
• 文档更新: CHANGELOG、README、VitePress 首页版本记录更新

v0.1.18

• 版本更新: 版本号更新至 v0.1.18
• 文档更新: CHANGELOG、README、VitePress 首页版本记录更新

v0.1.17

• 版本更新: 版本号更新至 v0.1.17
• 文档更新: CHANGELOG、README、VitePress 首页版本记录更新

v0.1.16

• 版本更新: 版本号更新至 v0.1.16
• 文档更新: 文档审查更新，各组件说明文档完善
• 新文档: Popover 弹出框、LayoutFooter 底部布局文档
• 构建验证: vp check/vp build/vp pack/vp staged 验证通过

v0.1.15

• 版本更新: 版本号更新至 v0.1.15
• 构建验证: vp check/vp build/vp pack/vp staged 验证通过

v0.0.1

• release: 版本号更新至 v0.0.1
• enhancement: 优化构建配置

v0.1.12

• release: 版本号更新至 v0.1.12
• enhancement: 优化构建配置

v0.1.11

• release: 版本号更新至 v0.1.11
• enhancement: 优化构建配置

v0.1.12

• enhancement: 版本更新至 v0.1.12
• refactor: 优化构建配置和组件导出

v0.1.9

• feat(AI Chat): AI 聊天页面组件 (YdChatPage) - 支持会话列表、模型选择、流式输出
• docs: ChatPage 组件文档
• docs: VitePress sidebar 新增 ChatPage
• docs: README.md 新增 AI 组件列表

v0.1.8

• feat(secureStorage): 支持 localStorage 和 sessionStorage 分别设置不同密钥
• fix: 修复报错问题
• enhancement: 优化说明文档
• feat: 登录控件优化，增强用户体验
• feat: 增加侧边栏控件，支持更灵活的布局配置
• feat: 增加懒加载和优化轮询机制，提升性能
• enhancement: 优化整体介绍和文档
• feat: 增加整体效果展示组件
• feat: 虚拟滚动等性能优化
• enhancement: 暂存优化，改进数据缓存

v0.1.7

• feat: 安全存储插件 (AES-GCM) 支持敏感数据加密存储

v0.1.6

• feat: 多语言支持 (i18n)

v0.1.5

• feat: 虚拟滚动表格组件

v0.0.1

• feat: 初始版本发布

v0.1.4

• feat: 初始版本发布

🔗 相关链接

• Vue 3 文档
• Vite+ 文档
• AsyncValidator

📄 License

MIT

☕ 赞助支持

如果这个项目对你有帮助，欢迎赞助支持，让我们持续维护下去 ❤️