Skip to content

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 BasisTableCRUD 表格(含 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 ErrorMessage403 / 404 / 500

组件默认基于 element-plus,用到表格、分页、弹层的组件需要项目里已安装 element-plus 并注册了对应组件。

组件命名规范 ​

组件名 = 依赖层级前缀 + 语义后缀。前缀回答“它依赖什么”,后缀写清“它是什么”,看名字就能判断安装成本。

前缀定位依赖示例
Pro依赖 UI 组件库element-plus 等第三方 UI 库ProEmpty(空状态,基于 el-empty)、ProTable
BizBusiness,业务组件业务接口、路由、权限、登录态BizEmpty(如 UserSelect、Message)
App平台级组件平台壳、布局、主题、多端适配AppEmpty(如布局壳、路由壳)
Basic基础但功能完整不依赖第三方库,可依赖自写组件BasicEmpty(如 BasisForm、BasisTable)
无前缀最基础不依赖组件库或自写组件Empty(如 Icon)

约定:

  1. 先看依赖,再看语义:能独立成立的最基础件用无前缀;一旦引入 element-plus 等 UI 库,就升到 Pro。
  2. 带业务语义(接口、权限、组织架构)用 Biz;平台能力(布局、路由壳、主题)用 App。
  3. 前缀只表达依赖层级,后半只表达用途,不要叠加两个前缀(ProBizXxx 不推荐)。
  4. 改名时同步更新目录、scripts/copy-components.mjs 的 META、CLI 清单和文档;命令只认新名,不保留旧名别名。
  5. 本次改名示例: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;标签不会被逐字打出来,只对文本逐字输出。

属性 ​

参数类型默认值说明
titlestring必填要输出的内容,允许 HTML 字符串
typeSpeednumber30每个字符的间隔毫秒数,越大越慢
delaynumber300开始输出前的等待毫秒数

Expose:

名称类型说明
isTypingRef<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%。

属性 ​

参数类型默认值说明
srcstring必填图片地址

无事件、无 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 用英文逗号分隔,匹配不区分大小写,内部会先转义正则元字符,不能传正则。

属性 ​

参数类型默认值说明
contentstring必填要展示的整段文本
keywordsstring | null""关键字,逗号分隔
colorstring—高亮文字颜色

无事件、无 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。

属性 ​

参数类型默认值说明
valuestring—预留字段,当前生成逻辑未使用
lengthnumber4验证码字符个数
backstring—预留背景色字段
widthnumber120宽度(px)
heightnumber40高度(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 是关掉的,播放 / 进度 / 音量都在组件内部实现;点画面本身也能播放、暂停。

属性 ​

参数类型默认值说明
videoSourcestring必填视频地址
posterstring""封面图
autoplaybooleanfalse是否自动播放
loopbooleanfalse是否循环
initialVolumenumber80初始音量(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:

参数类型默认值说明
colsnumber | Record<BreakPoint, number>{ xs: 1, sm: 2, md: 2, lg: 3, xl: 4 }各断点下的列数
collapsedbooleanfalse是否收起超出行数的内容
collapsedRowsnumber1收起时保留几行
gapnumber[] | number0间距,数字或 [水平, 垂直]

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 / FormItemProps

BasisForm 依赖 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>

属性 ​

参数类型默认值说明
titlestring—表单标题
itemFormItemProps[]必填表单项配置,字段见 interface/index.ts
fieldRecord<string, any>必填表单数据对象,字段与 prop 对应
hiddenRecord<string, boolean>{}按字段名控制隐藏
disabledColRecord<string, boolean>{}按字段名控制禁用
colsnumber | Record<BreakPoint, number>—栅格列数,可响应式
gapnumber[] | number[100, 0]栅格间距
labelWidthstring | number160标签宽度
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视控件而定—当前值
configFormItemProps必填控件配置,透传给内部 el-*

事件:

事件参数说明
update:valuevalue: 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。

属性 ​

参数类型默认值说明
columnsColumnProps[][]列配置,search 字段决定搜索项
searchParamRecord<string, any>{}搜索参数对象
searchColnumber | 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>

属性 ​

参数类型默认值说明
dataSelectDataProps[][]筛选项,含 title / key / options / multiple / tooltip
defaultValuesRecord<string, any>{}各筛选项默认值,按 key 对应
labelPositionstring"left"标题位置,top 或 left

事件:

事件参数说明
changevalue: 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>

属性 ​

参数类型默认值说明
titlestring—区块标题
itemany[]必填描述项配置(label / prop 等)
fieldRecord<string, any>必填数据对象
hiddenRecord<string, boolean>{}按字段隐藏
disabledRecord<string, boolean>{}按字段禁用
colsnumber | Record<BreakPoint, number>—每行列数
gapnumber[] | number[50, 0]间距
labelWidthstring | number160标签宽度
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"编辑方式
columnsany[]必填列配置
dataany[]必填表格数据
titlestring—表格标题
borderbooleantrue是否显示纵向边框
toolButtonbooleanfalse是否显示工具栏
rowKeystring"id"行唯一键
isViewbooleanfalse只读模式
defaultValueRecord<string, any>{}新增时的默认值
dialogConfigRecord<string, any>{}弹窗配置
isAddbooleantrue是否允许新增
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>

属性 ​

参数类型默认值说明
currentPagenumber1当前页,支持 v-model:current-page
pageSizenumber10每页条数,支持 v-model:page-size
totalnumber必填总条数
sizestring'default'尺寸
layoutstring'total, sizes, prev, pager, next, jumper, ->'分页布局
pageSizesnumber[][10, 20, 30, 100]可选每页条数
disabledbooleanfalse是否禁用
backgroundbooleantrue是否带背景色

事件:

事件参数说明
update:currentPagenumber页码变化
update:pageSizenumber每页条数变化
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 / EnumProps

ProTable 依赖 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>

属性 ​

参数类型默认值说明
columnsColumnProps[][]列配置,含 search / enum / render 等
dataany[]—静态数据,传了就不再走接口
requestApi(params: any) => Promise<any>—列表接口
requestAutobooleantrue挂载后是否自动请求
requestError(params: any) => void—请求失败回调
dataCallback(data: any) => any—对返回数据二次加工
titlestring—表格标题
paginationbooleantrue是否显示分页
initParamany{}初始查询参数
borderbooleantrue是否显示纵向边框
toolButton("refresh" | "setting" | "search")[] | booleantrue工具栏按钮
rowKeystring"id"行唯一键
searchColnumber | Record<BreakPoint, number>{ xs: 1, sm: 2, md: 2, lg: 3, xl: 4 }搜索区列数

事件:search(点查询)、reset(点重置)。

Expose(常用):

名称说明
elementel-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>

属性 ​

参数类型默认值说明
modelValuebooleanfalse是否显示,支持 v-model
titlestring—标题
showClosebooleantrue是否显示关闭按钮
showFullscreenbooleantrue是否显示全屏按钮

事件: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 上。

属性 ​

参数类型默认值说明
wsUrlstring必填WebSocket 地址
historyApi(params: any) => Promise<any>必填历史消息接口
readApi(params: any) => Promise<any>必填标记已读接口

事件:

事件参数说明
noticeHandlerow: InfoType点击通知项
messageHandlerow: InfoType点击消息项
todoHandlerow: 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 拼出。

属性 ​

参数类型默认值说明
listFileItem[]必填附件列表,字段 fileId / original / fileName / otherName
uploadUrlstring必填文件访问前缀

无事件;内部 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:

参数类型默认值说明
imageUrlstring""图片地址,支持 v-model:image-url
api(params: any) => Promise<any>必填上传接口
uploadUrlstring必填访问前缀
dragbooleantrue是否拖拽上传
disabledbooleanfalse是否禁用
fileSizenumber5单文件大小上限(MB)
fileTypestring[]["image/jpeg","image/png","image/gif"]允许的类型
height / widthstring"150px"预览尺寸
borderRadiusstring"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>必填头像上传接口
uploadUrlstring必填头像访问前缀
userInfoany必填当前用户信息

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' 组织。

属性 ​

参数类型默认值说明
userIdstring—当前用户 id
valueOrgType[]—兼容字段,当前组件未读取;选中结果通过 checkData 抛出
multiplebooleantrue是否多选
isCheckYourselfbooleantrue是否允许选自己
titlestring""弹窗标题
disabledNodesOrgType[][]不可选节点
selectType"3" | "2" | "1""3"人员 / 部门 / 组织
disabledIdsstring[][]不可选节点 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-copyv-copy点击复制文本到剪贴板
npx taibai@latest add v-debouncev-debounce按钮防抖(500ms)
npx taibai@latest add v-throttlev-throttle按钮节流(1 秒内只能点一次)
npx taibai@latest add v-draggablev-draggable元素拖拽
npx taibai@latest add v-longpressv-longpress长按 1 秒触发
npx taibai@latest add v-waterMarkerv-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-stylesnexus.css基础原子类:显示类型、Flex、文本省略、行高、定位、背景透明度、百分比宽高、层级等,详见 原子样式库 nexus.css
npx taibai@latest add base-styles-pxnexuspx.csspx 尺寸原子类:font14、lineht24、pad20、ht40、radius8 等
npx taibai@latest add base-animationsanimations.css8 组关键帧动画 + .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/指令名.tsmain.ts 里的 app.directive(...) 注册与模板里的 v-xxx
样式删 src/styles/modules/nexus.css / nexuspx.css / animations.cssmain.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 会自动跟着更新。

Released under the MIT License.