Appearance
taibai CLI
把组件源码拷进你的项目,你拥有全部代码,随便改。 思路参考 shadcn/ui,基于 element-plus。
快速开始
全局安装(可选)
bash
1. 安装
npm install -g taibai@latest
2. 验证安装是否成功
taibai --version
# 或者
taibai -v
3. 运行你的命令
taibai list
4. 卸载
npm uninstall -g taibai⚠️ 常见问题排查:权限错误 (EACCES),Mac 上执行 sudo npm install -g taibai@latest。
不想全局安装的话,所有命令都用 npx taibai@latest 跑,下面示例统一用这种写法。
1. 初始化项目(每个项目只做一次)
bash
cd your-vue-project
npx taibai@latest init直接回车用默认值即可,组件会放到 src/components/widgets/,初始化时可改成 src/components。 配置写在项目根目录的 taibai.json:
json
{
"componentsDir": "src/components",
"alias": "@"
}2. 查看可用内容
bash
npx taibai@latest list会列出指令、样式、工具函数,以及业务组件库里全部 23 个组件。
3. 添加
bash
# 单个
npx taibai@latest add ProEmpty
# 多个
npx taibai@latest add ProEmpty Pagination TypeWriter
# 业务组件库全部
npx taibai@latest add all- 组件落地到
<componentsDir>/<组件目录>/,多文件组件整目录拷入(如Grid/含index.vue与components/); - 组件内部用
@/components/...互相引用,安装时自动改写成你的alias前缀,拷过去就能跑; - 若还缺
src/utils、src/hooks等支撑目录,CLI 会提示,补一句add all最省事。
4. 在 vue 文件里直接用
vue
<script setup>
import ProEmpty from '@/components/ProEmpty/index.vue'
import Pagination from '@/components/Pagination/index.vue'
</script>
<template>
<ProEmpty />
<Pagination v-model:current-page="page" v-model:page-size="size" :total="100" />
</template>拷过去的文件就是你的,打开改样式、改逻辑都行。
组件全览(23 个)
taibai 提供 23 个业务组件,全部是源码拷贝:装进项目后就是你自己的文件,改样式、改逻辑都不受约束。
安装名默认与目录名一致,命令写 ProTable 或 pro-table 都可以;CLI 不兼容旧名,add 只认当前目录名。
| 分类 | 安装命令 | 说明 |
|---|---|---|
| 展示 | taibai add TypeWriter | 打字机逐字输出(自带 atoms.css;旧名:AiText) |
| 展示 | taibai add ImageViewer | 图片缩放查看(旧名:imgView) |
| 展示 | taibai add KeywordHighlighter | 关键字高亮 |
| 展示 | taibai add ProEmpty | 空状态占位(基于 element-plus;旧名:NoData) |
| 展示 | taibai add Captcha | 图形验证码(旧名:ValidCode) |
| 展示 | taibai add VideoPlayer | 视频播放器 |
| 布局 | taibai add EditPage | 编辑页骨架 |
| 布局 | taibai add Grid | 响应式栅格(含 components/GridItem.vue、interface/index.ts) |
| 表单 | taibai add BasisForm | 配置化表单(含 index.scss、interface/index.ts) |
| 表单 | taibai add ProFormControl | 表单控件封装,12 个:input / input-number / select / cascader / date / switch / radio / radio-button / checkbox / checkbox-button / checkbox-select / tree-select(旧名:Control) |
| 表单 | taibai add SearchForm | 搜索条件区(含 components/SearchFormItem.vue) |
| 表单 | taibai add SelectFilter | 分类筛选器(含 index.scss) |
| 数据 | taibai add BasisDetail | 详情容器 + 描述列表(index.vue + descriptions.vue) |
| 数据 | taibai add BasisTable | CRUD 表格(含 4 个 components/ 子文件) |
| 数据 | taibai add Pagination | 分页器,基于 element-plus |
| 数据 | taibai add ProTable | 高级表格(含 components/、interface/index.ts) |
| 弹层 | taibai add ProDialog | 可拖拽全屏弹窗(旧名:Dialog) |
| 弹层 | taibai add Message | 站内消息 + WebSocket |
| 弹层 | taibai add Preview | 附件预览(index.vue、single.vue、viewDialog.vue) |
| 文件 | taibai add Upload | 图片 / 文件上传(含 Img.vue、Imgs.vue、file.vue、copyFile.vue、upload.ts) |
| 业务 | taibai add UserInfo | 改密码 / 改资料 |
| 业务 | taibai add UserSelect | 选人 / 选部门 |
| 状态页 | taibai add ErrorMessage | 403 / 404 / 500 |
组件默认基于 element-plus,用到表格、分页、弹层的组件需要项目里已安装 element-plus 并注册了对应组件。
组件命名规范
组件名 = 依赖层级前缀 + 语义后缀。前缀回答“它依赖什么”,后缀写清“它是什么”,看名字就能判断安装成本。
| 前缀 | 定位 | 依赖 | 示例 |
|---|---|---|---|
Pro | 依赖 UI 组件库 | element-plus 等第三方 UI 库 | ProEmpty(空状态,基于 el-empty)、ProTable |
Biz | Business,业务组件 | 业务接口、路由、权限、登录态 | BizEmpty(如 UserSelect、Message) |
App | 平台级组件 | 平台壳、布局、主题、多端适配 | AppEmpty(如布局壳、路由壳) |
Basic | 基础但功能完整 | 不依赖第三方库,可依赖自写组件 | BasicEmpty(如 BasisForm、BasisTable) |
| 无前缀 | 最基础 | 不依赖组件库或自写组件 | Empty(如 Icon) |
约定:
- 先看依赖,再看语义:能独立成立的最基础件用无前缀;一旦引入 element-plus 等 UI 库,就升到
Pro。 - 带业务语义(接口、权限、组织架构)用
Biz;平台能力(布局、路由壳、主题)用App。 - 前缀只表达依赖层级,后半只表达用途,不要叠加两个前缀(
ProBizXxx不推荐)。 - 改名时同步更新目录、
scripts/copy-components.mjs的META、CLI 清单和文档;命令只认新名,不保留旧名别名。 - 本次改名示例:
NoData→ProEmpty,因为它依赖 element-plus 的el-empty;ProTable、BasisForm等历史命名保持不动,新组件按本规范起名。
组件使用
23 个组件逐个展开,每个组件都按 安装 → 使用 → 属性 → 扩展 四步写。
通用规则只说一次:命令名就是目录名(ProTable 或 pro-table 都认),文件拷到 <componentsDir>/<组件目录>/,多文件组件整目录拷入;组件内部的 @/components/... 引用会按 taibai.json 里的 alias 改写,装完直接 import 就能跑;目标文件已存在时会询问是否覆盖,默认不覆盖。组件基于 element-plus,用到表格、弹窗、分页的组件需要项目里已安装并注册了对应组件。
打字机TypeWriter
展示 · 打字机逐字输出,可重播。
安装
bash
npx taibai@latest add TypeWriter落地 src/components/TypeWriter/:
text
TypeWriter/
├── index.vue # 组件本体:props、逐字逻辑、光标
└── atoms.css # 组件自带的 10 条原子声明,由 <style src> 自动挂载单装 TypeWriter 不需要另外引 nexus.css。
使用
vue
<script setup>
import TypeWriter from '@/components/TypeWriter/index.vue'
</script>
<template>
<TypeWriter title="<p>你好,我是 taibai 的打字机组件。</p>" :type-speed="30" :delay="300" />
</template>title 走 v-html,可以写 HTML;标签不会被逐字打出来,只对文本逐字输出。
属性
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
title | string | 必填 | 要输出的内容,允许 HTML 字符串 |
typeSpeed | number | 30 | 每个字符的间隔毫秒数,越大越慢 |
delay | number | 300 | 开始输出前的等待毫秒数 |
Expose:
| 名称 | 类型 | 说明 |
|---|---|---|
isTyping | Ref<boolean> | 是否正在输出;默认 false,光标不显示 |
startTyping | () => Promise<void> | 从第一个字符重新开始输出 |
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 光标颜色、闪烁节奏 | atoms.css 的 .anim-cursor-blink |
| 光标与文字的间距 | atoms.css 的 .mglf2(当前 2px) |
| 换行、行高、断词 | index.vue 模板上的 leading-1-6、break-words 等原子类 |
| 打字速度、输出逻辑 | index.vue 的 typeText,或外面传 typeSpeed |
图片查看ImageViewer
展示 · 图片查看器,带缩放工具栏。
安装
bash
npx taibai@latest add ImageViewer落地 src/components/ImageViewer/:index.vue、atoms.css。
使用
vue
<script setup>
import ImageViewer from '@/components/ImageViewer/index.vue'
</script>
<template>
<ImageViewer src="/files/photo.png" />
</template>组件占满父容器(w-full h-full),父级需要有确定高度;顶部工具栏可缩小 / 放大,点中间百分比回到 100%。
属性
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
src | string | 必填 | 图片地址 |
无事件、无 Expose。
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 缩放上下限 | index.vue 的 MIN_IMAGE_SCALE / MAX_IMAGE_SCALE |
| 工具栏按钮、提示文案 | index.vue 的 <template> |
| 容器布局、图片样式 | atoms.css 与模板上的原子类 |
文字高亮KeywordHighlighter
展示 · 关键字高亮。
安装
bash
npx taibai@latest add KeywordHighlighter落地 src/components/KeywordHighlighter/:index.vue。
使用
vue
<script setup>
import KeywordHighlighter from '@/components/KeywordHighlighter/index.vue'
</script>
<template>
<KeywordHighlighter
content="taibai 是一个源码拷贝式的 Vue 组件库"
keywords="taibai,Vue,组件"
color="#f56c6c"
/>
</template>keywords 用英文逗号分隔,匹配不区分大小写,内部会先转义正则元字符,不能传正则。
属性
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
content | string | 必填 | 要展示的整段文本 |
keywords | string | null | "" | 关键字,逗号分隔 |
color | string | — | 高亮文字颜色 |
无事件、无 Expose。
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 匹配规则(分隔符、整词/模糊) | index.vue 里 keywords 的 split(",") 与 RegExp 构造 |
| 高亮样式 | index.vue 里的 span 样式或改用原子类 |
空状态ProEmpty
展示 · 空状态占位,基于 el-empty。
安装
bash
npx taibai@latest add ProEmpty落地 src/components/ProEmpty/:index.vue。
组件内置图片走 @/assets/images/notData.png,只装组件时若项目里没有这张图,需要自己放一份(add all 会补 assets)。
使用
vue
<script setup>
import ProEmpty from '@/components/ProEmpty/index.vue'
</script>
<template>
<ProEmpty />
<ProEmpty description="还没有任何记录" />
</template>属性
组件本身不声明 props,模板上 v-bind="$attrs" 直接透传给 el-empty,description、image、image-size 等 element-plus 属性都能用;默认 description="暂无数据"、image-size="120"。
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 默认文案、图片、尺寸 | index.vue 的 el-empty |
| 想换插画 | 替换 @/assets/images/notData.png,或传 image |
验证码Captcha
展示 · 图形验证码,点击刷新。
安装
bash
npx taibai@latest add Captcha落地 src/components/Captcha/:index.vue、atoms.css。
使用
vue
<script setup>
import Captcha from '@/components/Captcha/index.vue'
</script>
<template>
<Captcha :length="4" :width="120" :height="40" />
</template>验证码由组件内部随机生成,点一下换一张。当前实现不对外抛出验证码值、也没有 Expose,需要拿值做校验时得改源码补 defineExpose 或 emit。
属性
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value | string | — | 预留字段,当前生成逻辑未使用 |
length | number | 4 | 验证码字符个数 |
back | string | — | 预留背景色字段 |
width | number | 120 | 宽度(px) |
height | number | 40 | 高度(px) |
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 字符集 | index.vue 的 arrall 数组 |
| 背景色 | index.vue 的 getCode 里 RGB 随机逻辑 |
| 字号、颜色、圆角 | index.vue 模板上的 font24、radius4 等原子类 |
| 对外暴露验证码 | 在 index.vue 加 defineExpose({ codevalue }) |
视频播放VideoPlayer
展示 · 视频播放器,自带控制条。
安装
bash
npx taibai@latest add VideoPlayer落地 src/components/VideoPlayer/:index.vue。
使用
vue
<script setup>
import { ref } from 'vue'
import VideoPlayer from '@/components/VideoPlayer/index.vue'
const player = ref()
</script>
<template>
<VideoPlayer ref="player" video-source="/files/demo.mp4" poster="/files/cover.jpg" />
<button @click="player?.reset()">重播</button>
</template>原生 controls 是关掉的,播放 / 进度 / 音量都在组件内部实现;点画面本身也能播放、暂停。
属性
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
videoSource | string | 必填 | 视频地址 |
poster | string | "" | 封面图 |
autoplay | boolean | false | 是否自动播放 |
loop | boolean | false | 是否循环 |
initialVolume | number | 80 | 初始音量(0–100) |
Expose:
| 名称 | 类型 | 说明 |
|---|---|---|
reset | () => void | 回到开头并重置播放状态 |
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 控制条、加载态 | index.vue 的 <template> |
| 音量、进度逻辑 | index.vue 的 handleLoadedMetadata / togglePlayPause |
| 容器尺寸与样式 | index.vue 底部的样式块 |
编辑页EditPage
布局 · 编辑页骨架,正文滚动 + 底部操作条。
安装
bash
npx taibai@latest add EditPage落地 src/components/EditPage/:index.vue。
使用
vue
<script setup>
import EditPage from '@/components/EditPage/index.vue'
</script>
<template>
<EditPage>
<el-form label-width="100px">
<!-- 表单内容 -->
</el-form>
<template #submitLeft>
<el-button>返回</el-button>
</template>
<template #submit>
<el-button type="primary">保存</el-button>
</template>
</EditPage>
</template>属性
组件不声明 props,全部通过插槽填充:
| 插槽 | 说明 |
|---|---|
default | 正文区,放在 el-scrollbar 里,超出滚动 |
submitLeft | 底部操作条左侧 |
submit | 底部操作条右侧 |
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 底部条布局、间距 | index.vue 的 .submit 与 flx-between |
| 正文区高度策略 | index.vue 根节点的 height: 100% / flx-1 |
栅格Grid
布局 · 响应式栅格。
安装
bash
npx taibai@latest add Grid落地 src/components/Grid/:
text
Grid/
├── index.vue # 栅格容器
├── components/GridItem.vue # 栅格子项
└── interface/index.ts # BreakPoint / Responsive 类型使用
vue
<script setup>
import Grid from '@/components/Grid/index.vue'
import GridItem from '@/components/Grid/components/GridItem.vue'
</script>
<template>
<Grid :cols="{ xs: 1, sm: 2, lg: 3 }" :gap="[16, 16]">
<GridItem>第一块</GridItem>
<GridItem :span="2">跨两列</GridItem>
</Grid>
</template>属性
Grid:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
cols | number | Record<BreakPoint, number> | { xs: 1, sm: 2, md: 2, lg: 3, xl: 4 } | 各断点下的列数 |
collapsed | boolean | false | 是否收起超出行数的内容 |
collapsedRows | number | 1 | 收起时保留几行 |
gap | number[] | number | 0 | 间距,数字或 [水平, 垂直] |
Expose:breakPoint(当前断点)。
GridItem 常用 props:span(默认 1)、offset(默认 0)、suffix(默认 false)、xs / sm / md / lg / xl(各断点单独覆盖)。
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 断点阈值 | Grid/interface/index.ts 与 index.vue 的断点判断 |
| 子项跨列、响应式覆盖 | Grid/components/GridItem.vue |
| 折叠交互 | index.vue 的 collapsed / collapsedRows 逻辑 |
配置表单BasisForm
表单 · 配置化表单,按 item 数组渲染控件。
安装
bash
npx taibai@latest add BasisForm落地 src/components/BasisForm/:
text
BasisForm/
├── index.vue # 表单容器,内部按 el 字段匹配 ProFormControl 下的控件
├── index.scss # 表单样式
└── interface/index.ts # BasisFormProps / FormItemPropsBasisForm 依赖 ProFormControl/ 下的控件,单装表单时需要一并装:npx taibai@latest add BasisForm ProFormControl。
使用
vue
<script setup>
import { reactive, ref } from 'vue'
import BasisForm from '@/components/BasisForm/index.vue'
const formRef = ref()
const field = reactive({ name: '', status: 1 })
const item = [
{ el: 'input', label: '姓名', prop: 'name', required: true },
{ el: 'select', label: '状态', prop: 'status', options: [{ label: '启用', value: 1 }] }
]
const submit = async () => {
await formRef.value?.handlerFormValidate()
}
</script>
<template>
<BasisForm ref="formRef" :item="item" :field="field" label-width="100px" />
</template>属性
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
title | string | — | 表单标题 |
item | FormItemProps[] | 必填 | 表单项配置,字段见 interface/index.ts |
field | Record<string, any> | 必填 | 表单数据对象,字段与 prop 对应 |
hidden | Record<string, boolean> | {} | 按字段名控制隐藏 |
disabledCol | Record<string, boolean> | {} | 按字段名控制禁用 |
cols | number | Record<BreakPoint, number> | — | 栅格列数,可响应式 |
gap | number[] | number | [100, 0] | 栅格间距 |
labelWidth | string | number | 160 | 标签宽度 |
labelPosition | "left" | "right" | "top" | "top" | 标签位置 |
Expose:
| 名称 | 说明 |
|---|---|
handlerFormValidate | 触发表单校验 |
handlerFormReset | 重置表单 |
formRef | 内部 el-form 实例 |
handlerFormField | 按字段处理(详见 index.vue) |
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 表单项支持哪些字段 | interface/index.ts 的 FormItemProps |
| 新增控件类型 | 在 ProFormControl/ 下加目录,index.vue 通过 ../ProFormControl/**/index.vue 自动收集 |
| 表单样式 | index.scss |
表单控件ProFormControl
表单 · 12 个控件封装,供 BasisForm 使用,也能单独用。
安装
bash
npx taibai@latest add ProFormControl落地 src/components/ProFormControl/,12 个子目录各一个 index.vue:
text
ProFormControl/
├── input/ input-number/ select/
├── cascader/ date/ switch/
├── radio/ radio-button/ checkbox/
├── checkbox-button/ checkbox-select/ tree-select/使用
vue
<script setup>
import { reactive } from 'vue'
import ControlInput from '@/components/ProFormControl/input/index.vue'
import ControlSelect from '@/components/ProFormControl/select/index.vue'
const form = reactive({ name: '', status: '' })
const nameConfig = { el: 'input', label: '姓名', prop: 'name' }
const statusConfig = { el: 'select', label: '状态', prop: 'status', options: [] }
</script>
<template>
<ControlInput v-model:value="form.name" :config="nameConfig" />
<ControlSelect v-model:value="form.status" :config="statusConfig" />
</template>每个控件都是对 element-plus 对应组件的轻封装:config 里的属性会 v-bind 透传给内部 el-*。
属性
所有 12 个控件的 props 一致:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value | 视控件而定 | — | 当前值 |
config | FormItemProps | 必填 | 控件配置,透传给内部 el-* |
事件:
| 事件 | 参数 | 说明 |
|---|---|---|
update:value | value: any | 值变化,配合 v-model:value |
callback | { value, config } | 值变化回调,带上当前配置 |
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 某个控件的默认行为 | 对应目录下的 index.vue |
| 新增控件类型 | 新建 ProFormControl/<name>/index.vue,BasisForm 会自动收集 |
| 透传哪些属性 | 各控件模板上的 v-bind="config" |
搜索表单SearchForm
表单 · 搜索条件区,由列配置生成查询表单。
安装
bash
npx taibai@latest add SearchForm落地 src/components/SearchForm/:index.vue、components/SearchFormItem.vue。
使用
vue
<script setup>
import { reactive } from 'vue'
import SearchForm from '@/components/SearchForm/index.vue'
const searchParam = reactive({ name: '' })
const columns = [{ prop: 'name', label: '姓名', search: { el: 'input' } }]
const handleSearch = params => console.log('查询', params)
const handleReset = params => console.log('重置', params)
</script>
<template>
<SearchForm
:columns="columns"
:search-param="searchParam"
:search-col="{ xs: 1, sm: 2, lg: 3 }"
:search="handleSearch"
:reset="handleReset"
/>
</template>search / reset 是函数 props,由组件内部在点按钮时调用,不是 emit。
属性
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
columns | ColumnProps[] | [] | 列配置,search 字段决定搜索项 |
searchParam | Record<string, any> | {} | 搜索参数对象 |
searchCol | number | Record<BreakPoint, number> | 必填 | 搜索区列数 |
search | (params: any) => void | 必填 | 点查询时调用 |
reset | (params: any) => void | 必填 | 点重置时调用 |
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 单个搜索项的渲染 | components/SearchFormItem.vue |
| 列配置支持哪些字段 | ProTable/interface/index.ts 的 ColumnProps / SearchProps |
| 按钮与布局 | index.vue 的模板 |
分类筛选SelectFilter
表单 · 分类筛选器,适合列表页顶部的多组条件。
安装
bash
npx taibai@latest add SelectFilter落地 src/components/SelectFilter/:index.vue、index.scss。
使用
vue
<script setup>
import { ref } from 'vue'
import SelectFilter from '@/components/SelectFilter/index.vue'
const data = [
{
title: '状态',
key: 'status',
multiple: false,
options: [
{ label: '启用', value: 1 },
{ label: '停用', value: 0 }
]
}
]
const onChange = value => console.log(value)
</script>
<template>
<SelectFilter :data="data" :default-values="{ status: 1 }" @change="onChange" />
</template>属性
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
data | SelectDataProps[] | [] | 筛选项,含 title / key / options / multiple / tooltip |
defaultValues | Record<string, any> | {} | 各筛选项默认值,按 key 对应 |
labelPosition | string | "left" | 标题位置,top 或 left |
事件:
| 事件 | 参数 | 说明 |
|---|---|---|
change | value: any | 任一筛选项变化,返回当前全部选中值 |
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 筛选项结构 | index.vue 的 SelectDataProps |
| 下拉、标签样式 | index.scss |
| 自定义筛选项渲染 | index.vue 的默认插槽 |
描述列表BasisDetail
数据 · 详情容器 + 描述列表。
安装
bash
npx taibai@latest add BasisDetail落地 src/components/BasisDetail/:index.vue、descriptions.vue。
使用
vue
<script setup>
import { reactive } from 'vue'
import BasisDetail from '@/components/BasisDetail/index.vue'
const detail = reactive({ name: '张三', status: '启用' })
const item = [
{ label: '姓名', prop: 'name' },
{ label: '状态', prop: 'status' }
]
</script>
<template>
<BasisDetail title="基本信息" :item="item" :field="detail" :cols="2" />
</template>属性
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
title | string | — | 区块标题 |
item | any[] | 必填 | 描述项配置(label / prop 等) |
field | Record<string, any> | 必填 | 数据对象 |
hidden | Record<string, boolean> | {} | 按字段隐藏 |
disabled | Record<string, boolean> | {} | 按字段禁用 |
cols | number | Record<BreakPoint, number> | — | 每行列数 |
gap | number[] | number | [50, 0] | 间距 |
labelWidth | string | number | 160 | 标签宽度 |
labelPosition | "left" | "right" | "top" | "top" | 标签位置 |
默认插槽用于自定义字段内容。
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 描述项渲染 | descriptions.vue |
| 字段配置 | index.vue 的 props 与 item 结构 |
| 标签宽度、布局 | 传 labelWidth / cols / labelPosition |
基础表格BasisTable
数据 · CRUD 表格,编辑弹窗由列配置生成。
安装
bash
npx taibai@latest add BasisTable落地 src/components/BasisTable/:
text
BasisTable/
├── index.vue
└── components/
├── TableColumn.vue FormDialog.vue
└── FormItem.vue ColSetting.vue使用
vue
<script setup>
import { ref } from 'vue'
import BasisTable from '@/components/BasisTable/index.vue'
const tableRef = ref()
const columns = [
{ prop: 'name', label: '姓名' },
{ prop: 'status', label: '状态' }
]
const data = ref([{ id: 1, name: '张三', status: '启用' }])
</script>
<template>
<BasisTable ref="tableRef" :columns="columns" :data="data" title="用户列表" />
</template>type="dialog" 时增删改走弹窗表单;type="row" 时在行内编辑。
属性
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
type | "dialog" | "row" | "dialog" | 编辑方式 |
columns | any[] | 必填 | 列配置 |
data | any[] | 必填 | 表格数据 |
title | string | — | 表格标题 |
border | boolean | true | 是否显示纵向边框 |
toolButton | boolean | false | 是否显示工具栏 |
rowKey | string | "id" | 行唯一键 |
isView | boolean | false | 只读模式 |
defaultValue | Record<string, any> | {} | 新增时的默认值 |
dialogConfig | Record<string, any> | {} | 弹窗配置 |
isAdd | boolean | true | 是否允许新增 |
dialogAddHandle | (row: any) => void | — | 新增回调 |
dialogEditHandle | (row: any, index: number) => void | — | 编辑回调 |
Expose:element(el-table 实例)、enumMap、handlerFormValidate。
插槽:toolButton(工具栏)、默认插槽(列内容)、append、empty。
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 编辑弹窗表单 | components/FormDialog.vue、FormItem.vue |
| 列渲染、列设置 | components/TableColumn.vue、ColSetting.vue |
| 新增 / 编辑流程 | index.vue 的 dialogAddHandle / dialogEditHandle |
分页器Pagination
数据 · 分页器,基于 element-plus。
安装
bash
npx taibai@latest add Pagination落地 src/components/Pagination/:index.vue、atoms.css。
使用
vue
<script setup>
import { ref } from 'vue'
import Pagination from '@/components/Pagination/index.vue'
const page = ref(1)
const size = ref(10)
const total = ref(100)
const onPage = payload => console.log(payload)
</script>
<template>
<Pagination
v-model:current-page="page"
v-model:page-size="size"
:total="total"
@pagination="onPage"
/>
</template>属性
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
currentPage | number | 1 | 当前页,支持 v-model:current-page |
pageSize | number | 10 | 每页条数,支持 v-model:page-size |
total | number | 必填 | 总条数 |
size | string | 'default' | 尺寸 |
layout | string | 'total, sizes, prev, pager, next, jumper, ->' | 分页布局 |
pageSizes | number[] | [10, 20, 30, 100] | 可选每页条数 |
disabled | boolean | false | 是否禁用 |
background | boolean | true | 是否带背景色 |
事件:
| 事件 | 参数 | 说明 |
|---|---|---|
update:currentPage | number | 页码变化 |
update:pageSize | number | 每页条数变化 |
pagination | { currentPage, pageSize } | 页码或条数变化后统一抛出 |
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 布局、可选条数 | 传 layout / pageSizes,或改 index.vue 默认值 |
| 下拉框宽度等样式 | index.vue 的 <style scoped> 与 atoms.css |
高级表格ProTable
数据 · 高级表格,搜索 + 请求 + 列设置 + 分页一体。
安装
bash
npx taibai@latest add ProTable落地 src/components/ProTable/:
text
ProTable/
├── index.vue
├── components/ ColSetting.vue Pagination.vue TableColumn.vue
└── interface/index.ts ColumnProps / SearchProps / EnumPropsProTable 依赖 SearchForm,单装时建议一起:npx taibai@latest add ProTable SearchForm。
使用
vue
<script setup>
import { ref } from 'vue'
import ProTable from '@/components/ProTable/index.vue'
const tableRef = ref()
const columns = [
{ prop: 'name', label: '姓名', search: { el: 'input' } },
{ prop: 'status', label: '状态', search: { el: 'select' }, enum: [{ label: '启用', value: 1 }] }
]
// 入参是搜索 + 分页,返回值按项目接口约定取 data / total
const requestApi = params => getListApi(params)
</script>
<template>
<ProTable ref="tableRef" :columns="columns" :request-api="requestApi" title="用户列表" />
</template>属性
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
columns | ColumnProps[] | [] | 列配置,含 search / enum / render 等 |
data | any[] | — | 静态数据,传了就不再走接口 |
requestApi | (params: any) => Promise<any> | — | 列表接口 |
requestAuto | boolean | true | 挂载后是否自动请求 |
requestError | (params: any) => void | — | 请求失败回调 |
dataCallback | (data: any) => any | — | 对返回数据二次加工 |
title | string | — | 表格标题 |
pagination | boolean | true | 是否显示分页 |
initParam | any | {} | 初始查询参数 |
border | boolean | true | 是否显示纵向边框 |
toolButton | ("refresh" | "setting" | "search")[] | boolean | true | 工具栏按钮 |
rowKey | string | "id" | 行唯一键 |
searchCol | number | Record<BreakPoint, number> | { xs: 1, sm: 2, md: 2, lg: 3, xl: 4 } | 搜索区列数 |
事件:search(点查询)、reset(点重置)。
Expose(常用):
| 名称 | 说明 |
|---|---|
element | el-table 实例 |
tableData | 当前表格数据 |
searchParam / searchInitParam | 当前 / 初始搜索参数 |
getTableList() | 手动重新请求 |
search() / reset() | 触发查询 / 重置 |
handleSizeChange / handleCurrentChange | 分页变更 |
clearSelection() | 清空勾选 |
selectedList / selectedListIds / isSelected | 勾选行 / 勾选 id / 是否已有勾选 |
enumMap | 字典缓存 |
radio / pageable | 单选行 / 分页配置 |
插槽:tableHeader、toolButton、tableTop、默认插槽(列内容)、append、empty、pagination。
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 搜索区 | 复用 SearchForm,改 columns[].search |
| 列设置、列渲染 | components/ColSetting.vue、TableColumn.vue |
| 请求与分页逻辑 | index.vue 的 getTableList |
| 列配置字段 | interface/index.ts 的 ColumnProps |
全屏弹窗ProDialog
弹层 · 可拖拽、可全屏的弹窗。
安装
bash
npx taibai@latest add ProDialog落地 src/components/ProDialog/:index.vue。
全局注册标签为 ZkProDialog。
使用
vue
<script setup>
import { ref } from 'vue'
import ProDialog from '@/components/ProDialog/index.vue'
const visible = ref(false)
const dialogRef = ref()
</script>
<template>
<ProDialog ref="dialogRef" v-model="visible" title="编辑用户">
正文内容
<template #footer>
<el-button @click="visible = false">取消</el-button>
<el-button type="primary" @click="visible = false">保存</el-button>
</template>
</ProDialog>
</template>属性
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
modelValue | boolean | false | 是否显示,支持 v-model |
title | string | — | 标题 |
showClose | boolean | true | 是否显示关闭按钮 |
showFullscreen | boolean | true | 是否显示全屏按钮 |
事件:update:modelValue(value: boolean)。
Expose:zkDialogRef(内部 el-dialog 实例)。
插槽:header、default、footer。
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 拖拽、全屏实现 | index.vue 的 isFullscreen / setFullscreen |
| 头部、底部布局 | index.vue 的插槽与样式 |
站内消息Message
弹层 · 站内消息铃铛,WebSocket 实时推送。
安装
bash
npx taibai@latest add Message落地 src/components/Message/:ZkMessage.vue(组件本体)、websocket.ts(连接封装)。
使用
vue
<script setup>
import ZkMessage from '@/components/Message/ZkMessage.vue'
const historyApi = params => getMessageHistory(params)
const readApi = params => markMessageRead(params)
</script>
<template>
<ZkMessage
ws-url="wss://example.com/ws"
:history-api="historyApi"
:read-api="readApi"
@notice-handle="row => console.log('通知', row)"
@message-handle="row => console.log('消息', row)"
@todo-handle="row => console.log('待办', row)"
>
<template #icon>
<el-icon><Bell /></el-icon>
</template>
</ZkMessage>
</template>点击铃铛弹出气泡,按 type 分「通知 / 消息 / 待办」三个页签,未读数显示在 el-badge 上。
属性
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
wsUrl | string | 必填 | WebSocket 地址 |
historyApi | (params: any) => Promise<any> | 必填 | 历史消息接口 |
readApi | (params: any) => Promise<any> | 必填 | 标记已读接口 |
事件:
| 事件 | 参数 | 说明 |
|---|---|---|
noticeHandle | row: InfoType | 点击通知项 |
messageHandle | row: InfoType | 点击消息项 |
todoHandle | row: InfoType | 点击待办项 |
插槽:icon(铃铛图标)。
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 消息分类、未读统计 | ZkMessage.vue 里 on("message", ...) 的 type 过滤 |
| 连接与重连 | websocket.ts |
| 消息项样式 | ZkMessage.vue 模板与样式 |
附件预览Preview
弹层 · 附件列表 + 预览弹窗。
安装
bash
npx taibai@latest add Preview落地 src/components/Preview/:index.vue、single.vue、viewDialog.vue。
使用
vue
<script setup>
import Preview from '@/components/Preview/index.vue'
const files = [
{ fileId: '1', original: '合同.pdf', fileName: 'a1b2.pdf', otherName: '劳动合同' }
]
</script>
<template>
<Preview :list="files" upload-url="https://file.example.com/" />
</template>列表按 otherName || original 显示文件名,点击打开预览弹窗;地址由 uploadUrl + fileName 拼出。
属性
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
list | FileItem[] | 必填 | 附件列表,字段 fileId / original / fileName / otherName |
uploadUrl | string | 必填 | 文件访问前缀 |
无事件;内部 viewDialog.vue 负责预览弹窗。
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 单个文件预览方式 | single.vue |
| 预览弹窗、下载按钮 | viewDialog.vue |
| 列表展示 | index.vue 模板 |
文件上传Upload
文件 · 图片 / 文件上传,四个入口文件。
安装
bash
npx taibai@latest add Upload落地 src/components/Upload/:
text
Upload/
├── Img.vue # 单图
├── Imgs.vue # 多图
├── file.vue # 单文件 / 多文件
├── copyFile.vue # 支持 Ctrl+V 粘贴上传的文件
├── upload.ts # UploadFileProps 与上传方法
└── index.md # 目录说明使用
vue
<script setup>
import { ref } from 'vue'
import Img from '@/components/Upload/Img.vue'
const avatar = ref('')
const uploadApi = formData => uploadFileApi(formData)
</script>
<template>
<Img v-model:image-url="avatar" :api="uploadApi" upload-url="https://file.example.com/" />
</template>四个文件的 props 都来自 upload.ts 的 UploadFileProps,按需选一个入口:
| 文件 | 用途 |
|---|---|
Img.vue | 单张图片,带预览 |
Imgs.vue | 多图,带 limit |
file.vue | 任意文件,带 limit |
copyFile.vue | 任意文件,支持 Ctrl+V 粘贴上传;isFileName 控制是否显示原始文件名 |
属性
Img.vue:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
imageUrl | string | "" | 图片地址,支持 v-model:image-url |
api | (params: any) => Promise<any> | 必填 | 上传接口 |
uploadUrl | string | 必填 | 访问前缀 |
drag | boolean | true | 是否拖拽上传 |
disabled | boolean | false | 是否禁用 |
fileSize | number | 5 | 单文件大小上限(MB) |
fileType | string[] | ["image/jpeg","image/png","image/gif"] | 允许的类型 |
height / width | string | "150px" | 预览尺寸 |
borderRadius | string | "8px" | 圆角 |
其余入口额外支持 fileList(默认 [])、limit(默认 5)、isFileName(默认 false)。
事件:update:imageUrl(value: string)(Img.vue);其他入口按文件同理。
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 上传请求、类型 / 大小校验 | upload.ts 与各入口的 handleHttpUpload |
| 预览样式 | 各入口模板上的 height / width / borderRadius |
| 新增入口形态 | 复制一个入口文件,props 复用 UploadFileProps |
用户信息UserInfo
业务 · 个人资料 / 修改密码弹窗。
安装
bash
npx taibai@latest add UserInfo落地 src/components/UserInfo/:ZKUserInfoDialog.vue(资料)、ZkPasswordDialog.vue(改密码),没有 index.vue,按文件名引用。
使用
vue
<script setup>
import { ref } from 'vue'
import UserInfoDialog from '@/components/UserInfo/ZKUserInfoDialog.vue'
import PasswordDialog from '@/components/UserInfo/ZkPasswordDialog.vue'
const userRef = ref()
const pwdRef = ref()
const user = ref({ name: '张三' })
// 由页面按钮触发
const openProfile = () => userRef.value?.openDialog()
const openPassword = () => pwdRef.value?.openDialog()
</script>
<template>
<UserInfoDialog
ref="userRef"
:api="getUserApi"
:upload-img="uploadImgApi"
upload-url="https://file.example.com/"
:user-info="user"
/>
<PasswordDialog ref="pwdRef" :api="changePasswordApi" />
</template>属性
ZKUserInfoDialog.vue:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
api | (params: any) => Promise<any> | 必填 | 保存资料接口 |
uploadImg | (params: any) => Promise<any> | 必填 | 头像上传接口 |
uploadUrl | string | 必填 | 头像访问前缀 |
userInfo | any | 必填 | 当前用户信息 |
ZkPasswordDialog.vue:api(必填,提交新密码的接口)。
两个组件都暴露 openDialog() 打开弹窗。
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 资料表单字段 | ZKUserInfoDialog.vue 的表单与校验规则 |
| 密码校验规则 | ZkPasswordDialog.vue 的 passwordRules |
| 提交接口入参 | 各自 submit 方法 |
用户选择UserSelect
业务 · 选人 / 选部门弹窗。
安装
bash
npx taibai@latest add UserSelect落地 src/components/UserSelect/:index.vue、userBox.vue、interface.ts。
使用
vue
<script setup>
import { ref } from 'vue'
import UserSelect from '@/components/UserSelect/index.vue'
const selected = ref([])
const getUserApi = params => getUserList(params)
const orgUserApi = params => getOrgUserList(params)
const onCheck = data => console.log('选中', data)
</script>
<template>
<UserSelect
:value="selected"
:get-user-api="getUserApi"
:org-user-api="orgUserApi"
select-type="3"
multiple
@check-data="onCheck"
/>
</template>selectType 决定可选对象:'3' 人员、'2' 部门、'1' 组织。
属性
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
userId | string | — | 当前用户 id |
value | OrgType[] | — | 兼容字段,当前组件未读取;选中结果通过 checkData 抛出 |
multiple | boolean | true | 是否多选 |
isCheckYourself | boolean | true | 是否允许选自己 |
title | string | "" | 弹窗标题 |
disabledNodes | OrgType[] | [] | 不可选节点 |
selectType | "3" | "2" | "1" | "3" | 人员 / 部门 / 组织 |
disabledIds | string[] | [] | 不可选节点 id |
getUserApi | (params: any) => Promise<any> | 必填 | 懒加载用户 |
orgUserApi | (params: any) => Promise<any> | 必填 | 查部门下全部用户 |
事件:checkData(选中数据变化)。
Expose:acceptParams(带参数打开弹窗)、clearSelectUser(清空已选)。
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 树 / 人员列表展示 | userBox.vue |
| 可选类型、禁用逻辑 | index.vue 与 interface.ts 的 UserPropsType |
| 数据类型 | interface.ts 的 OrgType |
错误页面ErrorMessage
状态页 · 403 / 404 / 500。
安装
bash
npx taibai@latest add ErrorMessage落地 src/components/ErrorMessage/:403.vue、404.vue、500.vue、index.scss(三个页面共用样式),没有 index.vue。
使用
vue
<script setup>
import Error403 from '@/components/ErrorMessage/403.vue'
import Error404 from '@/components/ErrorMessage/404.vue'
import Error500 from '@/components/ErrorMessage/500.vue'
</script>
<template>
<Error404 />
<!-- 自定义返回逻辑 -->
<Error403 :go-back="() => router.push('/home')" />
</template>路由里可以直接把 404.vue 挂到 catch-all 路由。
属性
三个页面 props 一致:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
goBack | () => any | — | 自定义"返回上一页"行为;不传则 router.back() |
扩展
| 想改的东西 | 改哪里 |
|---|---|
| 文案、按钮 | 对应 403.vue / 404.vue / 500.vue 模板 |
| 插画与排版 | index.scss,图片在 @/assets/images/403.png 等 |
| 增加状态码 | 复制一个页面文件改文案即可 |
可用指令
指令拷到 src/directives/modules/,在 main.ts 里注册:
ts
import copy from '@/directives/modules/copy'
import debounce from '@/directives/modules/debounce'
app.directive('copy', copy)
app.directive('debounce', debounce)vue
<button v-copy="'要复制的内容'">复制</button>
<button v-debounce="handleSubmit">提交</button>
<div v-draggable>可拖拽</div>
<div v-waterMarker="{ text: '版权所有' }">内容</div>| 命令 | 指令 | 说明 |
|---|---|---|
npx taibai@latest add v-copy | v-copy | 点击复制文本到剪贴板 |
npx taibai@latest add v-debounce | v-debounce | 按钮防抖(500ms) |
npx taibai@latest add v-throttle | v-throttle | 按钮节流(1 秒内只能点一次) |
npx taibai@latest add v-draggable | v-draggable | 元素拖拽 |
npx taibai@latest add v-longpress | v-longpress | 长按 1 秒触发 |
npx taibai@latest add v-waterMarker | v-waterMarker | 背景水印 |
可用样式
样式拷到 src/styles/modules/,在 main.ts 里引入:
ts
import '@/styles/modules/nexus.css' // 基础原子类
import '@/styles/modules/nexuspx.css' // px 尺寸原子类
import '@/styles/modules/animations.css' // 关键帧动画| 命令 | 文件 | 说明 |
|---|---|---|
npx taibai@latest add base-styles | nexus.css | 基础原子类:显示类型、Flex、文本省略、行高、定位、背景透明度、百分比宽高、层级等,详见 原子样式库 nexus.css |
npx taibai@latest add base-styles-px | nexuspx.css | px 尺寸原子类:font14、lineht24、pad20、ht40、radius8 等 |
npx taibai@latest add base-animations | animations.css | 8 组关键帧动画 + .anim-* 工具类,详见 动画库 animations.css |
三个样式互相独立,可单装。TypeWriter 目录下自带 atoms.css(只含它用到的 10 条声明),装组件时一起拷进去、由组件里的 <style src="./atoms.css"> 挂载,所以单装 TypeWriter 就能直接显示,不必先引 nexus.css;其他组件仍按需引入全局原子库。
可用工具函数
工具函数拷到 src/utils/modules/,按需 import:
ts
import { formValidate } from '@/utils/modules/formValidate'
// 在 element-plus 表单 rules 里用
rules: [
{ validator: formValidate('phone'), trigger: 'blur' },
{ validator: formValidate('idCard'), trigger: 'blur' },
{ validator: formValidate('email'), trigger: 'blur' }
]内置校验类型:phone / password / idCard / email / plateNumber / chinese / fullName / creditCode / webUrl 等。
| 命令 | 说明 |
|---|---|
npx taibai@latest add form-validate | 常用表单校验规则(手机号/身份证/邮箱/密码等正则) |
如何卸载 / 删除
taibai 是把源码拷进你的项目,拷过去的文件就是你的,删除就是直接删文件:
| 类型 | 删除什么 | 同时记得去掉 |
|---|---|---|
| 组件 | 删 <componentsDir>/组件名/ 整个文件夹 | 文件里的 import 与模板里的使用 |
| 指令 | 删 src/directives/modules/指令名.ts | main.ts 里的 app.directive(...) 注册与模板里的 v-xxx |
| 样式 | 删 src/styles/modules/nexus.css / nexuspx.css / animations.css | main.ts 对应的 import |
| 工具函数 | 删 src/utils/modules/xxx.ts | 文件里的 import |
不需要 npm uninstall,组件没进 node_modules,拷过来的就是你自己的源码。
补充说明:
- 覆盖:目标文件已存在时,
add会询问是否覆盖,默认不覆盖;非交互环境(CI)下保持不覆盖,自己改过的文件不会被悄悄替换。 - 只想改一点:直接改拷过去的源码,
taibai不会再回头动它。
常用命令速查
bash
npx taibai@latest init # 初始化项目(写 taibai.json)
npx taibai@latest list # 查看全部组件 / 指令 / 样式 / 工具
npx taibai@latest add <名称> # 添加单个或多个
npx taibai@latest add all # 装业务组件库 + 支撑目录
npx taibai@latest --help # 帮助本地开发(维护这个 CLI 用)
bash
npm install
npm run build # tsup 打包 CLI + 把 src 下的库同步进 dist
npm link # 链到全局做本地测试构建产物:
dist/index.js CLI 本体
dist/library/ 业务组件库(组件的唯一来源)+ registry.json
dist/directives/ 指令
dist/styles/ 样式(nexus.css / nexuspx.css / animations.css)
dist/utils/ 工具函数dist 全部由 src 生成,src/cli 下不存副本。
新增内容
| 类型 | 放哪 | 还要做什么 |
|---|---|---|
| 组件 | src/components/<Name>/ | 在 scripts/copy-components.mjs 的 META 里登记分类与说明 |
| 指令 | src/directives/modules/x.ts | 在 src/cli/lib/registry.ts 加一条 v-x |
| 样式 | src/styles/base/x.css | 在 registry.ts 加条目;新文件名要同步 add.ts 的 STYLE_FILE 映射 |
| 工具函数 | src/utils/x.ts | 在 registry.ts 加条目 |
改完执行 npm run build,dist 会自动跟着更新。