列表示例

列表查询和基于列表数据的操作也是中后台系统的基本功能。Vue Admin Next 的示例模块中，实现了部分列表页通用的开发模式。

完整的源码可参考 src/modules/table，以下是功能简介。

Composition API

这里使用了 Vue Use 项目的 useTable API。

useTable

一般列表页中，都会包含表格、翻页、查询表单、快捷查询等组件，这些操作都会触发表格数据的更新。为了简化互相之间的交互，把通用的逻辑都封装在了 useTable 组合中，大致实现如下。

import { ref, reactive, computed, watch } from '@vue/composition-api'

function useTable(options = {}) {
  const state = reactive({
    // 初始翻页参数 pageNo pageSize orderBy order(asc|desc)
    initialPage: {},
    // 初始过滤条件
    initialFilter: {},
    // 当前翻页参数
    page: {},
    // 当前过滤条件
    filter: {},
    // 当前表格的数据
    list: {},
    // 当前表格选中的数据
    selection: [],
    // 当前表格跨页选择的数据
    crossPageSelection: [],
  })

  // 此处省略实现逻辑

  return {
    // 响应式数据
    state,
    // 转化为自定义格式的初始排序方式
    customPageSorter,

    // 更新表格的数据
    setList,

    // 更新翻页参数
    setPage,
    // 重置翻页参数
    resetPage,
    // 设置初始翻页参数
    setInitialPage,

    // 更新过滤条件
    setFilter,
    // 重置过滤条件
    resetFilter,
    // 设置初始过滤条件
    setInitialFilter,

    // 设置排序方式
    setPageSort,
    // 设置每页数据条数
    setPageSize,
    // 设置当前页数
    setPageNo,

    // 设置当前选择项
    setSelection,
    // 添加跨页选择项
    addCrossPageSelection,
    // 移除跨页选择项
    removeCrossPageSelection,
    // 清空跨页选择项
    clearCrossPageSelection,

    // 发送更新消息
    triggerUpdate,
    // 监听更新消息，接收回调函数（发起请求等）
    watchUpdate,
  }
}

export { useTable }

基本使用方法

以下为部分源码展示，详细信息可参考 src/modules/table/pages/basic。

外层组件 example-basic-list，用于组合各个子组件，同时调用 useTable 获取状态和方法。

<template>
  <div>
    <el-card>
      <example-query-form :table="table"></example-query-form>
    </el-card>

    <el-card>
      <example-table :table="table"></example-table>
      <example-query-page :table="table"></example-query-page>
    </el-card>
  </div>
</template>

<script>
import { useTable } from '@fext/vue-use'
import TableComponents from './components'

export default {
  name: 'example-basic-list',

  components: {
    ...TableComponents,
  },

  setup() {
    const table = useTable({
      uniqueKey: 'id',
      sortKeys: {
        order: 'order',
        orderBy: 'prop',
        asc: 'ascending',
        desc: 'descending',
      },
    })
    const { state, setInitialPage } = table

    return {
      table,

      state,

      setInitialPage,
    }
  },

  created() {
    this.setInitialPage({
      pageNo: 1,
      pageSize: 10,
      orderBy: 'id',
      order: 'asc',
    })
  },
}
</script>

查询表单组件 example-query-form 用于输入过滤条件，同时可以手动触发表格数据更新：

<template>
  <el-form size="medium" @keyup.native.enter="search">
    <!-- 表单元素，直接绑定到 state.filter.id -->
    <example-query-id v-model="state.filter.id"></example-query-id>
    <el-button size="medium" type="primary" @click="search">搜索</el-button>
    <el-button size="medium" @click="reset" title="RESET">重置</el-button>
  </el-form>
</template>

