04-组件文档-业务控件.md 13 KB

组件文档 · 业务控件

基座已封好的业务级控件,全部全局注册,模板里直接写标签,不用 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(上传)

<s-file-upload
  path="sysEmployee"
  :list="fileList"
  :maxFileCount="1"
  accept="image/*"
  listType="card"
  @handChange="onFileChange"
/>
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 点下载

列表项结构

{ 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(弹窗选人)

点输入框弹出选人窗口,适合表单里选一个/多个人。

<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(下拉选人)

表单里最常用的选人控件,外观是下拉框,点开是选人面板。

<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(按钮选人)

栅格/卡片里选人,或者需要"选择人员"按钮而不是输入框时用。

<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-office-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(组织树选择)

组织 / 校区 / 单位三合一的树选择器,支持数据权限过滤。

<!-- 选组织(带数据权限) -->
<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(通用下拉树)

数据源完全自定义,适合分类、部门、地区这类自己管数据的树。

<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(富文本)

<s-editor v-model="form.content" :config="{ minHeight: 300 }" />
属性 类型 默认 说明
modelValue String '' HTML 字符串,v-model
config Object {} jodit 配置覆盖项

内容存 HTML,展示时用 v-html。富文本里的图片地址依赖 VITE_APP_PC_HOST 配置。


十、s-tab(可滚动标签页)

标签多时自动出左右箭头,比 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(空状态)

<s-empty :desc="$l('暂无数据')" />
属性 类型 默认 说明
type String / Number 1 插画风格
icon String / Object '' 自定义图标
desc String / Boolean — 描述文案,传 false 不显示
iconStyle Object {} 图标样式

十二、s-icon(图标)

<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 等)全部可直接使用,无需引入。