grid 数据表格

带有分页栏的数据表格，集成了单选、多选、跨页选择等功能

v-grid 是基于 element-ui 的组合了 Table、Pagination 以及 Loading 等组件的功能模块，各组件原生文档内容可访问以下位置

• Table (opens new window)
• Pagination (opens new window)
• Loading (opens new window)

v-grid 完整继承 Table 的所有选项入参 props、事件 event、函数 methods 以及插槽 slot 等内容，并在此基础上增加业务常用功能封装，形成公司产品生态的标准化数据表格模块

安装

安装依赖

# 安装聚合包
npm i @plugins-core/main
# 安装独立功能库
npm i @plugins-core/grid

全局配置

import { post } from '@/config/settings/http'

// 聚合包
import { Grid } from '@plugins-core/main'
// 独立包
import Grid from '@plugins-core/grid'

// 全局安装 Grid 插件
Vue.use(Grid, {
  http: (url, data) => {
    return post(url, data)
  }
})

实际上，在业务项目使用的数据结构与表格定义的标准数据结构不一致时，除了通过配置 model 与 format prop 进行定制之外，也可以在此处进行全局安装并定义 http 函数时，对数据结构进行统一修改

关于 post 的内容可跳转至 HTTP 数据请求 位置查看

旧版包

import { post } from '@/config/settings/http'
import { Grid } from '@plugins/core'

// 全局安装 Grid 插件
Vue.use(Grid, {
  http: (url, data) => {
    return post(url, data)
  }
})

属性（prop）

设置 Grid 的功能与可定制内容

data 必填

• 类型：object | string

数据表格的数据源指定，object 对象格式则为应用本地数据进行功能调试，数据格式应用 数据表格标准返回格式 位置中指定的数据格式 。

通常情况下，指定一个数据接口 url 为数据源，表格将会对指定位置进行数据请求，该数据接口返回的数据格式也应满足上述位置中指定的数据格式

model @plugins-core 0.2.4+

• 类型：object
• 默认：Model

Model 的类型定义

{
  node: 'grid',
  totalRecords: 'total',
  dataList: 'list'
}

该模型内容描述了根据 数据表格标准返回格式 中定义的接口数据返回格式的部分关键数据节点名称。设置该 prop 的作用在于可按需对旧项目的旧数据结构进行适配

Vue.use(Grid, {
  model: {
    node: 'gridResult',
    totalRecords: 'totalRow',
    dataList: 'lists'
  },
  http: (url, data) => { ... }
})

height

• 类型：string | number

设置表格区域的高度，通常情况下，表格会应用根据内容自适应高度，在部分对内容区域高度有要求的场景，可自定义设置，该参数的设置值可参考 element-ui 官方对该值的描述

Table 的高度，默认为自动高度。如果 height 为 number 类型，单位 px；如果 height 为 string 类型，则这个高度会设置为 Table 的 style.height 的值，Table 的高度会受控于外部样式

index

• 类型：boolean
• 默认：false

显示序号列，该列显示了数据行的序号，该列与选择列（check）同时开启时，序号列则排在选择列之后

check

• 类型：boolean
• 默认：false

设置表格是否显示选择列（复选框多选），true 为多选模式启用，在该模式下，可手动选择多个数据行进行业务处理。默认为 false 单选模式，则选择列不显示，但表格行依然响应选择事件

params

• 类型：object

传递到服务端的查询参数，可将自定义的业务参数以及查询表单的查询字段合并到该参数中

format

• 类型：function

自定义格式化返回的表格原始数据

应用场景

• 表格数据格式与标准格式不一致
• 表格返回的数据中包含有它元素需要提取

注意：此处返回的数据模型，需与 model prop 中指定的模型一致，否则表格将无法解析数据

<template>
  <v-grid :format="format" />
</template>

<script>
// 自定义内容处理类
import { getStateName } from './state'

export default {
  methods: {
    // data 值为接口返回的原始数据集
    format (data) {
      const { total, list } = data.grid
      // 应用标准数据结构
      return {
        total: total,
        list: list.map(val => {
          // 此处仅举例将数据进行转换处理
          val.stateStr = getStateName(val.state)
          return val
        })
      }
    }
  }
}
</script>

如果使用了自定义数据结构，例如

{
  model: {
    node: 'gridResult',
    totalRecords: 'totalRow',
    dataList: 'results'
  }
}

则格式化函数应返回

function format () {
  return {
    totalRow: 10,
    results: [...]
  }
}

selected

• 类型：array

初始化表格已选中的项目

autoload

• 类型：boolean
• 默认：true

表格加载时，是否立即开始读取数据

例如：父子表格的场景，子表格的内容需取决于父表格选中的项目，在渲染后并不需要立即加载数据，此时可将子表格的 autoload 设置为 false

crossPagePick

• 类型：boolean
• 默认：false

跨页选择数据，启用该功能后，picked-change 事件响应的数据将是所有选中的数据行，而非当前页面选中的数据行

依赖

该功能依赖于 check prop 须设置为 true

blankText

• 类型：string
• 默认：'暂无数据'

表格无数据时显示的提示文本

pagination

• 类型：boolean
• 默认：true

是否使用分页栏

currentPage

• 类型：number
• 默认：1

加载表格时，直接跳转至指定的页码

pagerCount

• 类型：number
• 默认：7

分页栏中显示的页码个数

pageLength

• 类型：number
• 默认：10

每页加载的记录数

pageLengthList

• 类型：number[]
• 默认：[10, 20, 50, 100, 200]

每页显示记录数列表

paginationLayout

• 类型：string
• 默认：->, sizes, slot, prev, pager, next

