目录与版本

SAI组件

我们基于Artd 进行了组件封装,提供更多方便的组件供我们使用
本页目录

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'-按钮类型(预设样式)
iconstring-自定义图标(Iconify 格式)
toolTipstring''工具提示文本
iconColorstring-图标颜色
buttonBgColorstring-按钮背景色

预设类型:

  • 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:

属性类型默认值说明
dictstring-必填,字典编码
valueType'number' | 'string''number'值类型转换
placeholderstring'请选择'占位符
disabledbooleanfalse是否禁用
clearablebooleantrue是否可清除
filterablebooleanfalse是否可筛选
multiplebooleanfalse是否多选
collapseTagsbooleanfalse多选时折叠标签
collapseTagsTooltipbooleanfalse折叠标签显示提示

使用示例:

<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:

属性类型默认值说明
dictstring-必填,字典编码
type'radio' | 'button' | 'border''radio'显示样式
valueType'number' | 'string''number'值类型转换
disabledbooleanfalse是否禁用
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:

属性类型默认值说明
dictstring-必填,字典编码
type'checkbox' | 'button' | 'border''checkbox'显示样式
valueType'number' | 'string''number'值类型转换
disabledbooleanfalse是否禁用
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:

属性类型默认值说明
loadingbooleanfalse加载状态
inlinePromptbooleantrue内联显示文字
activeValuestring | number | boolean1打开时的值
inactiveValuestring | number | boolean2关闭时的值
showTextbooleantrue是否显示文字
activeTextstring'启用'打开时的文字
inactiveTextstring'禁用'关闭时的文字

使用示例:

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

SaDict 字典标签

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

Props:

属性类型默认值说明
dictstring-必填,字典类型
valuestring | number | string[] | number[]-必填,字典值
render'tag' | 'text''tag'渲染方式
size'large' | 'default' | 'small''default'标签大小
roundbooleanfalse是否圆角标签

使用示例:

<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:

属性类型默认值说明
labelstring-必填,标签内容
tooltipstring''提示内容
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:

属性类型默认值说明
placeholderstring'请选择用户'占位符
disabledbooleanfalse是否禁用
clearablebooleantrue是否可清除
multiplebooleanfalse是否多选
collapseTagsbooleantrue多选时折叠标签
collapseTagsTooltipbooleantrue折叠标签显示提示
valueType'id' | 'username''id'返回值类型

使用示例:

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

SaIconPicker 图标选择器

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

Props:

属性类型默认值说明
disabledbooleanfalse是否禁用

使用示例:

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

SaSearchBar 搜索栏

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

Props:

属性类型默认值说明
gutternumber12表单控件间隙
labelPosition'left' | 'right' | 'top''right'标签位置
showExpandbooleantrue显示展开/收起
defaultExpandedbooleanfalse默认是否展开
showResetbooleantrue显示重置按钮
showSearchbooleantrue显示搜索按钮
disabledSearchbooleanfalse禁用搜索按钮

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:

属性类型默认值说明
heightstring'500px'编辑器高度
mode'default' | 'simple''default'编辑器模式
placeholderstring'请输入内容...'占位符
toolbarKeysstring[]-自定义工具栏
excludeKeysstring[]['fontFamily']排除的工具
uploadConfigobject-上传配置

Expose 方法:

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

使用示例:

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

SaCode 代码高亮

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

Props:

属性类型默认值说明
codestring-必填,代码内容
languagestring'javascript'代码语言

使用示例:

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

SaImagePicker 图片选择器

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

Props:

属性类型默认值说明
modelValuestring | string[]''绑定值
placeholderstring'点击选择图片'占位符
multiplebooleanfalse是否多选
limitnumber3多选限制
roundbooleanfalse是否圆形
widthstring | number'120px'宽度
heightstring | number'120px'高度

使用示例:

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

SaImageDialog 图片弹窗

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

Props:

属性类型默认值说明
visiblebooleanfalse是否显示
multiplebooleanfalse是否多选
limitnumber3多选限制
initialUrlsstring | string[]''初始选中

Events:

事件说明
confirm确认选择

SaImageUpload 图片上传

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

Props:

属性类型默认值说明
modelValuestring | string[][]绑定值
multiplebooleanfalse是否多选
limitnumber1最大数量
maxSizenumber5最大文件大小 (MB)
acceptstring'image/*'接受的文件类型
disabledbooleanfalse是否禁用
widthnumber148上传区域宽度
heightnumber148上传区域高度
roundbooleanfalse是否圆形
showTipsbooleantrue显示上传提示

使用示例:

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

SaFileUpload 文件上传

通用文件上传组件。

Props:

属性类型默认值说明
modelValuestring | string[][]绑定值
multiplebooleanfalse是否多选
limitnumber1最大数量
maxSizenumber10最大文件大小 (MB)
acceptstring'*'接受的文件类型
acceptHintstring''文件类型提示
disabledbooleanfalse是否禁用
dragbooleanfalse是否拖拽上传
buttonTextstring'选择文件'按钮文字

使用示例:

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

SaChunkUpload 分片上传

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

Props:

属性类型默认值说明
modelValuestring | string[][]绑定值
multiplebooleanfalse是否多选
limitnumber1最大数量
maxSizenumber1024最大文件大小 (MB)
chunkSizenumber5分片大小 (MB)
acceptstring'*'接受的文件类型
acceptHintstring''文件类型提示
disabledbooleanfalse是否禁用
dragbooleantrue是否拖拽上传
autoUploadbooleanfalse是否自动上传

使用示例:

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

导入导出组件

SaExport 数据导出

Excel 数据导出按钮组件。

Props:

属性类型默认值说明
urlstring-必填,导出接口地址
paramsobject-请求参数
fileNamestring'导出数据.xlsx'文件名
methodstring'post'请求方法
labelstring'导出'按钮文字

Events:

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

使用示例:

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

SaImport 数据导入

Excel 数据导入弹窗组件。

Props:

属性类型默认值说明
titlestring'导入'弹窗标题
widthstring | number'600px'弹窗宽度
uploadUrlstring-上传接口地址
downloadUrlstring-模板下载地址
acceptstring'.xlsx,.xls'接受的文件类型
tipstring-上传提示
dataobject-附加数据

Events:

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

使用示例:

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

使用说明

全局注册

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

字典依赖

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

类型转换

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


开发规范

  1. 组件命名采用 Sa 前缀 + 驼峰命名
  2. 使用 defineOptions({ name: 'SaXxx' }) 定义组件名
  3. 使用 inheritAttrs: false + v-bind="$attrs" 透传属性
  4. 使用 defineModel 实现 v-model 双向绑定
  5. 使用 TypeScript 定义 Props 接口
更新时间:2026-02-05 19:35:22阅读量:1095