!!!###!!!title=ListTable——VisActor/VTable 配置文档!!!###!!!!!!###!!!description=VisActor/VTable 配置文档。本章内容主要介绍 VTable 配置项及其用法以便快速生成所需表格。!!!###!!!

ListTable.container

HTMLElement

容器 DOM,需要具有宽。

可放到初始化参数中。

ListTable.records

Array

表格数据。 目前支持的数据格式,以人的信息为例:

[
  {"name": "张三","age": 20,"sex": "male","phone": "123456789","address": "北京市海淀区"},
  {"name": "李四","age": 30,"sex": "female","phone": "23456789","address": "北京市海淀区"},
  {"name": "王五","age": 40,"sex": "male","phone": "3456789","address": "北京市海淀区"}
]

ListTable.columns

*

表格列配置,每一列需要分别设置配置项,配置项根据cellType不同有略微差别,cellType可支持:'text' | 'link' | 'image' | 'video' | 'sparkline' | 'progressbar' | 'chart, 每种cellType的配置项具体如下:

ListTable.columns-text

string

指定该列或该行单元格类型为'text',cellType 缺省的话会被默认为'text'

ListTable.columns-link

string

指定该列或该行单元格类型为'link',cellType 缺省的话会被默认为'text'

ListTable.columns-image

string

指定该列或该行单元格类型为'image',cellType 缺省的话会被默认为'text'

ListTable.columns-video

string

指定该列或该行单元格类型为'video',cellType 缺省的话会被默认为'text'

ListTable.columns-progressbar

string

指定该列或该行单元格类型为'progressbar',cellType 缺省的话会被默认为'text'

ListTable.columns-sparkline

string

指定该列或该行单元格类型为'sparkline',cellType 缺省的话会被默认为'text'

ListTable.columns-chart

string

指定该列或该行单元格类型为'chart',cellType 缺省的话会被默认为'text'

ListTable.columns-checkbox

string

指定该列或该行单元格类型为'checkbox',cellType 缺省的话会被默认为'text'

ListTable.columns-radio

string

指定该列或该行单元格类型为'radio',cellType 缺省的话会被默认为'text'

ListTable.columns-function

string

指定该列或该行单元格类型为自定义函数。

ListTable.transpose

是否转置 默认 false

ListTable.showHeader = true

是否显示表头。

ListTable.pagination

IPagination

分页配置。

基本表格和 VTable 数据分析透视表支持分页,透视组合图不支持分页。

IPagination 的具体类型如下:

点击展开全部内容

ListTable.sortState(SortState | SortState[])

*

排序状态。SortState 定义如下:

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

ListTable.widthMode('standard' | 'adaptive' | 'autoWidth') = 'standard'

*

表格列宽度的计算模式,可以是 'standard'(标准模式)、'adaptive'(自适应容器宽度模式)或 'autoWidth'(自动宽度模式),默认为 'standard'。

  • 'standard':使用 width 属性指定的宽度作为列宽度。
  • 'adaptive':使用表格容器的宽度分配列宽度。
  • 'autoWidth':根据列头和 body 单元格中内容的宽度自动计算列宽度,忽略 width 属性的设置。

ListTable.heightMode('standard' | 'adaptive' | 'autoHeight') = 'standard'

*

表格行高的计算模式,可以是 'standard'(标准模式)、'adaptive'(自适应容器高度模式)或 'autoHeight'(自动行高模式),默认为 'standard'。

  • 'standard':采用 defaultRowHeightdefaultHeaderRowHeight 作为行高。
  • 'adaptive':使用容器的高度分配每行高度,基于每行内容计算后的高度比例来分配。
  • 'autoHeight':根据内容自动计算行高,计算依据 fontSize 和 lineHeight(文字行高),以及 padding。相关搭配设置项autoWrapText自动换行,可以根据换行后的多行文本内容来计算行高。

ListTable.widthAdaptiveMode('only-body' | 'all') = 'only-body'

*

adaptive 模式下宽度的适应策略,默认为 'only-body'。

  • 'only-body':只有 body 部分的列参与宽度适应计算,表头部分宽度不变。
  • 'all':所有列参与宽度适应计算。

ListTable.heightAdaptiveMode('only-body' | 'all') = 'only-body'

*

adaptive 模式下高度的适应策略,默认为 'only-body'。

  • 'only-body':只有 body 部分的行参与高度适应计算,表头部分高度不变。
  • 'all':所有列参与高度适应计算。

ListTable.columnWidthComputeMode('normal' | 'only-header' | 'only-body') = 'normal'

*

