列大小调整指南

列大小调整功能允许您选择性地指定每列的宽度，包括最小和最大宽度。它还允许您和您的用户随意动态更改所有列的宽度，例如，通过拖动列标题。

列宽

默认情况下，列具有以下测量选项

tsx

export const defaultColumnSizing = {
  size: 150,
  minSize: 20,
  maxSize: Number.MAX_SAFE_INTEGER,
}

export const defaultColumnSizing = {
  size: 150,
  minSize: 20,
  maxSize: Number.MAX_SAFE_INTEGER,
}

这些默认值可以被 tableOptions.defaultColumn 和各个列定义覆盖，按此顺序。

tsx

const columns = [
  {
    accessorKey: 'col1',
    size: 270, //set column size for this column
  },
  //...
]

const table = useReactTable({
  //override default column sizing
  defaultColumn: {
    size: 200, //starting column size
    minSize: 50, //enforced during column resizing
    maxSize: 500, //enforced during column resizing
  },
})

const columns = [
  {
    accessorKey: 'col1',
    size: 270, //set column size for this column
  },
  //...
]

const table = useReactTable({
  //override default column sizing
  defaultColumn: {
    size: 200, //starting column size
    minSize: 50, //enforced during column resizing
    maxSize: 500, //enforced during column resizing
  },
})

列的“大小”作为数字存储在表格状态中，通常被解释为像素单位值，但您可以将这些列大小调整值连接到您的 CSS 样式，以您认为合适的方式。

作为一个无头实用程序，列大小调整的表格逻辑实际上只是状态的集合，您可以将这些状态应用于您自己的布局，以您认为合适的方式（上面的示例实现了这种逻辑的 2 种样式）。您可以通过多种方式应用这些宽度测量

语义化的 table 元素或以表格 CSS 模式显示的任何元素
div/span 元素或以非表格 CSS 模式显示的任何元素
- 具有严格宽度的块级元素
- 具有严格宽度的绝对定位元素
- 具有宽松宽度的 Flexbox 定位元素
- 具有宽松宽度的 Grid 定位元素
实际上，任何可以将单元格宽度插入表格结构的布局机制。

每种方法都有其自身的权衡和限制，这些通常是 UI/组件库或设计系统所持有的观点，幸运的是，这与您无关 😉。

列调整大小

TanStack Table 提供了内置的列调整大小状态和 API，使您能够轻松地在表格 UI 中实现列调整大小，并提供多种 UX 和性能选项。

启用列调整大小

默认情况下，column.getCanResize() API 对于所有列默认返回 true，但您可以使用 enableColumnResizing 表格选项禁用所有列的列调整大小，或者使用 enableResizing 列选项在每列的基础上禁用列调整大小。

tsx

const columns = [
  {
    accessorKey: 'id',
    enableResizing: false, //disable resizing for just this column
    size: 200, //starting column size
  },
  //...
]

const columns = [
  {
    accessorKey: 'id',
    enableResizing: false, //disable resizing for just this column
    size: 200, //starting column size
  },
  //...
]

列调整大小模式

默认情况下，列调整大小模式设置为 "onEnd"。这意味着 column.getSize() API 在用户完成调整大小（拖动）列之前不会返回新的列大小。通常，在用户调整列大小时，会显示一个小的 UI 指示器。

在 React TanStack Table 适配器中，实现 60 fps 列调整大小渲染可能很困难，具体取决于您的表格或网页的复杂性，"onEnd" 列调整大小模式可能是一个很好的默认选项，以避免在用户调整列大小时出现卡顿或延迟。但这并不是说您在使用 TanStack React Table 时无法实现 60 fps 列调整大小渲染，但您可能需要进行一些额外的 memoization 或其他性能优化才能实现此目的。

高级列调整大小性能技巧将在下方讨论。

如果您想将列调整大小模式更改为 "onChange" 以进行即时列调整大小渲染，您可以使用 columnResizeMode 表格选项来完成。

