# 组件文档 · 列表页
列表页三层结构:**工具栏**(标题 + 按钮)→ **查询区**(`s-filter-item`)→ **表格**(`s-table`)。`s-list-layout` 把三层拼好并管高度,直接用即可。
---
## 一、s-list-layout(标准列表页)
```vue
```
### Props
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `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` | — | 根节点末尾,通常放弹窗组件 |
| `` | `{ 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` 实例,需要更细操作时用 |
---
## 二、buttons 配置
每项是一个对象:
```js
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`,业务自己在事件里处理。
---
## 三、取数函数 loadData
```js
// 查询条件单独放一个 reactive,翻页参数由组件传进来
const queryParam = reactive({ name: undefined, type: undefined })
const loadData = (parameter = {}) => pageApi(queryParam, parameter)
```
`parameter` 是组件传进来的分页/排序对象:
```js
{ pageNo: 1, pageSize: 20, sortField: '', sortOrder: '', ...filters }
```
返回值必须是:
```js
{ list: [...], total: 100 }
```
- `list` 字段名不能改,`total` 不能少,否则列表空白或分页错乱。
- 也可以返回 `{ list, total, pageNo }`,`pageNo` / `pageNum` 会被用来回填当前页。
- 删完最后一条时组件会自动往前翻一页。
---
## 四、columns 配置
在 antd 列配置基础上加了三个约定字段:
| 字段 | 作用 |
|---|---|
| `template: true` | 该列用**同名插槽**渲染,插槽名 = `dataIndex` |
| `isClick: true` | 该列渲染成可点击的 ``,点击抛 `tableColCallback`;值为对象时取 `name` 显示 |
| `dataIndex: 'action'` | 操作列,用 `#action` 插槽渲染,一般配 `fixed: 'right'` |
```js
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' }
])
```
```vue
{{ record.name }}
修改
删除
```
其余字段与 antd 的 `a-table` 列一致:`width`、`align`、`ellipsis`、`fixed`、`sorter`、`customRender` 都能用。
---
## 五、完整列表页
见 `assets/list-page.vue`,直接复制改字段即可。结构:
```
#filter 主查询条件(输入框、下拉、日期)
#filterMore 更多条件
#name 等 列插槽
#action 操作列
#other 弹窗组件
```
配合的脚本:
```js
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-filter-toolbar / s-filter-wrap / s-filter-item
`s-list-layout` 内部已经把查询区画好了,**直接用 `s-filter-wrap` + `s-filter-item`**;只有在自定义页面里才单独用 `s-filter-toolbar`。
### s-filter-item
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `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` 无边框(用于复选框、纯按钮) |
```vue
启用
停用
```
`s-filter-wrap` 是 `flex-wrap` 容器,放多个 `s-filter-item` 自动换行;`type="filter-more"` 用于"更多"区。
### s-filter-toolbar(独立使用)
| 插槽 | 说明 |
|---|---|
| `filter` | 主查询行 |
| `filterMore` | 更多查询行 |
| 事件 | 说明 |
|---|---|
| `reset` | 点条件重置,业务清空参数后自行刷新 |
| `toggle` | 更多区展开/收起,参数为是否展开 |
暴露 `isMoreFilter`、`toggleFilter()`、`filterReset()`、`collapse()`。
---
## 七、无标题列表:s-filter-table-toolbar
嵌在标签页、面板、抽屉里时不想要那 60px 标题条,用它:查询区 + 表格,没有工具栏。
```vue
{{ record.status ? '启用' : '停用' }}
```
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `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` 就是它去掉查询区,属性方法一致。
---
## 八、s-table(裸表格)
需要自己写工具栏、或者表格要放在非常规容器里时直接用。
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `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)` 留在当前页。
```vue
```
---
## 九、左侧树 s-tree
放在 `s-list-layout` 的 `#tree` 插槽里,出现后左侧自带拖拽分隔条。
```vue
```
| 属性 | 类型 | 说明 |
|---|---|---|
| `levelTwoChildren` | Function | **初始化**根节点:调用时传空串 `''`,返回根级节点数组 |
| `levelOneChildren` | Function | **展开某节点**时懒加载其子级,入参是节点 id |
| `expandAll` | Boolean | 是否默认展开全部 |
| `checkable` | Boolean | 显示复选框 |
| `showIcon` | Boolean | 显示节点图标 |
| `selectFirstOne` | Boolean | 初始化后自动选中第一个节点 |
| `modelValue` | String / Array | 选中项,`v-model` 双向绑定 |
节点数据按 antd 默认字段:`title`(显示文本)、`key`(唯一标识)、`children`。后端字段不一致时在 api 层 map:
```js
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`:
```js
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 层转换,页面层不用管:
```js
// 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
}
})
}
```