列表页三层结构:工具栏(标题 + 按钮)→ 查询区(s-filter-item)→ 表格(s-table)。s-list-layout 把三层拼好并管高度,直接用即可。
<s-list-layout
ref="layoutRef"
:title="$l('岗位管理')"
:buttons="buttons"
:columns="columns"
:loadData="loadData"
:isSelection="true"
@reset="reset"
@btnCallback="btnCallback"
>
</s-list-layout>
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
title |
String | 必填 | 页面标题 |
loadData |
Function | 必填 | 取数函数,返回 { list, total } |
columns |
Array | [] |
列配置,见第四节 |
buttons |
Array | 添加/批量删除/导入/导出 | 工具栏按钮,传 [] 清空 |
isSelection |
Boolean | false |
显示 checkbox 列(配了 remove 按钮会自动开) |
showPagination |
Boolean | true |
是否分页 |
rowKey |
String / Function | 'id' |
行主键字段 |
pSize |
Number / String | 20 |
每页条数 |
selectedRowKeysArr |
Array | [] |
初始勾选的行 key(选择器弹窗场景) |
| 插槽 | 作用域 | 说明 |
|---|---|---|
filter |
— | 查询区主行,里面放 s-filter-wrap + s-filter-item |
filterMore |
— | 「更多」展开后的查询条件,有它才出现"更多/收起" |
otherBtns |
{ selections } |
工具栏按钮右侧追加内容 |
tree |
— | 左侧树,出现后自带拖拽分隔条 |
desc |
— | 查询区上方的说明文字区 |
tabs |
— | 表格上方的标签页区 |
empty |
— | 有它则整块内容区被替换(空状态/引导页) |
other |
— | 根节点末尾,通常放弹窗组件 |
<dataIndex> |
{ text, record, index, item } |
列插槽,列名即插槽名,见第四节 |
action |
{ record } |
操作列(dataIndex: 'action' 时生效) |
| 事件 | 参数 | 说明 |
|---|---|---|
reset |
— | 点了查询区"条件重置"。业务自己清空查询参数再调 reload() |
btnCallback |
(key, selectedRowKeys) |
点任意工具栏按钮都抛,业务在这里分发 |
tableColCallback |
(field, record) |
点了 isClick: true 的列 |
通过 ref 调用:
| 方法 / 属性 | 说明 |
|---|---|
reload() |
回到第一页重新请求 |
selectedRowKeys |
当前勾选的行 key 数组 |
spinning |
工具栏按钮请求中的 loading(内部用) |
setStateBtn(key, { show, disabled }) |
动态改按钮显隐/禁用,key 可传数组批量改 |
table |
内部 s-table 实例,需要更细操作时用 |
每项是一个对象:
const buttons = ref([
{ name: '添加', key: 'add', type: 'primary', icon: true },
{
name: '导入',
key: 'import',
icon: true,
importUploadUrl: IMPORT_UPLOAD_URL, // 上传地址
importColumns: importColumns, // 预览表头
importApis: { templateDownload, importPreview, importData, exportExceptionData }
},
{ name: '导出', key: 'export', icon: true, api: exportExcel },
{ name: '批量删除', key: 'remove', icon: true, api: deleteByIds, confirm: true }
])
| 字段 | 说明 |
|---|---|
name |
按钮文案,会过 $l() |
key |
唯一标识,同时作为按钮权限编码和 btnCallback 的第一个参数 |
show |
false 直接不渲染(默认 true) |
disabled |
禁用 |
type |
primary / default,不填时 add 自动 primary |
icon |
true 用内置图标(按 key 映射),也可传图标名字符串 |
api |
点击要调的接口,接收选中行 key 数组 |
confirm |
配了 api 时先弹确认框,确认后才调 |
selection |
false 时不校验是否勾选 |
内置 key 的行为:
| key | 行为 |
|---|---|
add |
只抛 btnCallback('add'),业务自己打开新增弹窗 |
remove / delete |
走 api(selectedRowKeys),自动校验"请选择要删除的数据",成功后刷新 |
import |
配了 importUploadUrl 就打开内置导入弹窗;没配则只抛 btnCallback('import') |
export |
走 api(),无选中行要求 |
其他自定义 key:配了 api 就走"校验勾选 → 确认 → 请求 → 提示 → 刷新";没配 api 就只抛 btnCallback,业务自己在事件里处理。
// 查询条件单独放一个 reactive,翻页参数由组件传进来
const queryParam = reactive({ name: undefined, type: undefined })
const loadData = (parameter = {}) => pageApi(queryParam, parameter)
parameter 是组件传进来的分页/排序对象:
{ pageNo: 1, pageSize: 20, sortField: '', sortOrder: '', ...filters }
返回值必须是:
{ list: [...], total: 100 }
list 字段名不能改,total 不能少,否则列表空白或分页错乱。{ list, total, pageNo },pageNo / pageNum 会被用来回填当前页。在 antd 列配置基础上加了三个约定字段:
| 字段 | 作用 |
|---|---|
template: true |
该列用同名插槽渲染,插槽名 = dataIndex |
isClick: true |
该列渲染成可点击的 <a>,点击抛 tableColCallback;值为对象时取 name 显示 |
dataIndex: 'action' |
操作列,用 #action 插槽渲染,一般配 fixed: 'right' |
const columns = ref([
{ title: '岗位名称', dataIndex: 'name', ellipsis: true, template: true },
{ title: '岗位编码', dataIndex: 'code', ellipsis: true },
{ title: '岗位类型', dataIndex: 'typeLabel', width: 150, align: 'center', ellipsis: true },
{ title: '是否启用', dataIndex: 'useable', width: 100, align: 'center', template: true },
{ title: '操作', dataIndex: 'action', width: 200, align: 'center', fixed: 'right' }
])
<template #name="{ record }">
<a @click="view(record)">{{ record.name }}</a>
</template>
<template #useable="{ record }">
<CheckOutlined v-if="record.useable" style="color: var(--s-color-success)" />
</template>
<template #action="{ record }">
<span v-action="'edit'">
<a @click="edit(record)">修改</a>
<a-divider type="vertical" />
</span>
<span v-action="'remove'">
<a style="color: red" @click="onDelete(record)">删除</a>
</span>
</template>
其余字段与 antd 的 a-table 列一致:width、align、ellipsis、fixed、sorter、customRender 都能用。
见 assets/list-page.vue,直接复制改字段即可。结构:
<s-list-layout>
#filter 主查询条件(输入框、下拉、日期)
#filterMore 更多条件
#name 等 列插槽
#action 操作列
#other 弹窗组件
</s-list-layout>
配合的脚本:
const layoutRef = ref(null)
const formRef = ref(null)
const queryParam = reactive({ name: undefined })
const loadData = (parameter = {}) => pageApi(queryParam, parameter)
const reload = () => layoutRef.value.reload()
const paramChange = () => reload() // 查询条件变化立刻刷新
const reset = () => { // 条件重置
Object.assign(queryParam, { name: undefined })
reload()
}
const btnCallback = (key) => {
if (key === 'add') formRef.value.add()
if (key === 'export') exportExcel(queryParam)
}
const edit = (record) => formRef.value.edit(record.id)
s-list-layout 内部已经把查询区画好了,直接用 s-filter-wrap + s-filter-item;只有在自定义页面里才单独用 s-filter-toolbar。
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
label |
String | 必填 | 标签文案 |
labelWidth |
Number | 70 |
标签宽度 px |
width |
Number | 280 |
整项宽度 px(含标签) |
full |
Boolean | false |
独占一行 |
colon |
Boolean | false |
标签后加冒号 |
mb |
Number | 0 |
底部间距 px |
isNormal |
Boolean | true |
true 描边样式;false 无边框(用于复选框、纯按钮) |
<template #filter>
<s-filter-wrap>
<s-filter-item label="名称">
<a-input v-model:value="queryParam.name" placeholder="请输入名称" @pressEnter="paramChange" />
</s-filter-item>
<s-filter-item label="状态">
<a-select v-model:value="queryParam.status" :allowClear="true" placeholder="请选择" @change="paramChange">
<a-select-option :value="1">启用</a-select-option>
<a-select-option :value="0">停用</a-select-option>
</a-select>
</s-filter-item>
<s-filter-item label="包含下级" :labelWidth="90" :isNormal="false">
<a-checkbox v-model:checked="queryParam.includeChild" @change="paramChange" />
</s-filter-item>
</s-filter-wrap>
</template>
s-filter-wrap 是 flex-wrap 容器,放多个 s-filter-item 自动换行;type="filter-more" 用于"更多"区。
| 插槽 | 说明 |
|---|---|
filter |
主查询行 |
filterMore |
更多查询行 |
| 事件 | 说明 |
|---|---|
reset |
点条件重置,业务清空参数后自行刷新 |
toggle |
更多区展开/收起,参数为是否展开 |
暴露 isMoreFilter、toggleFilter()、filterReset()、collapse()。
嵌在标签页、面板、抽屉里时不想要那 60px 标题条,用它:查询区 + 表格,没有工具栏。
<s-filter-table-toolbar
ref="tableRef"
:columns="columns"
:data="loadData"
:pageSize="20"
@reset="reset"
>
<template #filter>
<s-filter-wrap>
<s-filter-item label="名称">
<a-input v-model:value="queryParam.name" @pressEnter="refresh" />
</s-filter-item>
</s-filter-wrap>
</template>
<template #status="{ record }">
<a-tag :color="record.status ? 'green' : 'default'">{{ record.status ? '启用' : '停用' }}</a-tag>
</template>
</s-filter-table-toolbar>
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
data |
Function | 必填 | 取数函数,返回 { list, total } |
columns |
Array | [] |
列配置,template / isClick / action 同 s-list-layout |
rowKey |
String / Function | 'id' |
— |
pageSize |
Number | 10 |
— |
size |
String | 'middle' |
small / middle / large |
scrollX |
String / Number | '100%' |
横向滚动宽度 |
tableHeight |
Number | 300 |
表体最小高度,空间足够时按实际可用高度 |
事件 reset;方法 refresh(回第一页?)、reload()、resize()、tableRef。
s-table-toolbar 就是它去掉查询区,属性方法一致。
需要自己写工具栏、或者表格要放在非常规容器里时直接用。
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
data |
Function | 必填 | 取数函数,返回 { list, total } |
columns |
Array | — | antd 列配置 |
rowKey |
String / Function | 'key' |
默认是 'key',业务数据一般是 id,务必显式传 |
pageSize |
Number | 10 |
— |
pageNo |
Number | 1 |
— |
showPagination |
Boolean / 'auto' |
'auto' |
false 关闭分页 |
showSizeChanger |
Boolean | true |
显示每页条数切换 |
rowSelection |
Object | null |
同 antd,{ selectedRowKeys, onChange } |
loading |
Boolean | false |
外部控制的 loading |
expandedRowKeys |
Array | — | 展开行,v-model:expanded-row-keys |
方法:refresh(true) 回第一页刷新,refresh(false) 留在当前页。
<s-table ref="tableRef" :columns="columns" :data="loadData" rowKey="id" :pageSize="20" />
放在 s-list-layout 的 #tree 插槽里,出现后左侧自带拖拽分隔条。
<template #tree>
<s-tree
:levelOneChildren="levelOneChildren"
:levelTwoChildren="levelTwoChildren"
:expandAll="false"
@select:modelValue="onTreeSelect"
/>
</template>
| 属性 | 类型 | 说明 |
|---|---|---|
levelTwoChildren |
Function | 初始化根节点:调用时传空串 '',返回根级节点数组 |
levelOneChildren |
Function | 展开某节点时懒加载其子级,入参是节点 id |
expandAll |
Boolean | 是否默认展开全部 |
checkable |
Boolean | 显示复选框 |
showIcon |
Boolean | 显示节点图标 |
selectFirstOne |
Boolean | 初始化后自动选中第一个节点 |
modelValue |
String / Array | 选中项,v-model 双向绑定 |
节点数据按 antd 默认字段:title(显示文本)、key(唯一标识)、children。后端字段不一致时在 api 层 map:
const levelTwoChildren = async () => {
const list = await officeTree({ parentId: '' })
return list.map((o) => ({ ...o, title: o.name, key: o.id, value: o.id }))
}
选中事件拿到的是 antd 的 (selectedKeys, info),原始节点在 info.node.dataRef:
const selectNode = ref({})
const onTreeSelect = (keys, info) => {
const node = info?.node?.dataRef || {}
selectNode.value = info?.selected ? node : {}
queryParam.officeId = info?.selected ? node.id : undefined
layoutRef.value.reload()
}
loadData 收到的对象:
| 字段 | 来源 |
|---|---|
pageNo |
当前页(从 1 开始) |
pageSize |
每页条数 |
sortField |
排序列的 dataIndex,没排序时不传 |
sortOrder |
'ascend' / 'descend' |
| 其余 | 列的 filters 值 |
后端接口参数名不一致时在 api 层转换,页面层不用管:
// src/api/position.js
export function page(query = {}, parameter = {}) {
return window.$utils.http({
url: `/${window.$utils.env.VITE_APP_SYS_SERVER_NAME}/position/page`,
data: {
...query,
pageNum: parameter.pageNo,
pageSize: parameter.pageSize,
orderField: parameter.sortField,
orderType: parameter.sortOrder
}
})
}