tsx

const table = useReactTable({
  //...
  columnResizeMode: 'onChange', //change column resize mode to "onChange"
})

const table = useReactTable({
  //...
  columnResizeMode: 'onChange', //change column resize mode to "onChange"
})

列调整大小方向

默认情况下，TanStack Table 假定表格标记是以从左到右的方向布局的。对于从右到左的布局，您可能需要将列调整大小方向更改为 "rtl"。

tsx

const table = useReactTable({
  //...
  columnResizeDirection: 'rtl', //change column resize direction to "rtl" for certain locales
})

const table = useReactTable({
  //...
  columnResizeDirection: 'rtl', //change column resize direction to "rtl" for certain locales
})

将列调整大小 API 连接到 UI

有一些非常方便的 API，您可以使用它们将列调整大小拖动交互连接到您的 UI。

列大小 API

要将列的大小应用于列标题单元格、数据单元格或页脚单元格，您可以使用以下 API

header.getSize()
column.getSize()
cell.column.getSize()

header.getSize()
column.getSize()
cell.column.getSize()

如何将这些大小样式应用于您的标记取决于您，但通常使用 CSS 变量或内联样式来应用列大小。

tsx

<th
  key={header.id}
  colSpan={header.colSpan}
  style={{ width: `${header.getSize()}px` }}
>

<th
  key={header.id}
  colSpan={header.colSpan}
  style={{ width: `${header.getSize()}px` }}
>

但是，正如在高级列调整大小性能部分中讨论的那样，您可能需要考虑使用 CSS 变量将列大小应用于您的标记。

列调整大小 API

TanStack Table 提供了一个预构建的事件处理程序，使您的拖动交互易于实现。这些事件处理程序只是调用其他内部 API 以更新列大小调整状态并重新渲染表格的便捷函数。使用 header.getResizeHandler() 连接到您的列调整大小拖动交互，适用于鼠标和触摸事件。

tsx

<ColumnResizeHandle
  onMouseDown={header.getResizeHandler()} //for desktop
  onTouchStart={header.getResizeHandler()} //for mobile
/>

<ColumnResizeHandle
  onMouseDown={header.getResizeHandler()} //for desktop
  onTouchStart={header.getResizeHandler()} //for mobile
/>

带有 ColumnSizingInfoState 的列调整大小指示器

TanStack Table 跟踪一个名为 columnSizingInfo 的状态对象，您可以使用它来渲染列调整大小指示器 UI。

jsx

<ColumnResizeIndicator
  style={{
    transform: header.column.getIsResizing()
      ? `translateX(${table.getState().columnSizingInfo.deltaOffset}px)`
      : '',
  }}
/>

<ColumnResizeIndicator
  style={{
    transform: header.column.getIsResizing()
      ? `translateX(${table.getState().columnSizingInfo.deltaOffset}px)`
      : '',
  }}
/>

高级列调整大小性能

如果您正在创建大型或复杂的表格（并且使用 React 😉），您可能会发现，如果您没有向渲染逻辑添加适当的 memoization，您的用户在调整列大小时可能会遇到性能下降的情况。

我们创建了一个高性能列调整大小示例，演示了如何在复杂的表格中实现 60 fps 列调整大小渲染，否则可能会导致渲染缓慢。建议您直接查看该示例，了解它是如何完成的，但以下是需要记住的基本事项

不要在每个表头和每个数据单元格上使用 column.getSize()。而是预先计算所有列宽，并进行 memoization！
在调整大小正在进行时，memoize 您的表格主体。
使用 CSS 变量将列宽传递到您的表格单元格。

如果您遵循这些步骤，您应该会在调整列大小时看到明显的性能提升。

如果您没有使用 React，而是使用了 Svelte、Vue 或 Solid 适配器，您可能不必担心这么多，但类似的原则也适用。

列大小调整指南

示例

API