数据源及格式

为了更好地展示和分析数据，我们需要了解 VTable 中表格数据的格式及其意义。接下我们将讨论 VTable 中两种表格类型的数据形式：基本表格(ListTable)数据源和透视表格(PivotTable)数据源。

数据格式形式

在 VTable 中，我们需要处理的主要数据格式为 JSON 数组。例如，以下是以人的信息为例 JSON 数据：

[
  { "name": "zhang_san", "age": 20, "sex": "", "phone": "123456789", "address": "beijing haidian" },
  { "name": "li_si", "age": 30, "sex": "female", "phone": "23456789", "address": "beijing chaoyang" },
  { "name": "wang_wu", "age": 40, "sex": "male", "phone": "3456789", "address": "beijing fengtai" }
]

同时：二维数组的数据结构也是可以支持设置的。

接下来我们将分别介绍如何将这种数据应用到基本表格和透视表中。

基本表格数据

JSON 数据

在基本表格中，数据是以行为单位进行展示的，每一行含多个字段（列）。例如：姓名、年龄、性别、和地址。数据项中的每个对象将对应一行。

根据上述 JSON 数据创建一个基本表格应配置相应的 ListTableConstructorOptions 配项，并将 records 配置为数据源。

示例：

二维数组结构

如果使用二维数组作为数据源，可以按如下配置来运行：

多级数据特殊用法

多层级数据结构的数据源，可以通过设置 records 为 [{}] 来实现。如：

records:
    [
      {
        id: "7981",
        details:{
            productName:'fff'
        }
      }
    ]

details 作为数据条目中的一个对象，在数据源中，可以通过details.name来获取到对应的值。

需要再 columns 中需要这样配合上面的多级对象配置：

const columns =[
    {
        "field": ['details','productName'],
        "title": "Order productName",
        "width": "auto"
    },
]

效果如下图：

透视表数据

透视表格的主要目的是对数据进行多维度的展示和分析，在配置透视表格时，我们需要指定分组（行和列）维度以及指标维度。例如，我们可以将数据按照性别分组，并计算每个的人数和平均年龄。

其配置项为 PivotTableConstructorOptions。与基本表格类似，我们首先使用 JSON 数据作为透视表格的数据源。注意：这份数据是聚合分析之后的结果数据集

[
  { "age": 30, "sex": "male", "city": "北京", "income": 430 },
  { "age": 30, "sex": "female", "city": "上海", "income": 440 },
  { "age": 30, "sex ": "male", "city": "深圳", "income": 420 },
  { "age": 25, "sex": "male", "city": "北京", "income": 400 },
  { "age": 25, "sex": "female", "city": "上海", "income": 400 },
  { "age": 25, "sex ": "male", "city": "深圳", "income": 380 }
]

示例：

同时 records 数据格式还支持按逐个单元格对应配置：

records:[
    [430,650,657,325,456,500],
    [300,550,557,425,406,510],
    [430,450,607,455,560,400]
]

使用二维数组设置 records 示例：

数据接口

重置数据

可以使用 setRecords 来改变表格数据。具体可查看 api 文档。

添加数据

可以使用addRecords 或者 addRecord 来新增表格数据。具体可查看 api 文档。

删除数据

可以使用deleteRecords 来删除表格数据。具体可查看 api 文档。

修改数据

可以使用updateRecords 来修改表格数据。具体可查看 api 文档。

  /**
   * 修改数据 支持多条数据
   * @param records 修改数据条目
   * @param recordIndexs 对应修改数据的索引
   * 基本表格中显示在body中的索引，即要修改的是body部分的第几行数据；
   * 如果是树形结构的话 recordIndexs 为数组，数组中每个元素为data的原始数据索引；
   */
  updateRecords(records: any[], recordIndexs: (number | number[])[])

或者可以修改某一个数据字段利用changeCellValue或者changeCellValues接口来实现。

如果希望在筛选/排序状态下调用 addRecord/addRecords/deleteRecords/updateRecords 时也能同步修改到原始 records（例如清除筛选后新增行不丢失），可以在初始化配置中开启 syncRecordOperationsToSourceRecords。该配置也用于支持“筛选态新增草稿空行先保持可见，直到下一次 updateFilterRules 主动应用筛选才重新生效”的交互诉求。

树形结构数据更新

在普通的列表中，数据更新是传入的recordIndex为一个数值，代表改行数据在表格body中的索引。例如当recordIndex为0时，代表列表中的第一行数据。

当在树形（分组）结构中，recordIndex可能是一个数组，代表改节点从根节点开始的每级索引位置。尤其是在有排序的情况下，recordIndex是原始数据的结构，和在表格中显示的层级顺序可能不一致。因此在树形（分组）结构的表格中，请使用getRecordIndexByCell接口来获取目标位置的正确recordIndex，然后使用updateRecords等接口来更新数据。

const recordIndex = tableInstance.getRecordIndexByCell(col, row);
tableInstance.updateRecords([newRecord], [recordIndex]);

空数据提示

如果数据源不传，或者传入空数组，可以配置 emptyTip 来展示空数据提示。

提示信息和图标均是可配置的。

配置参考：https://visactor.io/vtable/option/ListTable#emptyTip

示例参考：https://visactor.io/vtable/demo/component/emptyTip

总结

在本教程中，我们学习了如何在 VTable 使用表格数据。我们首先了解了数据在表格中的意义，以及 VTable 中两种表格（基本表格和透视表格）的数据格式形式。为了帮助家更好地理解数据格式与表格的对应关系，我们分别讨论了基本表格和透视表格的对应关系。