SAI 组件库文档

基于 Element Plus 封装的业务组件库，用于快速构建后台管理系统。

📦 组件总览

组件名	说明	主要功能
`SaButton`	表格按钮	预设样式的图标按钮，支持工具提示
`SaCheckbox`	字典复选框	基于字典数据的复选框组
`SaRadio`	字典单选框	基于字典数据的单选框组
`SaSelect`	字典下拉框	基于字典数据的下拉选择器
`SaSwitch`	开关	预设启用/禁用状态的开关组件
`SaDict`	字典标签	将字典值渲染为标签或文本
`SaLabel`	表单标签	带提示图标的表单标签
`SaSearchBar`	搜索栏	表格搜索表单，支持展开/收起
`SaUser`	用户选择器	带分页表格的用户选择组件
`SaIconPicker`	图标选择器	RemixIcon 图标选择器
`SaEditor`	富文本编辑器	基于 WangEditor 的富文本编辑器
`SaCode`	代码高亮	基于 highlight.js 的代码高亮组件
`SaImagePicker`	图片选择器	从图库选择图片
`SaImageDialog`	图片弹窗	图片资源选择弹窗
`SaImageUpload`	图片上传	图片上传组件
`SaFileUpload`	文件上传	通用文件上传组件
`SaChunkUpload`	分片上传	大文件分片上传组件
`SaExport`	数据导出	Excel 数据导出按钮
`SaImport`	数据导入	Excel 数据导入弹窗

🎛️ 表单类组件

SaButton 表格按钮

表格操作列使用的图标按钮，预设了常用的按钮样式。

Props:

属性	类型	默认值	说明
`type`	`'primary' \| 'secondary' \| 'error' \| 'info' \| 'success'`	-	按钮类型（预设样式）
`icon`	`string`	-	自定义图标（Iconify 格式）
`toolTip`	`string`	`''`	工具提示文本
`iconColor`	`string`	-	图标颜色
`buttonBgColor`	`string`	-	按钮背景色

预设类型:

primary - 新增（蓝色，图标 ri:add-fill）
secondary - 编辑（紫色，图标 ri:pencil-line）
error - 删除（红色，图标 ri:delete-bin-5-line）
info - 更多（灰色，图标 ri:more-2-fill）
success - 查看（绿色，图标 ri:eye-line）

使用示例:

<SaButton type="primary" toolTip="新增" @click="handleAdd" />
<SaButton type="secondary" @click="handleEdit" />
<SaButton type="error" @click="handleDelete" />
<SaButton icon="ri:settings-line" toolTip="设置" @click="handleSetting" />

SaSelect 字典下拉框

基于字典数据的下拉选择器，自动从 DictStore 获取选项数据。

Props:

属性	类型	默认值	说明
`dict`	`string`	-	必填，字典编码
`valueType`	`'number' \| 'string'`	`'number'`	值类型转换
`placeholder`	`string`	`'请选择'`	占位符
`disabled`	`boolean`	`false`	是否禁用
`clearable`	`boolean`	`true`	是否可清除
`filterable`	`boolean`	`false`	是否可筛选
`multiple`	`boolean`	`false`	是否多选
`collapseTags`	`boolean`	`false`	多选时折叠标签
`collapseTagsTooltip`	`boolean`	`false`	折叠标签显示提示

使用示例:

<SaSelect v-model="form.status" dict="system_status" />
<SaSelect v-model="form.type" dict="article_type" clearable filterable />
<SaSelect v-model="form.tags" dict="tag_list" multiple collapseTags />

SaRadio 字典单选框

基于字典数据的单选框组，支持普通、按钮、边框三种样式。

Props:

属性	类型	默认值	说明
`dict`	`string`	-	必填，字典编码
`type`	`'radio' \| 'button' \| 'border'`	`'radio'`	显示样式
`valueType`	`'number' \| 'string'`	`'number'`	值类型转换
`disabled`	`boolean`	`false`	是否禁用
`size`	`'large' \| 'default' \| 'small'`	`'default'`	尺寸

