# 组件文档 · 列表页 列表页三层结构:**工具栏**(标题 + 按钮)→ **查询区**(`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 ``` 其余字段与 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 ``` | 属性 | 类型 | 默认 | 说明 | |---|---|---|---| | `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 } }) } ```