|
|
@@ -0,0 +1,426 @@
|
|
|
+# 组件文档 · 列表页
|
|
|
+
|
|
|
+列表页三层结构:**工具栏**(标题 + 按钮)→ **查询区**(`s-filter-item`)→ **表格**(`s-table`)。`s-list-layout` 把三层拼好并管高度,直接用即可。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 一、s-list-layout(标准列表页)
|
|
|
+
|
|
|
+```vue
|
|
|
+<s-list-layout
|
|
|
+ ref="layoutRef"
|
|
|
+ :title="$l('岗位管理')"
|
|
|
+ :buttons="buttons"
|
|
|
+ :columns="columns"
|
|
|
+ :loadData="loadData"
|
|
|
+ :isSelection="true"
|
|
|
+ @reset="reset"
|
|
|
+ @btnCallback="btnCallback"
|
|
|
+>
|
|
|
+</s-list-layout>
|
|
|
+```
|
|
|
+
|
|
|
+### 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` | — | 根节点末尾,通常放弹窗组件 |
|
|
|
+| `<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` 实例,需要更细操作时用 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 二、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` | 该列渲染成可点击的 `<a>`,点击抛 `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
|
|
|
+<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>
|
|
|
+```
|
|
|
+
|
|
|
+配合的脚本:
|
|
|
+
|
|
|
+```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
|
|
|
+<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"` 用于"更多"区。
|
|
|
+
|
|
|
+### s-filter-toolbar(独立使用)
|
|
|
+
|
|
|
+| 插槽 | 说明 |
|
|
|
+|---|---|
|
|
|
+| `filter` | 主查询行 |
|
|
|
+| `filterMore` | 更多查询行 |
|
|
|
+
|
|
|
+| 事件 | 说明 |
|
|
|
+|---|---|
|
|
|
+| `reset` | 点条件重置,业务清空参数后自行刷新 |
|
|
|
+| `toggle` | 更多区展开/收起,参数为是否展开 |
|
|
|
+
|
|
|
+暴露 `isMoreFilter`、`toggleFilter()`、`filterReset()`、`collapse()`。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 七、无标题列表:s-filter-table-toolbar
|
|
|
+
|
|
|
+嵌在标签页、面板、抽屉里时不想要那 60px 标题条,用它:查询区 + 表格,没有工具栏。
|
|
|
+
|
|
|
+```vue
|
|
|
+<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` 就是它去掉查询区,属性方法一致。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 八、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-table ref="tableRef" :columns="columns" :data="loadData" rowKey="id" :pageSize="20" />
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 九、左侧树 s-tree
|
|
|
+
|
|
|
+放在 `s-list-layout` 的 `#tree` 插槽里,出现后左侧自带拖拽分隔条。
|
|
|
+
|
|
|
+```vue
|
|
|
+<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:
|
|
|
+
|
|
|
+```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
|
|
|
+ }
|
|
|
+ })
|
|
|
+}
|
|
|
+```
|