使用示例:

<SaRadio v-model="form.status" dict="system_status" />
<SaRadio v-model="form.type" dict="article_type" type="button" />
<SaRadio v-model="form.level" dict="user_level" type="border" />

SaCheckbox 字典复选框

基于字典数据的复选框组，支持普通、按钮、边框三种样式。

Props:

属性	类型	默认值	说明
`dict`	`string`	-	必填，字典编码
`type`	`'checkbox' \| 'button' \| 'border'`	`'checkbox'`	显示样式
`valueType`	`'number' \| 'string'`	`'number'`	值类型转换
`disabled`	`boolean`	`false`	是否禁用
`size`	`'large' \| 'default' \| 'small'`	`'default'`	尺寸

使用示例:

<SaCheckbox v-model="form.permissions" dict="permission_list" />
<SaCheckbox v-model="form.days" dict="week_days" type="button" />

SaSwitch 开关

预设启用/禁用状态的开关组件。

Props:

属性	类型	默认值	说明
`loading`	`boolean`	`false`	加载状态
`inlinePrompt`	`boolean`	`true`	内联显示文字
`activeValue`	`string \| number \| boolean`	`1`	打开时的值
`inactiveValue`	`string \| number \| boolean`	`2`	关闭时的值
`showText`	`boolean`	`true`	是否显示文字
`activeText`	`string`	`'启用'`	打开时的文字
`inactiveText`	`string`	`'禁用'`	关闭时的文字

使用示例:

<SaSwitch v-model="form.status" />
<SaSwitch v-model="form.isPublic" activeText="公开" inactiveText="私密" />

SaDict 字典标签

将字典值渲染为标签或纯文本。

Props:

属性	类型	默认值	说明
`dict`	`string`	-	必填，字典类型
`value`	`string \| number \| string[] \| number[]`	-	必填，字典值
`render`	`'tag' \| 'text'`	`'tag'`	渲染方式
`size`	`'large' \| 'default' \| 'small'`	`'default'`	标签大小
`round`	`boolean`	`false`	是否圆角标签

使用示例:

<SaDict dict="system_status" :value="row.status" />
<SaDict dict="article_type" :value="row.type" render="text" />
<SaDict dict="tag_list" :value="['1', '2', '3']" round />

SaLabel 表单标签

带提示图标的表单标签，用于说明表单项。

Props:

属性	类型	默认值	说明
`label`	`string`	-	必填，标签内容
`tooltip`	`string`	`''`	提示内容
`placement`	`'top' \| 'bottom' \| 'left' \| 'right'`	`'top'`	提示位置

使用示例:

<el-form-item>
  <template #label>
    <SaLabel label="排序" tooltip="数值越小越靠前" />
  </template>
  <el-input-number v-model="form.sort" />
</el-form-item>

SaUser 用户选择器

带分页表格的用户选择组件，支持单选和多选。

Props:

属性	类型	默认值	说明
`placeholder`	`string`	`'请选择用户'`	占位符
`disabled`	`boolean`	`false`	是否禁用
`clearable`	`boolean`	`true`	是否可清除
`multiple`	`boolean`	`false`	是否多选
`collapseTags`	`boolean`	`true`	多选时折叠标签
`collapseTagsTooltip`	`boolean`	`true`	折叠标签显示提示
`valueType`	`'id' \| 'username'`	`'id'`	返回值类型

使用示例:

<SaUser v-model="form.userId" />
<SaUser v-model="form.userIds" multiple />

SaIconPicker 图标选择器

RemixIcon 图标选择器，支持分类浏览和搜索。

Props:

属性	类型	默认值	说明
`disabled`	`boolean`	`false`	是否禁用

使用示例:

<SaIconPicker v-model="form.icon" />

SaSearchBar 搜索栏

表格搜索表单组件，支持展开/收起功能。

Props:

