列大小调整指南

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

列宽度

默认情况下，列将获得以下测量选项

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 样式。

作为一个无头实用程序，表格列大小调整的逻辑实际上只是一组状态，您可以根据需要应用到自己的布局中（我们上面的示例实现了两种风格的逻辑）。您可以通过多种方式应用这些宽度测量：

语义 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 的列大小调整渲染，但您可能需要进行一些额外的记忆化或其他性能优化才能实现这一点。

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

如果您想将列大小调整模式更改为 "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 😉），您可能会发现，如果不对渲染逻辑添加适当的记忆化，您的用户在调整列大小时可能会遇到性能下降。

我们创建了一个高性能列大小调整示例，演示了如何在一个可能否则渲染缓慢的复杂表格中实现 60 fps 的列大小调整渲染。建议您仅查看该示例以了解如何实现，但以下是一些需要注意的基本事项：

不要在每个标题和每个数据单元格上都使用 column.getSize()。而是，一次性计算所有列的宽度，进行记忆化！
在调整大小过程中，记忆化您的表格主体。
使用 CSS 变量将列宽度传达给您的表格单元格。

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

如果您不使用 React，而是使用 Svelte、Vue 或 Solid 适配器，您可能不需要过多担心这个问题，但类似的原则也适用。

列大小调整指南

示例

API

列大小调整指南

列宽度

列大小调整

启用列大小调整

列大小调整模式

列大小调整方向

将列大小调整 API 连接到 UI

列大小 API

列大小调整 API

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

高级列大小调整性能

订阅 Bytes

订阅 Bytes