<script>
export default {
  name: 'example-query-form',

  props: {
    // 外层组件传递的 useTable 生成的状态空间
    table: {
      type: Object,
      required: true,
    },
  },

  setup(props) {
    const {
      state,
      setPage,
      setFilter,
      resetFilter,
      setInitialFilter,
      triggerUpdate,
    } = props.table

    return {
      state,
      setPage,
      setFilter,
      resetFilter,
      setInitialFilter,
      triggerUpdate,
    }
  },

  created() {
    // 设置初始过滤条件
    this.setInitialFilter(this.getInitialValues())
  },

  methods: {
    getInitialValues() {
      return {
        id: '',
      }
    },

    // 重置为初始过滤条件，并触发查询
    reset() {
      this.resetFilter()
      this.search()
    },

    // 查询操作，当前页码设置为 1
    search() {
      this.setPage({
        pageNo: 1,
      })
      // 触发更新
      this.triggerUpdate()
    },
  },
}
</script>

翻页组件 example-query-page 用于设置当前页码和每页的条数，也会触发表格数据的更新：

<template>
  <div>
    <!-- 将翻页组件的状态和事件处理方法绑定至 useTable 生成的状态空间 -->
    <el-pagination
      background
      :page-sizes="pageSizes"
      layout="total, sizes, prev, pager, next, jumper"
      @size-change="setPageSize"
      @current-change="setPageNo"
      :current-page="state.page.pageNo"
      :page-size="state.page.pageSize"
      :total="state.list.totalCount"
    >
    </el-pagination>
  </div>
</template>

<script>
export default {
  name: 'example-query-page',

  props: {
    // 外层组件传递的 useTable 生成的状态空间
    table: {
      type: Object,
      required: true,
    },
  },

  setup(props) {
    const { state, setPageSize, setPageNo } = props.table

    return {
      state,
      setPageSize,
      setPageNo,
    }
  },

  data() {
    return {
      pageSizes: [5, 10, 20, 40, 80],
    }
  },
}
</script>

最后是主角 example-table，用于展示最终查询得到的表格数据：

<template>
  <div>
    <!-- 将表格数据、排序方式、选择数据等操作绑定至 useTable 生成的状态空间 -->
    <el-table
      :data="state.list.result"
      :default-sort="customPageSorter"
      @sort-change="setPageSort"
      @selection-change="setSelection"
    >
      <!-- columns -->
    </el-table>
  </div>
</template>

<script>
export default {
  name: 'example-table',

  props: {
    // 外层组件传递的 useTable 生成的状态空间
    table: {
      type: Object,
      required: true,
    },
  },

  setup(props) {
    const {
      state,
      customPageSorter,
      setPageSort,
      setList,
      setSelection,
      watchUpdate,
    } = props.table

    return {
      state,
      customPageSorter,
      setPageSort,
      setList,
      setSelection,
      watchUpdate,
    }
  },

  // 通过计算属性将 page 和 filter 整合为接口所需的查询格式
  computed: {
    query() {
      const { page, filter } = this.state
      return {
        page,
        filter,
      }
    },
  },

  created() {
    // 监听其它组件发生的更新信号，执行拉取数据操作
    this.watchUpdate(() => {
      this.fetchList()
    })
  },

  methods: {
    async fetchList() {
      // 调用远程服务
      return this.$services.exampleListService
        .getList({
          data: this.query,
        })
        .then((list) => {
          // 更新表格数据
          this.setList(list)
        })
    },
  },
}
</script>

快捷查询

用户通常有把几个过滤条件的值组合到一起一键查询的操作。通过 Composition API 提供的方法，可以非常便捷地实现该功能。以下是 example-quick-query 组件部分源码参考：

<template>
  <el-form>
    <ul class="list-inline vertical-space-10 horizontal-space-10">
      <li>
        <span>常用查询：</span>
      </li>
      <!-- 展示所有快捷查询条件，点击时触发查询 -->
      <li v-for="query in queries" :key="query.name">
        <a @click="updateQuery(query)">{{ query.name }}</a>
      </li>
    </ul>
  </el-form>
</template>

<script>
export default {
  name: 'example-quick-query',

  props: {
    // 外层组件传递的 useTable 生成的状态空间
    table: {
      type: Object,
      required: true,
    },
  },

  setup(props) {
    const { state, setFilter, triggerUpdate } = props.table

    return {
      state,

      setFilter,
      triggerUpdate,
    }
  },

  data() {
    return {
      // 可以保存至数据库、LocalStorage 等
      queries: [
        {
          name: 'ID - 1000',
          filter: {
            id: 1000,
          },
        },
        {
          name: '标题 - Next',
          filter: {
            q: 'Next',
          },
        },
      ],
    }
  },

  methods: {
    updateQuery(query) {
      // 更新过滤条件
      this.setFilter(query.filter || {}, {
        merge: false,
      })
      // 触发数据更新操作
      this.triggerUpdate()
    },
  },
}
</script>