属性	类型	默认值	说明
`gutter`	`number`	`12`	表单控件间隙
`labelPosition`	`'left' \| 'right' \| 'top'`	`'right'`	标签位置
`showExpand`	`boolean`	`true`	显示展开/收起
`defaultExpanded`	`boolean`	`false`	默认是否展开
`showReset`	`boolean`	`true`	显示重置按钮
`showSearch`	`boolean`	`true`	显示搜索按钮
`disabledSearch`	`boolean`	`false`	禁用搜索按钮

Events:

事件	说明
`search`	点击搜索按钮
`reset`	点击重置按钮
`expand`	展开/收起变化

使用示例:

<SaSearchBar v-model="searchForm" @search="handleSearch" @reset="handleReset">
  <el-col :span="6">
    <el-form-item label="关键词" prop="keyword">
      <el-input v-model="searchForm.keyword" />
    </el-form-item>
  </el-col>
  <el-col :span="6">
    <el-form-item label="状态" prop="status">
      <SaSelect v-model="searchForm.status" dict="system_status" />
    </el-form-item>
  </el-col>
</SaSearchBar>

SaEditor 富文本编辑器

基于 WangEditor 的富文本编辑器，支持图片上传和图库选择。

Props:

属性	类型	默认值	说明
`height`	`string`	`'500px'`	编辑器高度
`mode`	`'default' \| 'simple'`	`'default'`	编辑器模式
`placeholder`	`string`	`'请输入内容...'`	占位符
`toolbarKeys`	`string[]`	-	自定义工具栏
`excludeKeys`	`string[]`	`['fontFamily']`	排除的工具
`uploadConfig`	`object`	-	上传配置

Expose 方法:

方法	说明
`getEditor()`	获取编辑器实例
`setHtml(html)`	设置内容
`getHtml()`	获取内容
`clear()`	清空编辑器
`focus()`	聚焦编辑器
`openImageDialog()`	打开图库选择

使用示例:

<SaEditor v-model="form.content" height="400px" />

SaCode 代码高亮

基于 highlight.js 的代码高亮组件。

Props:

属性	类型	默认值	说明
`code`	`string`	-	必填，代码内容
`language`	`string`	`'javascript'`	代码语言

使用示例:

<SaCode :code="codeStr" language="vue" />
<SaCode :code="phpCode" language="php" />

SaImagePicker 图片选择器

从图库选择图片的组件，支持单选和多选。

Props:

属性	类型	默认值	说明
`modelValue`	`string \| string[]`	`''`	绑定值
`placeholder`	`string`	`'点击选择图片'`	占位符
`multiple`	`boolean`	`false`	是否多选
`limit`	`number`	`3`	多选限制
`round`	`boolean`	`false`	是否圆形
`width`	`string \| number`	`'120px'`	宽度
`height`	`string \| number`	`'120px'`	高度

使用示例:

<SaImagePicker v-model="form.avatar" round />
<SaImagePicker v-model="form.images" multiple :limit="5" />

SaImageDialog 图片弹窗

图片资源选择弹窗组件，通常与 SaImagePicker 或 SaEditor 配合使用。

Props:

属性	类型	默认值	说明
`visible`	`boolean`	`false`	是否显示
`multiple`	`boolean`	`false`	是否多选
`limit`	`number`	`3`	多选限制
`initialUrls`	`string \| string[]`	`''`	初始选中

Events:

事件	说明
`confirm`	确认选择

SaImageUpload 图片上传

图片上传组件，支持预览和删除。

Props:

属性	类型	默认值	说明
`modelValue`	`string \| string[]`	`[]`	绑定值
`multiple`	`boolean`	`false`	是否多选
`limit`	`number`	`1`	最大数量
`maxSize`	`number`	`5`	最大文件大小 (MB)
`accept`	`string`	`'image/*'`	接受的文件类型
`disabled`	`boolean`	`false`	是否禁用
`width`	`number`	`148`	上传区域宽度
`height`	`number`	`148`	上传区域高度
`round`	`boolean`	`false`	是否圆形
`showTips`	`boolean`	`true`	显示上传提示