计算内容宽度时限定区域参与计算:

  • 'only-header':只计算表头内容。
  • 'only-body':只计算 body 单元格内容。
  • 'normal':正常计算,即计算表头和 body 单元格内容。

ListTable.autoWrapText

是否自动换行

ListTable.autoFillWidth

配置项 autoFillWidth,用于控制是否自动撑满容器宽度。区别于宽度模式widthModeadaptive的自适应容器的效果,autoFillWidth 控制的是只有当列数较少的时候,表格可以自动撑满容器宽度,但是当列数超过容器的时候根据真实情况来定列宽可出现滚动条。

ListTable.autoFillHeight

配置项 autoFillHeight,用于控制是否自动撑满容器高度。区别于高度模式heightModeadaptive的自适应容器的效果,autoFillHeight 控制的是只有当行数较少的时候,表格可以自动撑满容器高度,但是当行数超过容器的时候根据真实情况来定行高可出现滚动条。

ListTable.maxCharactersNumber = 200

单元格中可显示最大字符数 默认 200

ListTable.maxOperatableRecordCount

number

最大可操作的记录数 如 copy 操作可复制出最大数据条目数

ListTable.limitMaxAutoWidth = 450

boolean
number

计算列宽时 指定最大列宽 可设置 boolean 或者具体的值 默认为 450

ListTable.limitMinWidth = 10

boolean
number

最小列宽限制。如设置为 true 则拖拽改变列宽时限制列宽最小为 10px,设置为 false 则不进行限制。或者直接将其设置为某个数字值。默认为 10px。

ListTable.frozenColCount

冻结列数

ListTable.frozenRowCount

冻结行数(包含表头)

ListTable.rightFrozenColCount

右侧冻结列数

ListTable.bottomFrozenRowCount

底部冻结行数

ListTable.allowFrozenColCount

允许冻结列数,表示前多少列会出现冻结操作按钮(基本表格生效)

ListTable.showFrozenIcon = true

是否显示固定列图钉(基本表格生效)

ListTable.defaultRowHeight = 40

默认行高

ListTable.defaultHeaderRowHeight

Array
number

列表头默认行高 可以按逐行设置 如果没有就取 defaultRowHeight

ListTable.defaultColWidth = 80

列宽默认值

ListTable.defaultHeaderColWidth

Array
number

行表头默认列宽 可以按逐列设置 如果没有就取 defaultColWidth

ListTable.keyboardOptions

Object

快捷键功能设置,具体配置项:

点击展开全部内容

ListTable.eventOptions

Object

事件触发相关问题设置,具体配置项:

点击展开全部内容

ListTable.excelOptions

Object

对齐 excel 高级能力

点击展开全部内容

ListTable.columnResizeMode = 'all'

鼠标 hover 到单元格右边界可拖拽调整列宽。该操作可触发的范围:

  • 'all' 整列包括表头和 body 处的单元格均可调整列宽
  • 'none' 禁止调整
  • 'header' 只能在表头处单元格调整
  • 'body' 只能在 body 单元格调整

ListTable.rowResizeMode = 'all'

鼠标 hover 到单元格下边界可拖拽调整行高。该操作可触发的范围:

  • 'all' 整列包括表头和 body 处的单元格均可调整列宽
  • 'none' 禁止调整
  • 'header' 只能在表头处单元格调整
  • 'body' 只能在 body 单元格调整

ListTable.dragHeaderMode = 'none'

控制拖拽表头移动位置的开关。选中某个单元格后,鼠标拖拽该单元格可触发移动。 可换位单元格范围限定:

  • 'all' 所有表头均可换位
  • 'none' 不可换位
  • 'column' 只有换列表头可换位
  • 'row' 只有换行表头可换位

ListTable.hover

Object

hover 交互配置,具体配置项如下:

点击展开全部内容

ListTable.select

Object

选择单元格交互配置,具体配置项如下:

点击展开全部内容

ListTable.theme

Object

表格主题,其中内置主题名称有 DEFAULT, ARCO, BRIGHT, DARK, SIMPLIFY,具体配置方式可用内置类型或者直接使用字符串名称配置:

  • VTable.themes.DEFAULT
  • VTable.themes.ARCO;
  • VTable.themes.BRIGHT
  • VTable.themes.DARK
  • VTable.themes.SIMPLIFY

or

  • 'default'
  • 'arco'
  • 'bright'
  • 'dark'
  • 'simplify'

同时可以基于内置主题进行扩展,例如想基于 ARCO 主题改变字体:

VTable.themes.ARCO.extend({
  fontSize: '14px',
  fontFamily: 'PingFangSC'
})

或者直接自定义一套专属主题:

{
  defaultStyle:{
    borderLineWidth:0,
  },
  headerStyle:{
    frameStyle:{
      borderColor:'blue',
      borderLineWidth:[0,0,1,0]
    }
  },
  rowHeaderStyle:{
    frameStyle:{
      borderColor:'blue',
      borderLineWidth:[0,1,0,0]
    }
  },
  cornerHeaderStyle:{
    frameStyle:{
      borderColor:'blue',
      borderLineWidth:[0,1,1,0]
    }
  }
}
点击展开全部内容

ListTable.menu

Object

下拉菜单的相关配置。消失时机:显示后点击菜单区域外自动消失。具体配置项如下:

点击展开全部内容

ListTable.title

Object

表格标题配置。

点击展开全部内容

ListTable.emptyTip

Object

表格空数据提示。

可以直接配置boolean 或者 IEmptyTip类型对象, 默认为 false,不显示提示信息。

IEmptyTip类型定如如下:

点击展开全部内容

ListTable.tooltip

Object

tooltip 相关配置。具体配置如下:

点击展开全部内容

ListTable.legends

*

图例配置,目前提供了三种图例类型,分别是离散图例('discrete'),连续型颜色图例('color'),连续型尺寸图例('size')。

ListTable.legends-discrete

string

离散图例配置。可参考 VChart 中的配置图例 demo

ListTable.legends-color

string

连续型颜色图例配置。

TODO: 补充离散图例图示

ListTable.legends-size

string

连续型尺寸图例配置。

TODO: 补充离散图例图示

ListTable.axes

*

具体同 VChart 的轴配置,可支持线性轴离散轴时间轴

支持四个方向的轴配置,默认上轴在列表头的最后一行,下轴在表格底部的冻结一行,左轴在行表头的最后一列,上轴在表头最右侧固定的一列。如果在 indicator 的 spec 中同时也配置了某一方位的 axes,spec 中的优先级较高。

示例:

{
  axes: [
      {
        orient: 'bottom'
      },
      {
        orient: 'left',
        title: {
          visible: true
        }
      },
      {
        orient: 'right',
        visible: true,
        grid: {
          visible: false
        }
      }
    ]
}

ListTable.customRender

Function
Object

自定义渲染 函数形式或者对象形式。类型为:ICustomRenderFuc | ICustomRenderObj

示例链接 教程链接

其中 ICustomRenderFuc 定义为:

 type ICustomRenderFuc = (args: CustomRenderFunctionArg) => ICustomRenderObj;

回调函数参数CustomRenderFunctionArg的类型声明为:

interface CustomRenderFunctionArg {
  row: number;
  col: number;
  table: TableAPI;
  /**format之后的值 */
  value: string|number;
  /**原始值 */
  dataValue: string|number;
  rect?: RectProps;
}

ICustomRenderObj 的定义如下:

export type ICustomRenderObj = {
  /** 配置出来的类型集合 */
  elements: ICustomRenderElements;
  /** 期望单元格的高度 */
  expectedHeight: number;
  /** 期望单元格的宽度 */
  expectedWidth: number;
  /**
   * 是否还需要默认渲染内容 只有配置true才绘制 默认 不绘制
   */
  renderDefault?: boolean;
};

详细配置说明如下:

点击展开全部内容

ListTable.overscrollBehavior = 'auto'

表格滚动行为,可设置:'auto'|'none',默认值为'auto'。

'auto': 表格滚动到顶部或者底部时,触发浏览器默认行为;
'none': 表格滚动到顶部或者底部时, 触发浏览器默认行为;

ListTable.customMergeCell

Function

自定义单元格合并规则,传入的行列号在目标区域内时,返回合并规则:

  • text: 合并单元格内的文字
  • range: 合并的范围
  • style: 合并单元格的样式 示例:
  customMergeCell: (col, row, table) => {
    if (col > 0 && col < 8 && row > 7 && row < 11) {
      return {
        text: 'merge text',
        range: {
          start: {
            col: 1,
            row: 8
          },
          end: {
            col: 7,
            row: 10
          }
        },
        style: {
          bgColor: '#ccc'
        }
      };
    }
  }

ListTable.customCellStyle

Array
{
  customCellStyle: {id: string;style: ColumnStyleOption}[]
}

自定义单元格样式

  • id: 自定义样式的唯一 id
  • style: 自定义单元格样式,与column中的style配置相同,最终呈现效果是单元格原有样式与自定义样式融合

ListTable.customCellStyleArrangement

Array
{
  customCellStyleArrangement:
  {
    cellPosition: {
      row?: number;
      col?: number;
      range?: {
        start: {row: number; col: number};
        end: {row: number; col: number}
      }
  };
  customStyleId: string}[]
}