hidePaginationWhenNoData

• 类型：boolean
• 默认：true

表格无数据时，自动隐藏分页栏

loadingTransition

• 类型：boolean
• 默认：true

使用 loading 动画过渡表格数据加载

loadingOverlay

• 类型：boolean
• 默认：true

表格数据加载过程显示覆盖整个表格的遮罩，阻止多余操作

可全局设置的 prop

• blankText
• pageLength
• pageLengthList
• model

// 全局设置样例
Vue.use(Grid, {
  blankText: '您的角色无相关数据',
  pageLength: 30,
  http: (url, data) => { ... }
})

函数（method）

函数需要通过定义 ref 来获得 v-grid 的组件对象引用，再访问相关函数

<template>
  <div>
    <button type="button" @click="reload">查询表格</button>
    <v-grid ref="grid" />
  </div>
</template>

<script>
export default {
  methods: {
    reload () {
      this.$refs.grid.reload()
    }
  }
}
</script>

grid

获得表格原生实例，使用返回的对象即可调用 element table 原生函数

grid(): object

函数使用示例

{
  methods: {
    doSomething () {
      // 获得 element-ui table 原生对象
      const grid = this.$refs.grid.grid()
      // 调用 element-ui table 原生函数 setCurrentRow
      grid.setCurrentRow({ row-data })
    }
  }
}

page

获得表格中的分页栏原生实例，使用返回的对象即可调用 element pagination 原生函数，使用方式类同 grid 函数

page(): object

reload

刷新表格、使用新的查询条件查询表格

reload(): void

函数使用示例

<template>
  <div>
    年度：<input type="text" v-model="searchParams.year">
    <button type="button" @click="search">查询表格</button>
    <v-grid ref="grid" :params="searchParams"></v-grid>
  </div>
</template>

<script>
export default {
  data () {
    return {
      searchParams: {
        // 设置默认年度为当前年度
        year: new Date().getFullYear().toString()
      }
    }
  },
  methods: {
    search () {
      // 表格数据查询前对数据进行处理
      if (!this.searchParams.year) {
        this.searchParams.year = new Date().getFullYear().toString()
      }
      // 处理好查询参数后，刷新表格当前页
      this.$refs.grid.reload()
    }
  }
}
</script>

clearSelection

清除表格选中的行

clearSelection(row: object): void

在绝大多数情况下，调用该函数可清除所有选中的行

在多选模式下，调用函数且传递行数据时（行的原始数据），则仅清除指定行的选中状态

clearGrid

完全重置表格，清除表格数据

clearGrid(): void

事件（event）

数据表格的响应事件，在 v-grid 上可直接使用 element-ui 的 table 组件的所有原生事件，文中列出的是 v-grid 表格插件定制化的事件

<template>
  <div>
    <!--
    done 是 v-grid 自定义的事件
    row-click 是 element-ui table 组件的原生行点击事件
    -->
    <v-grid
      @done="loaded"
      @row-click="rowClick"
    >
    </v-grid>
  </div>
</template>

<script>
export default {
  methods: {
    loaded (data) {
      ...
    },
    rowClick (row, column, event) {
      ...
    }
  }
}
</script>

picked-change

行选中结果发生变化时触发的事件，返回的 data 入参为已选中行的原始数据

'picked-change'(data: object[]): void

done

表格数据加载完成后触发的事件，返回的 data 入参为当前分页相关信息，数据格式如下

done(data: PageInfo): void

interface PageInfo {
  pageNumber: number
  pageSize: number
  totalRow: number
}

loading-change

响应表格 loading 状态的事件

'loading-change'(data: boolean): void

插槽（slot）

可自定义内容的插槽位置

no-data

自定义表格无数据时的提示内容

提示

组件已默认集成了无数据提示的处理流程，通常情况下，初始化表格不加载数据（autoload: false）与使用 clearGrid 函数重置表格后等场景仅显示空白表格，在进行数据加载后且无数据的情况下，显示出无数据的提示与图标

也就是无数据提示仅与数据加载行为关联，其他状态下展示空表格

需要注意的是：若自定义了该插槽，则失去了上述控制逻辑

插槽使用示例

<template>
  <v-grid>
    <!--
      也可以使用缩写
      <template #no-data>
    -->
    <template v-slot:no-data>
      <div>暂时没有相关的数据</div>
    </template>
  </v-grid>
</template>

footer

分页栏左侧空白区域插槽

<template>
  <v-grid>
    <template v-slot:footer>
      <div>自定义内容</div>
    </template>
  </v-grid>
</template>

loading

通常应用于自定义 loading 过渡的插槽。实际上它只是提供了一个位于 v-grid 根节点下的元素插槽，可以适用于制作全表格覆盖的遮罩(使用绝对布局)或是在分页栏以下扩展的内容区域

以下是一个自定义 loading 内容的应用实例

<template>
  <v-grid
    :loading-transition="false"
    @loading-change="loadingChange"
  >
    <template v-slot:loading>
      <!-- 设置绝对定位，并覆盖全表格 -->
      <div
        style="position: absolute;top: 0;left: 0;bottom: 0;right: 0;"
        v-if="loading"
      >
      自定义 loading 内容
      </div>
    </template>
  </v-grid>
</template>

<script>
export default {
  data () {
    return {
      loading: false
    }
  },
  methods: {
    loadingChange (val) {
      this.loading = val
    }
  }
}
</script>

实例中通过设置 loading-transition prop 关闭内置的 loading 动画效果，并应用了 loading-change 事件响应的 loading 状态来控制自定义内容的显示，使功能应用逻辑完整