列固定指南

想要直接跳到实现部分吗？请查看以下示例：

• column-pinning
• sticky-column-pinning

• Svelte column-pinning
• Vue column-pinning

列固定 API

TanStack Table 提供了有助于在表格 UI 中实现列固定功能的状态和 API。您可以通过多种方式实现列固定。您可以将固定列拆分为单独的表格，也可以将所有列保留在同一表格中，但使用固定状态正确排序列，并使用粘性 CSS 将列固定到左侧或右侧。

有 3 个表格功能可以重新排序列，它们按以下顺序发生：

1. 列固定 - 如果固定，列将分为左侧、中间（未固定）和右侧固定列。
2. 手动列排序 - 应用手动指定的列顺序。
3. 分组 - 如果启用了分组，分组状态处于活动状态，并且 tableOptions.groupedColumnMode 设置为 'reorder' | 'remove'，则分组的列将重新排序到列流的开头。

更改固定列顺序的唯一方法是在 columnPinning.left 和 columnPinning.right 状态本身中进行。columnOrder 状态将仅影响未固定（“中间”）列的顺序。

管理 columnPinning 状态是可选的，通常不需要，除非您要添加持久状态功能。TanStack Table 已经为您跟踪列固定状态。如果需要，可以像管理任何其他表格状态一样管理 columnPinning 状态。

const [columnPinning, setColumnPinning] = useState<ColumnPinningState>({
  left: [],
  right: [],
});
//...
const table = useReactTable({
  //...
  state: {
    columnPinning,
    //...
  }
  onColumnPinningChange: setColumnPinning,
  //...
});

const [columnPinning, setColumnPinning] = useState<ColumnPinningState>({
  left: [],
  right: [],
});
//...
const table = useReactTable({
  //...
  state: {
    columnPinning,
    //...
  }
  onColumnPinningChange: setColumnPinning,
  //...
});

一个非常常见的用例是默认固定某些列。您可以通过使用固定列 ID 初始化 columnPinning 状态，或使用 initialState 表格选项来实现此目的。

const table = useReactTable({
  //...
  initialState: {
    columnPinning: {
      left: ['expand-column'],
      right: ['actions-column'],
    },
    //...
  }
  //...
});

const table = useReactTable({
  //...
  initialState: {
    columnPinning: {
      left: ['expand-column'],
      right: ['actions-column'],
    },
    //...
  }
  //...
});

注意：其中一些 API 是 v8.12.0 中的新增功能

有许多有用的列 API 方法可帮助您实现列固定功能：

• column.getCanPin：用于确定列是否可以固定。
• column.pin：用于将列固定到左侧或右侧。或用于取消固定列。
• column.getIsPinned：用于确定列固定的位置。
• column.getStart：用于为固定列提供正确的 left CSS 值。
• column.getAfter：用于为固定列提供正确的 right CSS 值。
• column.getIsLastColumn：用于确定列是否是其固定组中的最后一列。对于添加框阴影很有用。
• column.getIsFirstColumn：用于确定列是否是其固定组中的第一列。对于添加框阴影很有用。

如果您只是使用粘性 CSS 来固定列，那么在大多数情况下，您只需像平常一样使用 table.getHeaderGroups 和 row.getVisibleCells 方法渲染表格即可。

但是，如果您要将固定列拆分为单独的表格，则可以使用 table.getLeftHeaderGroups、table.getCenterHeaderGroups、table.getRightHeaderGroups、row.getLeftVisibleCells、row.getCenterVisibleCells 和 row.getRightVisibleCells 方法仅渲染与当前表格相关的列。