自定义单元格样式分配

  • cellPosition: 单元格位置信息,支持配置单个单元格与单元格区域
    • 单个单元格:{ row: number, column: number }
    • 单元格区域:{ range: { start: { row: number, column: number }, end: { row: number, column: number} } }
  • customStyleId: 自定义样式 id,与注册自定义样式时定义的 id 相同

ListTable.rowSeriesNumber

IRowSeriesNumber

配置行序号。

点击展开全部内容

ListTable.editor

string
Object
Function

全局配置单元格编辑器

editor?: string | IEditor | ((args: BaseCellInfo & { table: BaseTableAPI }) => string | IEditor);

其中 IEditor 是@visactor/vtable-editors 中定义的编辑器接口,具体可以参看源码:https://github.com/VisActor/VTable/blob/main/packages/vtable-editors/src/types.ts。

ListTable.headerEditor

string
Object
Function

全局配置表头显示标题 title 的编辑器

headerEditor?: string | IEditor | ((args: BaseCellInfo & { table: BaseTableAPI }) => string | IEditor);

ListTable.editCellTrigger('doubleclick' | 'click' | 'api') = 'doubleclick'

*

进入编辑状态的触发时机。


/\*_ 编辑触发时机:双击事件 | 单击事件 | api 手动开启编辑。默认为双击'doubleclick' _/
editCellTrigger?: 'doubleclick' | 'click' | 'api';

ListTable.enableLineBreak

是否开启换行符解析,开启后,单元格内容中包含换行符时,会自动解析换行。

ListTable.clearDOM = true

是否清空容器 DOM。

ListTable.animationAppear

boolean
Object

表格的入场动画配置。

animationAppear?: boolean | {
  type?: 'all' | 'one-by-one';
  direction?: 'row' | 'column';
  duration?: number;
  delay?: number;
};

可以配置 true 开启默认动画,也可以配置动画的参数:

  • type 入场动画的类型,目前支持 allone-by-one两种,默认为 one-by-one
  • direction 入场动画的方向,目前支持 rowcolumn两种,默认为 row
  • duration 单个动画的时长,单位为毫秒,one-by-one 时,为一次动画的时长,默认为 500
  • delay 动画的延迟,单位为毫秒;one-by-one 时为两次动画直接的时间差,all 时为所有动画的延迟,默认为 0

ListTable.hierarchyIndent

number

展示为树形结构时,每层内容缩进值。

ListTable.hierarchyExpandLevel

number

展示为树形结构时,默认展开层数。默认为 1 只显示根节点,配置为Infinity则全部展开。

ListTable.hierarchyTextStartAlignment

同层级的结点是否按文字对齐 如没有收起展开图标的节点和有图标的节点文字对齐 默认 false

ListTable.frozenColDragHeaderMode = 'fixedFrozenCount'

拖拽表头移动位置 针对冻结部分的规则 默认为 fixedFrozenCount

  • "disabled"(禁止调整冻结列位置):不允许其他列的表头移入冻结列,也不允许冻结列移出,冻结列保持不变。
  • "adjustFrozenCount"(根据交互结果调整冻结数量):允许其他列的表头移入冻结列,及冻结列移出,并根据拖拽的动作调整冻结列的数量。当其他列的表头被拖拽进入冻结列位置时,冻结列数量增加;当其他列的表头被拖拽移出冻结列位置时,冻结列数量减少。
  • "fixedFrozenCount"(可调整冻结列,并维持冻结数量不变):允许自由拖拽其他列的表头移入或移出冻结列位置,同时保持冻结列的数量不变。

ListTable.aggregation

Aggregation
CustomAggregation
Array
Function

数据聚合汇总分析配置,全局配置每一列都将有聚合逻辑,也可以在列(columns)定义中配置,列中配置的优先级更高。

aggregation?:
    | Aggregation
    | CustomAggregation
    | (Aggregation | CustomAggregation)[]
    | ((args: {
        col: number;
        field: string;
      }) => Aggregation | CustomAggregation | (Aggregation | CustomAggregation)[] | null);

其中:

type Aggregation = {
  aggregationType: AggregationType;
  showOnTop?: boolean;
  formatFun?: (value: number, col: number, row: number, table: BaseTableAPI) => string | number;
};

type CustomAggregation = {
  aggregationType: AggregationType.CUSTOM;
  aggregationFun: (values: any[], records: any[]) => any;
  showOnTop?: boolean;
  formatFun?: (value: number, col: number, row: number, table: BaseTableAPI) => string | number;
};