基本表格排序功能

在数据分析过程中，排序（排序）功能对数据的组织和协助分析非常重要。通过排序，用户可以快速将关心的数据排列在前面，提高数据查找和分析的效率，同时也能快速发现数据中的异常点和规律。

VTable 提供了丰富的排序功能，用户可以轻松地按需开启、自定义排序规则、设定初始排序状态等。

开启排序

要使用 VTable 的排序功能，需要先对表格列进行配置。在 columns 中，每一列的配置项需要根据 cellType（列类型）进行设置。在本教程中，我们主要关注排序相关的配置。

以下是一个开启排序功能的例子：

const listTable = new ListTable({
  // ...其它配置项
  columns: [
    {
      title: '姓名',
      field: 'name',
      cellType: 'text',
      sort: true // 使用内置默认排序逻辑
    },
    {
      title: '年龄',
      field: 'age',
      cellType: 'text',
      sort: (v1, v2, order) => {
        // 使用自定义排序逻辑
        if (order === 'desc') {
          return v1 === v2 ? 0 : v1 > v2 ? -1 : 1;
        }
        return v1 === v2 ? 0 : v1 > v2 ? 1 : -1;
      }
    }
  ]
});

在上述代码中，sort 为 true，表示该列支持排序，并使用内置的排序规则。

排序规则设置

VTable 允许用户自定义排序规则。如自定义排序规则，需要将 sort 设置为一个函数。该函数接收两个参数 a 和 b，表示需要比较的两个值。函数返回值为负数时，a 排在 b 前面；返回值为正数时，a 排在 b 后面；返回值为 0 时，a 和 b 的相对位置不变。

以下是一个自定义排序规则的例子：

const listTable = new ListTable(document.getElementById(CONTAINER_ID), {
  // ...其它配置项
  columns: [
    {
      title: '姓名',
      field: 'name',
      cellType: 'text',
      sort: (a, b) => a.localeCompare(b)
    },
    {
      title: '年龄',
      field: 'age',
      cellType: 'text',
      sort: (a, b) => parseInt(a) - parseInt(b)
    }
  ]
});

在上述代码中，姓名 列使用 localeCompare 函数进行排序，以保证中文字符的正确排序结果；年龄 列根据数字大小进行排序。

多列排序

当启用 multipleSort 选项时，VTable 允许按多列排序。此功能允许用户按多列对表中的数据进行排序，从而根据多个条件提供更详细的数据视图。要启用多列排序，请在 ListTable 配置中配置 multipleSort 选项。

multipleSort 选项是布尔类型，可以按如下方式设置：

ListTable({
  // ...其他配置项
  columns: [
    // ...色谱柱配置
  ],
  multipleSort: true
});

如果启用，用户在单击列标题中的排序图标时，可以添加其他排序条件，而无需删除之前的排序。

例子：

初始排序状态

VTable 支持为表格设定初始排序状态。要设置初始排序状态，可以在 ListTable 配置项中使用 sortState 配置。sortState 类型为 SortState 或 SortState[]。其中，SortState 定义如下：

SortState {
  /** 排序依据字段 */
  field: string;
  /** 排序规则 */
  order: 'desc' | 'asc' | 'normal';
}

以下是一个设置初始排序状态的例子：

const tableInstance = new ListTable({
  // ...其它配置项
  columns: [
    // ...列配置
  ],
  sortState: [
    {
      field: 'age',
      order: 'desc'
    }
  ]
});

在上述代码中，表格的初始排序状态为按照年龄降序排列。

排序状态设置接口(更改排序)

VTable 提供 updateSortState 属性用于设置排序状态。接口说明：

  /**
   * 更新排序状态
   * @param sortState 要设置的排序状态
   * @param executeSort 是否执行内部排序逻辑，设置false将只更新图标状态不执行数据排序
   */
  updateSortState(sortState: SortState[] | SortState | null, executeSort: boolean = true)

当需要修改排序状态时，可以直接调用该接口。例如：

tableInstance.updateSortState({
  field: 'name',
  order: 'asc'
});

通过使用 updateSortState 接口，用户可以在任意时刻动态调整表格的排序状态，以满足实时分析需求。

禁用内部排序

在某些场景下，排序逻辑的执行并不期望由 VTable 来执行，如：后端负责排序。

可以按照如下配置和流程来使用：

配置 sort 为 false；
如果需要显示排序按钮，配置 sortState 为 true；
通过监听事件 sort_click事件来得知用户点击了排序按钮，注意这个事件回调函数需要返回 false 来禁止 VTable 内部的排序逻辑：

tableInstance.on('sort_click', args => {
    .....
    return false; //return false代表不执行内部排序逻辑
  });

监听排序按钮点击后，执行业务层的排序逻辑。排序完成后需要 setRecords 将数据更新到表格。注意：

setRecords 接口调用时需将第二个参数 option 中的 sortState 设置为 null，这样就清除了内部排序状态（否则 setRecords 调用时 vtable 会按上次设置过的排序状态对数据进行排序）

如果需要对应切换排序图标的状态则需要配合接口updateSortState，注意接口的第二个参数需设置为 false，这样可以只切换排序图标而不执行 vtable 的排序逻辑.

示例：

替换默认的排序图标

如果不希望使用内部的图标，可以使用图标自定义功能来替换，接参考教程：https://www.visactor.io/vtable/guide/custom_define/custom_icon

以下是一个替换排序图标的例子：

注意： name和funcType的配置

VTable.register.icon("frozenCurrent", {
  type: "svg",
  svg: "/sort.svg",
  width: 22,
  height: 22,
  name: "sort_normal",
  positionType: VTable.TYPES.IconPosition.left,
  marginRight: 0,
  funcType: VTable.TYPES.IconFuncTypeEnum.sort,
  hover: {
    width: 22,
    height: 22,
    bgColor: "rgba(101, 117, 168, 0.1)",
  },
  cursor: "pointer",
});

隐藏排序图标

我们提供了showSort配置来隐藏排序图标，但可以正常执行排序逻辑

以下是一个隐藏排序图标的例子：

const listTable = new ListTable({
  // ...其它配置项
  columns: [
    {
      title: '姓名',
      field: 'name',
      cellType: 'text',
      showSort: false,
      sort: true // 使用内置默认排序逻辑
    },
    {
      title: '年龄',
      field: 'age',
      cellType: 'text',
      showSort: false,
      sort: (v1, v2, order) => {
        // 使用自定义排序逻辑
        if (order === 'desc') {
          return v1 === v2 ? 0 : v1 > v2 ? -1 : 1;
        }
        return v1 === v2 ? 0 : v1 > v2 ? 1 : -1;
      }
    }
  ]
});

预排序

在大数据量的情况下，首次排序可能会耗时较长，可以通过预排序来提升排序功能的性能。通过 setSortedIndexMap 方法，设置预排序的数据字段和排序顺序。

interface ISortedMapItem {
  asc?: (number | number[])[];
  desc?: (number | number[])[];
  normal?: (number | number[])[];
}

const tableInstance = new VTable.ListTable(document.getElementById(CONTAINER_ID),option);
tableInstance.setSortedIndexMap(field, filedMap as ISortedMapItem);