(1.0.44)
Sybz-Components

Appearance

On this page

组件库使用指南 ​

这篇文档从一个空 Vue3 项目开始，带你完成 sybz-components 的安装、引入、注册和组件使用。按顺序做完，就可以在项目里直接使用组件库开发页面。

1. 创建 Vue3 项目 ​

如果你已经有 Vue3 项目，可以跳过这一步。

sh
pnpm create vite my-sybz-app --template vue-ts
cd my-sybz-app
pnpm install
pnpm create vite my-sybz-app --template vue-ts
cd my-sybz-app
pnpm install
sh
bun create vite my-sybz-app --template vue-ts
cd my-sybz-app
bun install
bun create vite my-sybz-app --template vue-ts
cd my-sybz-app
bun install
sh
npm create vite@latest my-sybz-app -- --template vue-ts
cd my-sybz-app
npm install
npm create vite@latest my-sybz-app -- --template vue-ts
cd my-sybz-app
npm install

2. 安装组件库 ​

sybz-components 基于 Vue3 和 Element Plus 二次封装，所以项目里需要同时安装 Element Plus。

sh
pnpm add sybz-components element-plus
pnpm add sybz-components element-plus
sh
bun add sybz-components element-plus
bun add sybz-components element-plus
sh
npm install sybz-components element-plus
npm install sybz-components element-plus

如果你还需要使用公共函数库，例如 $toast、clone、validateForm，再安装 utils：

sh
pnpm add @sybz-components/utils
pnpm add @sybz-components/utils
sh
bun add @sybz-components/utils
bun add @sybz-components/utils
sh
npm install @sybz-components/utils
npm install @sybz-components/utils

3. 在 main.ts 中注册 ​

打开项目里的 src/main.ts，按下面写法引入 Element Plus、组件库和样式。

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')
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')

这一步完成后，s-button、s-input、s-select、s-dialog 等组件就可以在任意 .vue 文件里直接使用。

4. 写第一个页面 ​

把 src/App.vue 改成下面这样，先确认组件能正常显示和交互。

vue
<script setup lang="ts">
import { ref } from 'vue'

const keyword = ref('')
const status = ref('')
const showDialog = ref(false)

const statusOptions = [
  { label: '启用', value: 'enabled' },
  { label: '停用', value: 'disabled' },
]
</script>

<template>
  <div>
    <s-title title="我的第一个组件库页面" theme="chenghua" />

    <s-flex>
      <s-input v-model="keyword" />
      <s-select v-model="status" :options="statusOptions" />
      <s-button @click="showDialog = true">打开弹窗</s-button>
    </s-flex>

    <s-dialog v-model="showDialog" title="提示">这里是弹窗内容</s-dialog>
  </div>
</template>
<script setup lang="ts">
import { ref } from 'vue'

const keyword = ref('')
const status = ref('')
const showDialog = ref(false)

const statusOptions = [
  { label: '启用', value: 'enabled' },
  { label: '停用', value: 'disabled' },
]
</script>

<template>
  <div>
    <s-title title="我的第一个组件库页面" theme="chenghua" />

    <s-flex>
      <s-input v-model="keyword" />
      <s-select v-model="status" :options="statusOptions" />
      <s-button @click="showDialog = true">打开弹窗</s-button>
    </s-flex>

    <s-dialog v-model="showDialog" title="提示">这里是弹窗内容</s-dialog>
  </div>
</template>

5. 组件的基本语法 ​

组件库的组件命名一般是 s-组件名。

vue
<s-button>按钮</s-button>
<s-input v-model="name" />
<s-select v-model="value" :options="options" />
<s-dialog v-model="visible" title="标题">内容</s-dialog>
<s-button>按钮</s-button>
<s-input v-model="name" />
<s-select v-model="value" :options="options" />
<s-dialog v-model="visible" title="标题">内容</s-dialog>

常见写法主要分为四类：

vue
<!-- 1. 普通属性 -->
<s-button type="primary" size="small">保存</s-button>

<!-- 2. 动态属性，前面加冒号 -->
<s-select :options="options" :width="240" />

<!-- 3. 双向绑定 -->
<s-input v-model="form.name" />