使用示例:

<SaImageUpload v-model="form.cover" />
<SaImageUpload v-model="form.gallery" multiple :limit="9" />

SaFileUpload 文件上传

通用文件上传组件。

Props:

属性	类型	默认值	说明
`modelValue`	`string \| string[]`	`[]`	绑定值
`multiple`	`boolean`	`false`	是否多选
`limit`	`number`	`1`	最大数量
`maxSize`	`number`	`10`	最大文件大小 (MB)
`accept`	`string`	`'*'`	接受的文件类型
`acceptHint`	`string`	`''`	文件类型提示
`disabled`	`boolean`	`false`	是否禁用
`drag`	`boolean`	`false`	是否拖拽上传
`buttonText`	`string`	`'选择文件'`	按钮文字

使用示例:

<SaFileUpload v-model="form.attachment" />
<SaFileUpload
  v-model="form.docs"
  accept=".pdf,.doc,.docx"
  acceptHint="PDF/Word"
  drag
/>

SaChunkUpload 分片上传

大文件分片上传组件，支持断点续传和进度显示。

Props:

属性	类型	默认值	说明
`modelValue`	`string \| string[]`	`[]`	绑定值
`multiple`	`boolean`	`false`	是否多选
`limit`	`number`	`1`	最大数量
`maxSize`	`number`	`1024`	最大文件大小 (MB)
`chunkSize`	`number`	`5`	分片大小 (MB)
`accept`	`string`	`'*'`	接受的文件类型
`acceptHint`	`string`	`''`	文件类型提示
`disabled`	`boolean`	`false`	是否禁用
`drag`	`boolean`	`true`	是否拖拽上传
`autoUpload`	`boolean`	`false`	是否自动上传

使用示例:

<SaChunkUpload v-model="form.video" :maxSize="500" :chunkSize="10" />

📥 导入导出组件

SaExport 数据导出

Excel 数据导出按钮组件。

Props:

属性	类型	默认值	说明
`url`	`string`	-	必填，导出接口地址
`params`	`object`	-	请求参数
`fileName`	`string`	`'导出数据.xlsx'`	文件名
`method`	`string`	`'post'`	请求方法
`label`	`string`	`'导出'`	按钮文字

Events:

事件	说明
`success`	导出成功
`error`	导出失败

使用示例:

<SaExport
  url="/api/user/export"
  :params="searchForm"
  fileName="用户列表.xlsx"
/>

SaImport 数据导入

Excel 数据导入弹窗组件。

Props:

属性	类型	默认值	说明
`title`	`string`	`'导入'`	弹窗标题
`width`	`string \| number`	`'600px'`	弹窗宽度
`uploadUrl`	`string`	-	上传接口地址
`downloadUrl`	`string`	-	模板下载地址
`accept`	`string`	`'.xlsx,.xls'`	接受的文件类型
`tip`	`string`	-	上传提示
`data`	`object`	-	附加数据

Events:

事件	说明
`success`	导入成功
`error`	导入失败
`download-template`	下载模板

使用示例:

<SaImport
  title="导入用户"
  uploadUrl="/api/user/import"
  downloadUrl="/api/user/template"
  @success="handleImportSuccess"
/>

📚 使用说明

全局注册

组件已在项目中全局注册，可直接在模板中使用。

字典依赖

SaSelect、SaRadio、SaCheckbox、SaDict 组件依赖 useDictStore，需要确保字典数据已加载。

类型转换

字典类组件的 valueType 属性用于解决后端返回字符串但前端需要数字的类型不匹配问题。默认值为 'number'，会自动将字典值转换为数字类型。

🔧 开发规范

组件命名采用 Sa 前缀 + 驼峰命名
使用 defineOptions({ name: 'SaXxx' }) 定义组件名
使用 inheritAttrs: false + v-bind="$attrs" 透传属性
使用 defineModel 实现 v-model 双向绑定
使用 TypeScript 定义 Props 接口