数据选择和批量操作

一般情况下，通过 useTable 的 selection 状态就可以获取到当前页选择的数据。但是某些情况下，可能会存在需要从不同的查询结果中挑选一些数据进行批量操作，因此为了解决跨页选择的问题，useTable 内部维护了一个 crossPageSelection 的状态和对应的更新方法，但是并没有可视化的交互组件。由于这个功能比较通用，Vue Admin Next 将其封装成了一个通用的组件，放在了 src/common/components/extend/table-selection-ultimate 目录。

下面演示一下它的基础使用方法：

<template>
  <el-form>
    <!-- 需要传递 useTable 生成的状态空间 -->
    <table-selection-ultimate
      ref="ultimateSelection"
      :table="table"
    ></table-selection-ultimate>
  </el-form>
</template>

<script>
import { TableSelectionUltimate } from '@/common/components/extend/table-selection-ultimate'

export default {
  name: 'example-toolbar',

  components: {
    TableSelectionUltimate,
  },

  props: {
    // 外层组件传递的 useTable 生成的状态空间
    table: {
      type: Object,
      required: true,
    },
  },

  setup(props) {
    const { state } = props.table

    return {
      state,
    }
  },

  methods: {
    async getSelection() {
      // 1. 仅返回当前页选择的数据（不需要 table-selection-ultimate 组件）
      return this.state.selection

      // 2. 返回跨页选择的数据
      return this.state.crossPageSelection

      // 3. 都存在的情况下可以由用户进行选择
      return this.$refs.ultimateSelection.use()
    },
  },
}
</script>

基于选择的数据，你就可以进行任意的批量操作了。

提示

table-selection-ultimate 的 use 方法会进行如下判断：1）若仅存在当前页数据则直接使用当前页数据；2）若仅存在跨页数据则直接使用跨页数据；3）若当前页和跨页数据都存在，则需要用户进行选择。

导出表格数据

Vue Admin Next 中通过 json2csv 将 JSON 数据转换为 CSV 文件并下载。此功能封装到了工具函数 src/common/utils/export.js 中。

使用方法参考示例模块的代码：src/modules/table/pages/basic/components/ExampleToolbar.vue。导出操作同样也使用到了数据选择的功能。

显示更多查询项

在比较复杂的模块中，随着业务的不断迭代，可能会有几十个表单查询项。如果全部都默认展示的话，使用体验较差。因此 Vue Admin Next 示例模块中通过 popover 和 tab 来展示不常有的查询项，节省页面空间。

源码参考：

• src/modules/table/pages/basic/components/ExampleQueryForm.vue
• src/modules/table/pages/basic/components/form/advanced

显示更多数据详情

在部分列表页场景下，用户关心的数据维度较多，在屏幕宽度有限的情况下，无法全部展示。虽然 el-table 通过 expand 列提供了展开收起的功能。但是依然不够便捷。Vue Admin Next 采用了 popover 的形式，在鼠标移动到每行 “更多数据” 链接的时候，就可以展示当前行需要的全部数据。

源码参考：

• src/modules/table/pages/basic/components/ExampleTable.vue
• src/modules/table/pages/basic/components/table/ExampleMoreColumn.vue

提示

为了避免渲染过多 popover，组件 example-table 通过设置 currentRow 并判断是否当前列来优化。

显示更多操作项

在部分列表页场景下，用户需要的操作非常多，一列的空间无法摆放。因此 Vue Admin Next 采用了 popover 和 tab 的形式，在鼠标移动到每行 “更多操作” 链接的时候，就可以展示所有操作按钮。

源码参考：

• src/modules/table/pages/basic/components/ExampleTable.vue
• src/modules/table/pages/basic/components/table/ExampleMoreLink.vue

提示

为了避免渲染过多 popover，组件 example-table 通过设置 currentRow 并判断是否当前列来优化。