# 组件文档 · 业务控件
基座已封好的业务级控件,全部全局注册,模板里直接写标签,不用 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`。
```js
// 按类型批量取字典,返回 { 类型转驼峰: [{ label, value, id }] }
const res = await window.$utils.mapByDictTypes('sys_position_type', 'card_type')
// res.sysPositionType / res.cardType
```
```vue
{{ item.label }}
```
```js
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(上传)
```vue
```
```js
const fileList = ref([])
const onFileChange = (list) => { fileList.value = list }
```
### Props
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `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` | 点下载 |
### 列表项结构
```js
{ uid: '唯一标识', url: '文件地址', imageUrl: '图片地址', name: '文件名', type: 'image/png', sort: 1 }
```
回显后端数据时按这个结构拼:
```js
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(弹窗选人)
点输入框弹出选人窗口,适合表单里选一个/多个人。
```vue
```
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `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` 是选中人员的完整对象数组,确认时触发;直接关闭时回调不带参数,形参给默认值 `[]`:
```js
const onUserSelected = (list = []) => {
form.userIds = list.map((i) => i.id)
form.userNames = list.map((i) => i.name).join('、')
}
```
---
## 四、s-user-select(下拉选人)
表单里最常用的选人控件,外观是下拉框,点开是选人面板。
```vue
```
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `value` | String / Array | `''` | 单选为 id 字符串,多选为 id 数组 |
| `multiple` | Boolean | **`true`** | **默认多选,单选必须显式传 `:multiple="false"`** |
| `placeholder` | String | `'请选择'` | — |
| `title` | String | `'人员选择'` | 弹窗标题 |
事件 `@change="(tags, nameList, idList, list) => {}"`:
| 参数 | 内容 |
|---|---|
| `tags` | 选中的显示文本(数组) |
| `nameList` | 姓名数组 |
| `idList` | id 数组 |
| `list` | 完整对象数组(要存姓名时用这个) |
```js
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(按钮选人)
栅格/卡片里选人,或者需要"选择人员"按钮而不是输入框时用。
```vue
```
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `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-office-select(岗位选择)
```vue
```
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `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(组织树选择)
组织 / 校区 / 单位三合一的树选择器,支持数据权限过滤。
```vue
```
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `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(通用下拉树)
数据源完全自定义,适合分类、部门、地区这类自己管数据的树。
```vue
```
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `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(富文本)
```vue
```
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `modelValue` | String | `''` | HTML 字符串,`v-model` |
| `config` | Object | `{}` | jodit 配置覆盖项 |
内容存 HTML,展示时用 `v-html`。富文本里的图片地址依赖 `VITE_APP_PC_HOST` 配置。
---
## 十、s-tab(可滚动标签页)
标签多时自动出左右箭头,比 `a-tabs` 更适合列表页顶部。
```vue
```
`s-tab` 属性:`tabs`(`[{ label, value }]`)、`activeKey`(`v-model:activeKey`)、`defaultActiveKey`、`tabKey`(字段映射)、`stepRatio`(滚动步长)。
`s-tab-item` 属性:`value`、`label`(也可用默认插槽放富内容)。
---
## 十一、s-empty(空状态)
```vue
```
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `type` | String / Number | `1` | 插画风格 |
| `icon` | String / Object | `''` | 自定义图标 |
| `desc` | String / Boolean | — | 描述文案,传 `false` 不显示 |
| `iconStyle` | Object | `{}` | 图标样式 |
---
## 十二、s-icon(图标)
```vue
```
`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` 等)全部可直接使用,无需引入。