# 组件文档 · 业务控件 基座已封好的业务级控件,全部全局注册,模板里直接写标签,不用 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` 等)全部可直接使用,无需引入。