sybz-components

Sybz Components

基于 Vue 3 + Element Plus 的业务组件库。把项目中高频出现的表单、表格、弹窗、筛选、布局、提示、图表等能力沉淀为可复用组件，同时提供常用工具函数和自定义指令，帮助后台系统更快落地。

Codex Skills

组件库随 npm 包暴露 skills/sybz-components，可安装为 Codex skill，用来指导 Codex 优先使用当前组件库、工具函数和主题规范。

安装组件库后执行：

node node_modules/sybz-components/scripts/install-sybz-skill.mjs

在当前仓库内也可以执行：

pnpm skills:install

安装后可在 Codex 中这样使用：

使用 $sybz-components 把这个页面改成 sybz-components 组件库写法

在线文档

• 文档地址：https://liulihao88.github.io/sybz-components/
• 组件总览：组件文档
• 快速体验：Button 示例

项目特色

• 基于真实业务沉淀：组件来自实际项目中的通用场景，不只是 Element Plus 的简单换皮。
• 默认兼容，按需收敛：一次 app.use(SybzComponents) 即可注册组件、内置指令和 Element Plus 图标，也可以关闭部分全局能力，减少安装副作用。
• 统一默认配置：支持在安装时传入全局默认属性，例如 theme、size、组件级默认配置等。
• 主题扩展：内置 chenghua 主题样式，适合在同一套组件里快速切换业务视觉风格。
• 表格能力增强：提供 STable 相关类型和配置能力，适合复杂后台表格场景。
• 工具函数配套：@sybz-components/utils 提供提示、格式化、校验、复制、节流、防抖等常用方法。
• 文档驱动开发：每个组件都有独立示例，便于查看属性、默认值、不同主题和交互效果。

安装

推荐使用 pnpm 安装组件库和基础 peer 依赖：

pnpm add sybz-components element-plus

也可以使用 bun、npm：

bun add sybz-components element-plus

npm install sybz-components element-plus

如果使用 SChart、objectLine、quotaPie、countBar 等图表组件，再安装：

pnpm add echarts

bun add echarts

npm install echarts

yarn add echarts

如需使用工具函数包：

pnpm add @sybz-components/utils

使用其他包管理器安装工具函数包：

bun add @sybz-components/utils

npm install @sybz-components/utils

yarn add @sybz-components/utils

更新组件库

更新 sybz-components：

pnpm add sybz-components@latest

bun add sybz-components@latest

npm install sybz-components@latest

yarn add sybz-components@latest

同时更新组件库和工具函数包：

pnpm add sybz-components@latest @sybz-components/utils@latest

bun add sybz-components@latest @sybz-components/utils@latest

npm install sybz-components@latest @sybz-components/utils@latest

yarn add sybz-components@latest @sybz-components/utils@latest

快速上手

在入口文件中注册 Element Plus 和 Sybz Components：

// main.ts
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import SybzComponents from 'sybz-components'
import 'sybz-components/style.css'
import App from './App.vue'

const app = createApp(App)

app.use(ElementPlus)
app.use(SybzComponents)
app.mount('#app')

然后在任意 Vue 文件中直接使用组件：

<template>
  <s-button type="primary">新建任务</s-button>
  <s-title title="任务列表" />
  <s-empty description="暂无数据" />
</template>

按需引入组件

如果只使用少量组件，可以从独立入口导入并注册。路径与组件文档目录一致；业务组件也支持 components/company/baseHeader 这样的路径。

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import SButton from 'sybz-components/components/button'
import STitle from 'sybz-components/components/title'
import 'element-plus/dist/index.css'
import 'sybz-components/style.css'
import App from './App.vue'

const app = createApp(App)
app.use(ElementPlus)
app.use(SButton)
app.use(STitle)
app.mount('#app')

独立入口会按组件拆分 JavaScript，并提供对应的组件属性类型。当前样式仍使用公共的 style.css；图表组件继续使用 sybz-components/charts/* 和 sybz-components/charts/style.css。

全局默认配置

安装组件库时可以传入默认配置，减少业务页面中的重复属性：

app.use(SybzComponents, {
  theme: 'chenghua',
  size: 'large',
  button: {
    type: 'primary',
  },
  tooltip: {
    showAfter: 500,
  },
})

常用全局配置：

更多配置请查看 类型定义。

可选全局能力

默认安装行为会注册内置指令和 Element Plus 图标别名。如果项目已经自行管理这些能力，可以在安装时关闭：

app.use(SybzComponents, {
  registerDirectives: false,
  registerElementPlusIcons: false,
})

Peer 依赖说明

组件库的 peer 依赖只保留宿主项目必须提供的基础运行时：vue 和 element-plus。@element-plus/icons-vue、@vueuse/core 由组件库依赖自动安装；echarts 属于功能型依赖，仅在使用图表能力时由宿主项目按需安装。

常用组件

完整示例请访问 组件文档。

工具函数

工具函数独立发布在 @sybz-components/utils，可以按需引入：

import { $toast, clone, debounce, throttle } from '@sybz-components/utils'

$toast('保存成功')

const nextData = clone(data)
const handleSearch = debounce(() => {
  // 执行搜索
}, 300)

也可以挂载到 Vue 全局属性：

import * as utils from '@sybz-components/utils'

Object.keys(utils).forEach((key) => {
  app.config.globalProperties[key] = utils[key]
})

在组件中通过 proxy 使用：

import { getCurrentInstance } from 'vue'

const { proxy } = getCurrentInstance()!

proxy.$toast('操作成功')

自定义指令

注册 SybzComponents 后，内置指令可直接使用：

类型支持

组件库导出了常用类型，尤其适合在表格配置中获得类型提示：

import type { TableColumnList, STableProps } from 'sybz-components'

const columns: TableColumnList = [
  {
    label: '名称',
    prop: 'name',
  },
]

const tableProps: STableProps = {
  data: [],
  columns,
}

本地开发

pnpm install
pnpm dev

常用命令：

目录结构

├─ packages
│  ├─ components      # 组件源码
│  ├─ directives      # 自定义指令
│  ├─ hooks           # 组件内部 hooks
│  ├─ styles          # 全局样式与主题
│  ├─ types           # 类型定义
│  └─ utils           # 工具函数包源码
├─ docs
│  ├─ components      # 组件文档与示例
│  ├─ public          # 文档静态资源
│  └─ shared          # 文档公共组件
└─ README.md

适用场景

sybz-components 更适合中后台、管理端、数据平台和业务系统。如果你的项目已经使用 Vue 3 + Element Plus，并且希望减少重复封装、统一交互和样式，那么它可以作为项目组件层的基础设施。