02-组件文档-列表页.md 14 KB

组件文档 · 列表页

列表页三层结构:工具栏(标题 + 按钮)→ 查询区(s-filter-item)→ 表格(s-table)。s-list-layout 把三层拼好并管高度,直接用即可。


一、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>

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 配置

每项是一个对象:

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

// 查询条件单独放一个 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 会被用来回填当前页。
  • 删完最后一条时组件会自动往前翻一页。

四、columns 配置

在 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-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 无边框(用于复选框、纯按钮)
<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 标题条,用它:查询区 + 表格,没有工具栏。

<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) 留在当前页。

<s-table ref="tableRef" :columns="columns" :data="loadData" rowKey="id" :pageSize="20" />

九、左侧树 s-tree

放在 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
    }
  })
}