<!-- 4. 事件监听 -->
<s-button @click="submit">提交</s-button>
<!-- 1. 普通属性 -->
<s-button type="primary" size="small">保存</s-button>

<!-- 2. 动态属性，前面加冒号 -->
<s-select :options="options" :width="240" />

<!-- 3. 双向绑定 -->
<s-input v-model="form.name" />

<!-- 4. 事件监听 -->
<s-button @click="submit">提交</s-button>

6. 使用表单输入组件 ​

vue
<script setup lang="ts">
import { reactive } from 'vue'

const form = reactive({
  name: '',
  type: '',
})

const typeOptions = [
  { label: '普通用户', value: 'normal' },
  { label: '管理员', value: 'admin' },
]
</script>

<template>
  <s-input v-model="form.name" placeholder="请输入名称" clearable />
  <s-select v-model="form.type" :options="typeOptions" placeholder="请选择类型" clearable />
</template>
<script setup lang="ts">
import { reactive } from 'vue'

const form = reactive({
  name: '',
  type: '',
})

const typeOptions = [
  { label: '普通用户', value: 'normal' },
  { label: '管理员', value: 'admin' },
]
</script>

<template>
  <s-input v-model="form.name" placeholder="请输入名称" clearable />
  <s-select v-model="form.type" :options="typeOptions" placeholder="请选择类型" clearable />
</template>

7. 使用表格组件 ​

vue
<script setup lang="ts">
const columns = [
  { label: '姓名', prop: 'name' },
  { label: '地址', prop: 'address' },
  {
    label: '操作',
    btns: [
      {
        content: '编辑',
        handler: ({ row }) => {
          console.log('编辑当前行', row)
        },
      },
    ],
  },
]

const data = [
  { name: '张三', address: '北京市朝阳区' },
  { name: '李四', address: '上海市浦东新区' },
]
</script>

<template>
  <s-table :columns="columns" :data="data" />
</template>
<script setup lang="ts">
const columns = [
  { label: '姓名', prop: 'name' },
  { label: '地址', prop: 'address' },
  {
    label: '操作',
    btns: [
      {
        content: '编辑',
        handler: ({ row }) => {
          console.log('编辑当前行', row)
        },
      },
    ],
  },
]

const data = [
  { name: '张三', address: '北京市朝阳区' },
  { name: '李四', address: '上海市浦东新区' },
]
</script>

<template>
  <s-table :columns="columns" :data="data" />
</template>

8. 使用工具函数 ​

工具函数从 @sybz-components/utils 引入。

ts
import { $toast, clone, delay } from '@sybz-components/utils'

$toast('保存成功')

const newData = clone(oldData)

await delay(500)
import { $toast, clone, delay } from '@sybz-components/utils'

$toast('保存成功')

const newData = clone(oldData)

await delay(500)

也可以把常用方法挂到全局，不过新项目更推荐在需要的文件里按需引入，这样来源更清楚。

9. 使用内置指令 ​

注册 SybzComponents 后，内置指令可以直接在模板里使用。

vue
<template>
  <s-button v-copy="'要复制的文字'">复制</s-button>
  <s-input v-focus />
</template>
<template>
  <s-button v-copy="'要复制的文字'">复制</s-button>
  <s-input v-focus />
</template>

10. 全局默认配置 ​

如果项目里很多组件都想统一尺寸、主题或默认属性，可以在 app.use(SybzComponents, options) 里配置。

ts
app.use(SybzComponents, {
  theme: 'shijingshan',
  themeColors: {
    primary: '#7c3aed',
    accent: '#ec4899',
    background: '#faf8ff',
    fill: '#f3efff',
    text: '#241f31',
    divider: '#ded7eb',
  },
  button: {
    size: 'small',
  },
  dialog: {
    width: '520px',
  },
  table: {
    pageSize: 30,
  },
})
app.use(SybzComponents, {
  theme: 'shijingshan',
  themeColors: {
    primary: '#7c3aed',
    accent: '#ec4899',
    background: '#faf8ff',
    fill: '#f3efff',
    text: '#241f31',
    divider: '#ded7eb',
  },
  button: {
    size: 'small',
  },
  dialog: {
    width: '520px',
  },
  table: {
    pageSize: 30,
  },
})

