基座已封好的业务级控件,全部全局注册,模板里直接写标签,不用 import。
| 控件 | 用途 |
|---|---|
s-file-upload |
图片/文件上传(拖拽排序、预览、下载、删除) |
s-choose-user |
弹窗选人 |
s-user-select |
下拉选人 |
s-user-select-button |
按钮 + 弹窗选人 |
s-office-select |
岗位选择 |
s-data-range-tree-select |
组织/校区/单位树选择 |
s-tree-select |
通用下拉树(自定义数据源) |
s-editor |
富文本 |
s-tab |
可横向滚动的标签页 |
s-empty |
空状态 |
s-icon |
图标 |
字典不单独封组件,用 $utils 里的字典方法 + a-select。
// 按类型批量取字典,返回 { 类型转驼峰: [{ label, value, id }] }
const res = await window.$utils.mapByDictTypes('sys_position_type', 'card_type')
// res.sysPositionType / res.cardType
<a-select
v-model:value="form.type"
:allowClear="true"
:showSearch="true"
:filterOption="$utils.filterSelectOption"
placeholder="请选择岗位类型"
style="width: 100%"
>
<a-select-option v-for="item in types" :key="item.value" :value="item.value">
{{ item.label }}
</a-select-option>
</a-select>
const types = ref([])
onMounted(async () => {
const res = await window.$utils.mapByDictTypes('sys_position_type')
types.value = res.sysPositionType || []
})
字典工具(window.$utils.*):
| 方法 | 说明 |
|---|---|
mapByDictTypes(...类型) |
批量取字典,返回 { 驼峰类型名: [{ label, value, id }] } |
dictTypes() |
字典类型清单 |
toDictOptions(list) |
转 [{ label, value }] |
dictName(list, value) |
按字典值取文案,取不到返回 '--' |
filterSelectOption(inputValue, option) |
a-select 本地搜索的 filterOption 回调 |
下拉的 value 一律用字典项的 value(字典值),不要用 id(主键)。
<s-file-upload
path="sysEmployee"
:list="fileList"
:maxFileCount="1"
accept="image/*"
listType="card"
@handChange="onFileChange"
/>
const fileList = ref([])
const onFileChange = (list) => { fileList.value = list }
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
list |
Array | [] |
文件列表,见下方项结构 |
label |
String | '' |
控件上方标题 |
accept |
String | 'image/*' |
可选文件类型,如 .pdf,.docx 或 image/* |
listType |
String | 'card' |
card 卡片(图片显原图)/ list 列表(图标 + 文件名) |
maxFileCount |
Number | 5 |
最多文件数 |
fileSize |
Number | 200 |
单文件大小上限,单位 KB |
path |
String | — | 上传目录,一般传业务表名 |
businessKey |
String | — | 业务主键,随上传一起提交 |
readonly |
Boolean | false |
只读(不能加/删/拖) |
detailMode |
Boolean | false |
详情模式:只留预览和下载入口 |
isAdd |
Boolean | true |
false 隐藏新增入口 |
showPreview |
Boolean | true |
显示预览按钮 |
showDownload |
Boolean | true |
显示下载按钮 |
showRemove |
Boolean | true |
显示删除按钮 |
noDrag |
Boolean | false |
关闭拖拽排序 |
picStyle |
Object | {} |
列表容器样式 |
| 事件 | 参数 | 说明 |
|---|---|---|
handChange |
fileList |
上传/删除/排序后触发,用这个 |
change |
fileList |
同上(历史别名) |
dragChange |
fileList |
拖拽排序后 |
download |
record |
点下载 |
{ uid: '唯一标识', url: '文件地址', imageUrl: '图片地址', name: '文件名', type: 'image/png', sort: 1 }
回显后端数据时按这个结构拼:
fileList.value = res.imageUrl
? [{ uid: res.imageUrl, url: res.imageUrl, imageUrl: res.imageUrl, name: '照片', sort: 1 }]
: []
提交时取 fileList.value.map(i => i.imageUrl || i.url)。
点输入框弹出选人窗口,适合表单里选一个/多个人。
<s-choose-user
v-model:value="chooseVisible"
v-model:selectedIds="form.userIds"
:multiple="true"
@callback="onUserSelected"
/>
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
value |
Boolean | false |
弹窗显隐,v-model:value |
selectedIds |
Array | [] |
多选回显,v-model:selectedIds |
selectedId |
String | '' |
单选回显,v-model:selectedId |
multiple |
Boolean | false |
是否多选 |
required |
Boolean | false |
未选时提示"请选择人员" |
title |
String | '选择人员' |
弹窗标题 |
searchPlaceholder |
String | 按姓名/工号/手机号搜索 | 搜索框占位 |
事件 @callback="(list) => {}",list 是选中人员的完整对象数组,确认时触发;直接关闭时回调不带参数,形参给默认值 []:
const onUserSelected = (list = []) => {
form.userIds = list.map((i) => i.id)
form.userNames = list.map((i) => i.name).join('、')
}
表单里最常用的选人控件,外观是下拉框,点开是选人面板。
<s-user-select
v-model:value="form.superiorLeaderId"
:multiple="false"
placeholder="请选择上级领导"
@change="onLeaderChange"
/>
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
value |
String / Array | '' |
单选为 id 字符串,多选为 id 数组 |
multiple |
Boolean | true |
默认多选,单选必须显式传 :multiple="false" |
placeholder |
String | '请选择' |
— |
title |
String | '人员选择' |
弹窗标题 |
事件 @change="(tags, nameList, idList, list) => {}":
| 参数 | 内容 |
|---|---|
tags |
选中的显示文本(数组) |
nameList |
姓名数组 |
idList |
id 数组 |
list |
完整对象数组(要存姓名时用这个) |
const onLeaderChange = (tags, nameList, idList, list) => {
const one = list && list[0]
form.superiorLeaderId = one ? one.id : ''
form.superiorLeaderName = one ? one.name : ''
}
栅格/卡片里选人,或者需要"选择人员"按钮而不是输入框时用。
<s-user-select-button
v-model:value="form.memberIds"
:multiple="true"
buttonText="选择人员"
type="primary"
@change="onMembersChange"
/>
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
value |
String / Array | '' |
同 s-user-select |
multiple |
Boolean | true |
— |
buttonText |
String | '选择人员' |
按钮文案 |
type |
String | 'default' |
default / primary / dashed / link / text |
size |
String | 'middle' |
large / middle / small |
disabled |
Boolean | false |
— |
title |
String | '人员选择' |
弹窗标题 |
placeholder |
String | — | 未选时文案 |
事件 @change 参数同 s-user-select。
<s-form-item label="主岗" name="mainPositionId">
<s-office-select v-model:value="form.mainPositionId" :multiple="false" placeholder="请选择主岗" />
</s-form-item>
<s-form-item label="副岗" name="deputyPositionIds">
<s-office-select v-model:value="form.deputyPositionIds" :multiple="true" placeholder="请选择副岗" />
</s-form-item>
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
value |
String / Array | — | 单选为 id,多选为 id 数组 |
multiple |
Boolean | true |
默认多选,单选显式传 false |
placeholder |
String | '请选择' |
— |
title |
String | '岗位选择' |
弹窗标题 |
事件 @change="(tags, nameList, idList, list) => {}",参数同 s-user-select。
组织 / 校区 / 单位三合一的树选择器,支持数据权限过滤。
<!-- 选组织(带数据权限) -->
<s-data-range-tree-select
v-model:value="form.campusIds"
:treeCheckable="false"
:showOnlyOrganization="true"
:isDataScopeFilter="true"
:maxTagCount="1"
@change="onCampusChange"
/>
<!-- 选单位(数据源来自上级组织,禁用校区和单位分组) -->
<s-data-range-tree-select
v-model:value="form.unitIds"
:treeSelectData="units"
:disabledGroup="['1', '2']"
:maxTagCount="1"
/>
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
value |
String / Array | null |
选中的组织 id 集合(一般用数组) |
treeSelectData |
Boolean / Array | false |
传数组则不请求接口,直接用这个数据源 |
showOnlyOrganization |
Boolean | false |
只显示组织层级 |
isDataScopeFilter |
Boolean | false |
按当前用户数据权限过滤 |
autoSysConfig |
Boolean | false |
数据范围跟随系统配置(dataScope) |
defaultValue |
Boolean | true |
默认选中当前登录用户组织(仅 showOnlyOrganization 生效) |
disabledGroup |
String / Array | '' |
禁用某类节点:'1' 组织 / '2' 校区 / '3' 单位,可传数组 |
multiple |
Boolean | false |
是否多选 |
treeCheckable |
Boolean | false |
是否显示复选框 |
maxTagCount |
Number | 1 |
最多显示几个 tag |
allowClear |
Boolean | true |
可清空 |
showSearch |
Boolean | true |
可搜索 |
treeDefaultExpandAll |
Boolean | true |
默认展开全部 |
placeholder |
String | '' |
— |
事件 @change="(val) => {}",val 是选中的 id 数组。
treeCheckable为false时返回的仍是数组(如[id]),取值时按数组处理。
数据源完全自定义,适合分类、部门、地区这类自己管数据的树。
<s-tree-select
v-model:value="form.categoryId"
:recursionChildren="loadChildren"
:props="{ label: 'name', value: 'id', children: 'children' }"
:expandAll="true"
placeholder="请选择分类"
/>
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
value |
String / Array | '' |
选中值 |
recursionChildren |
Function | — | 取数函数,入参是父节点 id |
props |
Object | { children: 'children', label: 'name', value: 'value' } |
节点字段映射 |
multiple |
Boolean | false |
多选 |
maxTagCount |
Number | 1 |
— |
search |
Boolean | true |
可搜索 |
filterField |
String | 'name' |
搜索匹配字段 |
clear |
Boolean | true |
可清空 |
expandAll |
Boolean | false |
默认展开全部 |
appendRootNodeAll |
Boolean | false |
加一个"全部"根节点 |
disabled |
Boolean | false |
— |
listHeight |
Number | 232 |
下拉列表高度 px |
<s-editor v-model="form.content" :config="{ minHeight: 300 }" />
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
modelValue |
String | '' |
HTML 字符串,v-model |
config |
Object | {} |
jodit 配置覆盖项 |
内容存 HTML,展示时用 v-html。富文本里的图片地址依赖 VITE_APP_PC_HOST 配置。
标签多时自动出左右箭头,比 a-tabs 更适合列表页顶部。
<s-tab v-model:activeKey="activeKey" :tabs="tabs" @change="onTabChange">
<!-- 或自定义标签内容 -->
</s-tab>
<s-tab v-model:activeKey="activeKey">
<s-tab-item value="all" label="全部" />
<s-tab-item value="mine" label="我的" />
</s-tab>
s-tab 属性:tabs([{ label, value }])、activeKey(v-model:activeKey)、defaultActiveKey、tabKey(字段映射)、stepRatio(滚动步长)。
s-tab-item 属性:value、label(也可用默认插槽放富内容)。
<s-empty :desc="$l('暂无数据')" />
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
type |
String / Number | 1 |
插画风格 |
icon |
String / Object | '' |
自定义图标 |
desc |
String / Boolean | — | 描述文案,传 false 不显示 |
iconStyle |
Object | {} |
图标样式 |
<s-icon type="plus" />
<s-icon type="check" :style="{ color: 'var(--s-color-success)' }" />
type 支持 kebab 写法(info-circle)或 Pascal 名(InfoCircleOutlined),内部会转成图标组件。也可以直接用 $icons 或从 @ant-design/icons-vue import。
| 组件 | 用途 |
|---|---|
s-extend-fields-form |
扩展字段表单(data + defaultValue + column,方法 validate() / getModel()) |
s-cascader |
级联选择 |
s-color-picker |
颜色选择 |
s-import-modal |
导入弹窗(见 03 文档) |
s-list-card-layout |
卡片列表 |
s-list-table-tree-layout |
表格树列表 |
s-super-list-layout |
左右主从列表 |
s-anchor |
锚点导航(s-form-layout 已内置) |
s-upload 相关 |
统一用 s-file-upload |
antd 原生组件(a-input、a-select、a-date-picker、a-switch、a-radio-group、a-checkbox、a-textarea、a-input-number、a-upload 等)全部可直接使用,无需引入。