Appearance
组件系统
沈孟平
最后更新于 2026-04-23 19:53:53
本模板的通用组件统一存放在 components 目录下，它是单独的一个子包，支持独立构建并发布。 并且本模板的组件均基于 Naive UI 进行封装，样式系统采用 unocss，所以暂不支持样式的 tree shaking。
组件地图
这套组件库不是对 Naive UI 的逐个镜像封装，而是围绕中后台高频场景做的“业务增强版”组件。可以按下面的方式理解：
| 分类 | 代表组件 | 主要解决的问题 |
|---|---|---|
| 页面骨架 | AtPageContainer、AtPageHeader、AtTitle | 页面结构统一、标题区一致、内容区滚动边界清晰 |
| 数据录入 | AtForm、AtSearch、AtUpload、AtCronInput | 声明式表单、搜索栏、上传、Cron 表达式输入 |
| 复杂选择 | AtTreeFilter、AtMultipleFilter、AtComplexSelector | 树状筛选、多级标签筛选、组织/人员等复杂层级选择 |
| 数据展示 | AtTable、AtPagination、AtEmpty、AtLoading、AtIconMsg | 列表请求、分页、空状态、加载态、结果反馈 |
| 容器与交互 | AtModal、AtConfirm、AtExpandTransition、AtConfigProvider | 弹窗、二次确认、折叠动画、全局配置 |
| 编辑与协议 | AtMonacoEditor、AtMonacoDiffEditor、AtSchemaGenerator | 代码编辑、Diff 对比、JSON Schema 可视化配置 |
| 视觉与辅助 | AtIcon、AtIconBtn、AtLink、AtRuler | 图标、图标按钮、链接增强、标尺辅助 |
推荐先看哪些组件
如果你想快速建立对这个组件库的理解，建议优先阅读下面几页：
- AtForm：很多高阶组件的基础能力都来自这里。
- AtSearch：本质是搜索场景下的
AtForm。 - AtTable：负责列表页最核心的数据请求、分页、排序、列配置。
- AtModal：弹窗编辑、查看详情等场景的统一容器。
- AtConfigProvider：统一表格、弹窗和 Monaco 相关的全局行为。
常见组合方式
- 列表页：
AtPageContainer + AtSearch + AtTable - 表单弹窗：
AtModal + AtForm - 复杂人员/组织选择：
AtComplexSelector或AtTreeFilter - 协议/字段配置：
AtSchemaGenerator + AtMonacoEditor - 全局兜底：根节点挂载
AtConfigProvider
如何使用
- 安装
bash
ni @gupo-admin/components- 在
main.ts中引入全局样式
ts
import '@gupo-admin/components/style.css'- 按需引入组件使用即可，也可以配置
unplugin-vue-components插件实现组件的自动引入
ts
Components({
dts: './types/components.d.ts',
dirs: ['src/components'],
extensions: ['vue', 'tsx', 'jsx'],
resolvers: [NaiveUiResolver(), (name: string) => {
if (name.startsWith('At')) {
return { name, from: '@gupo-admin/components' }
}
}],
}),子入口
除了组件主入口，组件库还提供独立的 hooks 和 utils 子入口：
ts
import { useRequest } from '@gupo-admin/components/hooks'
import { opacityColor } from '@gupo-admin/components/utils'依赖说明
- 组件内部基于
vue、naive-ui、@vueuse/core等能力构建。 monaco-editor相关组件需要确保项目已安装对应 peer dependency，并按文档完成初始化。- 组件库默认输出
es模块和类型声明，适合在 Vite 项目中直接使用。