themeColors 只替换主题颜色，组件功能、布局、圆角和交互仍沿用 shijingshan。主色使用十六进制或 rgb(...) 时会自动派生 hover、active、浅色背景、边框和阴影所需颜色。也可以从 sybz-components 导入 setSybzThemeColors 和 resetSybzThemeColors 在运行时换色或恢复默认主题色。

11. 常见问题 ​

页面上没有样式 ​

检查 main.ts 是否引入了这两个样式：

ts
import 'element-plus/dist/index.css'
import 'sybz-components/style.css'
import 'element-plus/dist/index.css'
import 'sybz-components/style.css'

组件标签不生效 ​

检查是否执行了：

ts
app.use(ElementPlus)
app.use(SybzComponents)
app.use(ElementPlus)
app.use(SybzComponents)

TypeScript 不认识组件属性 ​

优先确认安装的是最新版本：

sh
pnpm add sybz-components@latest
pnpm add sybz-components@latest
sh
bun add sybz-components@latest
bun add sybz-components@latest
sh
npm install sybz-components@latest
npm install sybz-components@latest

如果项目自己有严格的类型配置，重启一下编辑器的 TS 服务，通常即可恢复提示。

12. 推荐学习顺序 ​

  1. 先看本页，把组件库接入项目。
  2. 看 Button 按钮、Input 输入框、Select 选择器。
  3. 再看 Dialog 弹窗、Table 表格、Form 表单。
  4. 最后看 项目常见写法，统一项目里的写法风格。

sybz 思云博智主题（theme 默认值：default） ​

全局设置 theme: 'sybz'，或在单个组件设置 theme="sybz"。组件主题可选 default / chenghua / shijingshan / sybz，默认值为 default。Dialog 另保留 norm / norm16 / simple 布局主题。

ts
app.use(SybzComponents, { theme: 'sybz' })
app.use(SybzComponents, { theme: 'sybz' })
vue
<s-button theme="sybz" type="primary">保存</s-button>
<s-icon theme="sybz" icon="edit" type="primary" variant="solid" />
<s-table theme="sybz" :columns="columns" :data="rows" />
<s-button theme="sybz" type="primary">保存</s-button>
<s-icon theme="sybz" icon="edit" type="primary" variant="solid" />
<s-table theme="sybz" :columns="columns" :data="rows" />
语义颜色CSS 变量
品牌蓝#4876EF--s-sybz-primary
AI 辅助绿#00D3AB--s-sybz-accent
成功#17B26A--s-sybz-success
错误 / 删除#E5484D--s-sybz-danger
警告#EF6820--s-sybz-warning
中性信息#717680--s-sybz-info
页面浅底色#F5F8FF--s-sybz-bg

色阶保留 25 / 100 / 300 / 500 / 700 / 900 / 950，例如 var(--s-sybz-blue-100)。扩展色集包括 sky / azure / purple / rose / pink / red / yellow，用于图表与分类标识。主按钮使用品牌蓝，辅助绿用于 AI 场景，功能色保持独立语义；颜色以设计图中的 HEX 标注为准。

ts
// 可选：覆盖颜色；省略 themeColors 时使用内置配色。
app.use(SybzComponents, {
  theme: 'sybz',
  themeColors: { sybz: { primary: '#4876EF', accent: '#00D3AB' } },
})
// 可选：覆盖颜色；省略 themeColors 时使用内置配色。
app.use(SybzComponents, {
  theme: 'sybz',
  themeColors: { sybz: { primary: '#4876EF', accent: '#00D3AB' } },
})

工具包消息与确认框可使用 configureUtils({ theme: 'sybz' })；图表插件注册后设置 <s-chart theme="sybz" :option="option" />。布局和交互沿用现有主题组件规范。

主题维护入口 ​

内置主题名称与颜色前缀统一在 packages/utils/src/theme.ts 的 SYBZ_THEME_PREFIX 注册；组件使用公共 SybzComponentTheme，Dialog 使用扩展类型 SDialogTheme。类型提示由 types:generate 自动同步。只调整颜色时直接使用 themeColors 或 setSybzThemeColors，无需修改组件的属性类型。

思云博智私有前端组件库

版权所有 © 2023-2030