Lzh on GitHub

这份快速指南将讨论如何在 TanStack Table 中检索和与 行对象 (row objects) 进行交互。

从何处获取行

有多个表格实例 API 可用于从表格实例中检索行。

table.getRow

如果你需要通过行的 id 访问特定的行，可以使用 table.getRow 表格实例 API。

const row = table.getRow(rowId)

行模型 (Row Models)

表格实例会生成行对象并将它们存储在有用的数组中，这些数组被称为“行模型 (Row Models)”。这在 行模型指南 中有更详细的讨论，但这里是一些你可能访问行模型的最常见方式。

渲染行 (Render Rows)

<tbody>
  {table.getRowModel().rows.map(row => (
    <tr key={row.id}>
     {/* ... */}
    </tr>
  ))}
</tbody>

获取选定的行 (Get Selected Rows)

const selectedRows = table.getSelectedRowModel().rows

行对象 (Row Objects)

每个行对象都包含行数据和许多 API，用于与表格状态交互或根据表格状态从行中提取单元格。

行 ID (Row IDs)

每个行对象都有一个 id 属性，使其在表格实例中独一无二。默认情况下，row.id 与行模型中创建的 row.index 相同。然而，使用行数据中的唯一标识符来覆盖每行的 id 可能很有用。你可以使用 getRowId 表格选项来完成此操作。

const table = useReactTable({
  columns,
  data,
  getRowId: originalRow => originalRow.uuid, // 使用原始行数据中的 uuid 覆盖 row.id
})

注意： 在分组和展开等某些功能中，row.id 将附加额外的字符串。

访问行值 (Access Row Values)

访问行数据值的推荐方法是使用 row.getValue 或 row.renderValue API。使用这些 API 中的任何一个都会缓存访问器函数的结果并保持高效渲染。两者之间的唯一区别是，如果值为 undefined，row.renderValue 将返回该值或 renderFallbackValue，而 row.getValue 将返回该值或 undefined。

// 访问任何列的数据
const firstName = row.getValue('firstName') // 从 firstName 列读取行值
const renderedLastName = row.renderValue('lastName') // 渲染 lastName 列的值

注意： cell.getValue 和 cell.renderValue 分别是 row.getValue 和 row.renderValue API 的快捷方式。

访问原始行数据 (Access Original Row Data)

对于每个行对象，你可以通过 row.original 属性访问传递给表格实例的原始对应 data。row.original 中的数据都不会被列定义中的访问器修改，因此如果你在访问器中进行了任何数据转换，这些转换将不会反映在 row.original 对象中。

// 访问原始行中的任何数据
const firstName = row.original.firstName // { firstName: 'John', lastName: 'Doe' }

子行 (Sub Rows)

如果你正在使用分组或展开功能，你的行可能包含子行或父行引用。这在 展开指南 中有更详细的讨论，但这里是使用子行的一些有用属性和方法的快速概述。

  • row.subRows: 行的子行数组。
  • row.depth: 行的深度（如果嵌套或分组），相对于根行数组。根级别行为 0，子行为 1，孙子行为 2，依此类推。
  • row.parentId: 行的父行的唯一 ID（包含此行的父行在其 subRows 数组中）。
  • row.getParentRow: 返回行的父行（如果存在）。

更多行 API (More Row APIs)

根据你用于表格的功能，还有数十个用于与行交互的有用 API。有关更多信息，请参阅每个功能的相应 API 文档或指南。