跳到主要内容

VISALL 多维表格 (MultiTable) 使用文档

简介​

多维表格组件是VISALL数据可视化库中的文本类图表，支持横向一维表格、纵向一维表格、多维表格以及树状表格等多种展现形式。该组件能够灵活处理多维数据，适用于各种结构化数据的表格展示场景。

基本用法​

import { render } from 'path/to/bundle.esm.min.js';

// 创建多维表格
const chart = render(container, {
  layers: [
    {
      type: 'multiTable',
      dataIndex: 0,
      encoding: {
        rows: ['产品'], // 行字段名
        columns: ['销售额'] // 列字段名
      }
    }
  ],
  data: [
    {
      values: [
        { 产品: '产品A', 销售额: 320 },
        { 产品: '产品B', 销售额: 120 },
        { 产品: '产品C', 销售额: 220 },
        // ...更多数据
      ]
    }
  ]
});

配置参数​

参数类型默认值说明
encoding.rowsstring[]-行映射字段，用于定义表格行
encoding.columnsstring[]-列映射字段，用于定义表格列
dataIndexnumber0指定使用的数据集索引
isTreeTablebooleanfalse是否启用树状表格模式
maxHeightnumber400表格最大高度（像素）
widthnumber400表格宽度（像素）
columnsNumnumber2横向表格的列数，必须为偶数
pageSizenumber10分页大小
currentPagenumber1当前页码
customEventfunction-自定义事件处理函数

数据要求​

  • 数据必须是对象数组格式
  • 字段名必须与encoding中指定的字段名匹配
  • 树状表格需要特定的数据结构
  • 数据量至少需要大于0条

高级用法​

1. 横向一维表格​

适用于简单的键值对显示：

{
  type: 'multiTable',
  encoding: {
    rows: ['产品名称'],
    columns: []
  },
  columnsNum: 2
}

2. 纵向一维表格​

适合展示单列数据：

{
  type: 'multiTable',
  encoding: {
    rows: [],
    columns: ['销售额']
  }
}

3. 第一列为额外表头的多维表格​

{
  type: 'multiTable',
  encoding: {
    rows: ['产品'],
    columns: ['一季度', '二季度', '三季度', '四季度']
  }
}

4. 第一行为额外表头的多维表格​

{
  type: 'multiTable',
  encoding: {
    rows: ['销售额', '成本', '利润'],
    columns: ['季度']
  }
}

5. 树状表格​

展示层级结构数据：

{
  type: 'multiTable',
  encoding: {
    rows: ['部门', '人员'],
    columns: ['日期']
  },
  isTreeTable: true
}

6. 自定义事件处理​

支持表格交互事件的自定义处理：

{
  type: 'multiTable',
  encoding: {
    rows: ['产品'],
    columns: ['销售额']
  },
  customEvent: (event) => {
    if (event.type === 'cell:selected') {
      console.log('选中单元格:', event.data);
    } else if (event.type === 'page:changed') {
      console.log('页码变更:', event.page);
    }
  }
}

潜规则与注意事项​

  1. 表格类型自动识别：

    • 组件会根据rows和columns的设置自动识别表格类型。
    • 当data.length === 1 && !columns.length && rows.length时，渲染横向一维表格。
    • 当columns.length && !rows.length时，渲染纵向一维表格。
    • 当columns.length > 1 && rows.length === 1时，渲染第一列为额外表头的多维表格。
    • 当columns.length === 1 && rows.length > 1 && !isTreeTable时，渲染第一行为额外表头的多维表格。
    • 当isTreeTable === true时，渲染树状表格。

  2. 横向表格列数设置：

    • 横向一维表格的列数(columnsNum)必须为偶数，否则会抛出错误。
    • 实现代码中的限制：if (columnsNum % 2 !== 0) { throw new Error('Please input an event-numbered column'); }

  3. 数据排序机制：

    • 多维表格默认会对行数据进行升序排序，列数据进行降序排序。
    • 树状表格会根据日期字段进行降序排序。

  4. 表格尺寸调整：

    • 可通过maxHeight和width参数控制表格尺寸。
    • 默认值由tableConfig常量定义。

  5. 事件处理：

    • 支持四种事件类型：cell:selected、page:changed、tree:selected和cell:expand。
    • 通过customEvent参数可以自定义处理这些事件。

  6. 数据格式化：

    • 表格会使用api.hook.formatDataNumberValue自动格式化数字值。

实现原理​

多维表格组件内部使用了不同的表格子组件，主要包括：

  1. HorizontalTable：横向一维表格
  2. VerticalTable：纵向一维表格
  3. MultiTableX：第一列为额外表头的多维表格
  4. MultiTableY：第一行为额外表头的多维表格
  5. TreeTable：树状表格

根据配置参数和数据特性，组件会自动选择合适的表格子组件进行渲染。

类型兼容性问题​

使用本组件时，需要注意以下类型兼容性问题：

  1. 树状表格需要特定的数据结构，确保数据符合TreeTableData格式
  2. 日期类型字段在排序时需要转换为时间戳
  3. 事件处理函数接收的事件类型需要匹配Event联合类型定义

示例​

横向一维表格​

{
  type: 'multiTable',
  encoding: {
    rows: ['指标名称'],
    columns: []
  },
  columnsNum: 4
}

纵向一维表格​

{
  type: 'multiTable',
  encoding: {
    rows: [],
    columns: ['销售额']
  },
  pageSize: 20
}

多维表格​

{
  type: 'multiTable',
  encoding: {
    rows: ['产品'],
    columns: ['一季度', '二季度', '三季度', '四季度']
  },
  maxHeight: 600,
  width: 800
}

树状表格​

{
  type: 'multiTable',
  encoding: {
    rows: ['部门', '人员'],
    columns: ['日期']
  },
  isTreeTable: true,
  pageSize: 15
}

常见问题解决​

  1. 表格类型错误

    • 检查rows和columns的设置是否符合预期
    • 确认isTreeTable参数设置正确

  2. 横向表格列数错误

    • 确保columnsNum为偶数

  3. 树状表格数据问题

    • 检查数据结构是否符合TreeTableData格式
    • 确保包含正确的列和行字段

  4. 分页问题

    • 检查pageSize和currentPage设置是否合理
    • 确保customEvent正确处理page:changed事件
编辑此页
最后由 gongyuzhouchang 于 更新