useTable
useTable
is the root hook for React Table. To use it, pass it with an options object with at least a columns
and data
value, followed by any React Table compatible hooks you want to use.
useTable
是 React Table 的根钩子。要使用它,请将其与包含至少 columns
和 data
值的选项对象一起传递,然后再添加任何你想使用的 React Table 兼容钩子。
Table Options 表格选项
The following options are supported via the main options object passed to useTable(options)
通过传递给 useTable(options)
的主要选项对象支持以下选项
columns: Array<Column>
- Required 必需
- Must be memoized 必须进行记忆化处理
- The core columns configuration object for the entire table.
整个表格的核心列配置对象。 - Supports nested
columns
arrays via the column's columns
key, eg. [{ Header: 'My Group', columns: [...] }]
通过列的 columns
键(例如 [{ Header: 'My Group', columns: [...] }]
)支持嵌套的 columns
数组
data: Array<any>
- Required 必需
- Must be memoized 必须进行记忆化处理
- The data array that you want to display on the table.
你希望在表格中显示的数据数组。
initialState: Object
- Optional 可选
- The initial state object for the table.
表格的初始状态对象。 - Upon table initialization, this object is merged over the table's
defaultState
object (eg. {...defaultState, ...initialState}
) that React Table and its hooks use to register default state to produce the final initial state object passed to the React.useState
hook internally.
在表格初始化时,此对象会与表格的 defaultState
对象(例如 {...defaultState, ...initialState}
)合并,React Table 及其钩子用来注册默认状态,以生成传递给内部 React.useState
钩子的最终初始状态对象。
initialState.hiddenColumns: Array<ColumnId: String>
- Optional 可选
- The initial state object for hidden columns
隐藏列的初始状态对象 - If a column's ID is contained in this array, it will be hidden
如果某列的 ID 包含在此数组中,则该列将被隐藏 - To update
hiddenColumns
, pass a new array into setHiddenColumns
which is supplied by useTable
. Changing hiddenColumns
directly won't cause the table to add the hidden columns back.
要更新 hiddenColumns
,请将一个新数组传入 setHiddenColumns
,该数组由 useTable
提供。直接更改 hiddenColumns
不会导致表格重新添加隐藏的列。
autoResetHiddenColumns: Boolean
- Defaults to
true
默认为 true
- When
true
, the hiddenColumns
state will automatically reset if any of the following conditions are met:
当 true
时,如果满足以下任何条件, hiddenColumns
状态将自动重置:columns
is changed columns
被更改
- To disable, set to
false
要禁用,请设置为 false
stateReducer: Function(newState, action, prevState) => newState
- Optional 可选
- With every action that is dispatched to the table's internal
React.useReducer
instance, this reducer is called and is allowed to modify the final state object for updating.
每当有操作被派发到表格的内部 React.useReducer
实例时,这个 reducer 就会被调用,并有权修改最终的状态对象以进行更新。 - It is passed the
newState
, action
, and prevState
and is expected to either return the newState
or a modified version of the newState
它会接收 newState
、 action
和 prevState
,并预期返回 newState
或者对 newState
的修改版本。 - May also be used to "control" the state of the table, by overriding certain pieces of state regardless of the action.
也可以用来“控制”表格的状态,通过覆盖某些状态部分,无论操作内容如何。
useControlledState: HookFunction(state) => controlledState
- Optional 可选
- If you need to control part of the table state, this is the place to do it.
如果你需要控制表格状态的某一部分,这里是实现的地方。 - This function is run on every single render, just like a hook and allows you to alter the final state of the table if necessary.
这个函数在每次渲染时都会运行,就像一个钩子一样,允许你在必要时修改表格的最终状态。 - You can use hooks inside of this function, but most of the time, we just suggest using
React.useMemo
to memoize your state overrides.
你可以在这个函数内部使用钩子,但大多数情况下,我们建议使用 React.useMemo
来记忆你的状态覆盖。 - See the FAQ "How can I manually control the table state?" for a an example.
请参阅常见问题解答“我如何手动控制表格状态?”以获取示例。
defaultColumn: Object
- Optional 可选
- Defaults to
{}
默认为 {}
- The default column object for every column passed to React Table.
传递给 React Table 的每一列的默认列对象。 - Column-specific properties will override the properties in this object, eg.
{ ...defaultColumn, ...userColumn }
列特定的属性将覆盖此对象中的属性,例如 { ...defaultColumn, ...userColumn }
- This is particularly useful for adding global column properties. For instance, when using the
useFilters
plugin hook, add a default Filter
renderer for every column, eg.{ Filter: MyDefaultFilterComponent }
这对于添加全局列属性特别有用。例如,在使用 useFilters
插件钩子时,为每一列添加一个默认的 Filter
渲染器,例如 { Filter: MyDefaultFilterComponent }
getSubRows: Function(row, relativeIndex) => Rows[]
- Optional 可选
- Must be memoized 必须进行记忆化
- Defaults to
(row) => row.subRows || []
默认为 (row) => row.subRows || []
- Use this function to change how React Table detects subrows. You could even use this function to generate sub rows if you want.
使用此函数可以改变 React Table 检测子行的方式。你甚至可以使用此函数来生成子行。 - By default, it will attempt to return the
subRows
property on the row, or an empty array if that is not found.
默认情况下,它会尝试返回行的 subRows
属性,如果未找到则返回空数组。
getRowId: Function(row, relativeIndex, ?parent) => string
- Use this function to change how React Table detects unique rows and also how it constructs each row's underlying
id
property.
使用此函数可以改变 React Table 检测唯一行的方式,以及它构建每一行底层 id
属性的方式。 - Optional 可选
- Must be memoized 必须进行记忆化
- Defaults to
(row, relativeIndex, parent) => parent ? [parent.id, relativeIndex].join('.') : relativeIndex
默认为 (row, relativeIndex, parent) => parent ? [parent.id, relativeIndex].join('.') : relativeIndex
Column Options 列选项
The following options are supported on any column object you can pass to columns
.
以下选项支持在你传递给 columns
的任何列对象上使用。
accessor: String | Function(originalRow, rowIndex) => any
- Required 必需
- This string/function is used to build the data model for your column.
此字符串/函数用于构建列的数据模型。 - The data returned by an accessor should be primitive and sortable.
访问器返回的数据应为基本类型且可排序。 - If a string is passed, the column's value will be looked up on the original row via that key, eg. If your column's accessor is
firstName
then its value would be read from row['firstName']
. You can also specify deeply nested values with accessors like info.hobbies
or even address[0].street
如果传入的是字符串,则会在原始行中通过该键查找列的值,例如,如果你的列访问器是 firstName
,那么其值将从 row['firstName']
中读取。你也可以使用像 info.hobbies
或甚至 address[0].street
这样的深层嵌套值作为访问器。 - If a function is passed, the column's value will be looked up on the original row using this accessor function, eg. If your column's accessor is
row => row.firstName
, then its value would be determined by passing the row to this function and using the resulting value.
如果传入的是函数,则会使用该访问器函数在原始行中查找列的值,例如,如果你的列访问器是 row => row.firstName
,那么其值将通过将行传递给此函数并使用返回值来确定。 - Technically speaking, this field isn't required if you have a unique
id
for a column. This is used for things like expander or row selection columns. Warning: Only omit accessor
if you really know what you're doing.
从技术上讲,如果你为列提供了唯一的 id
,这个字段不是必需的。它用于像展开器或行选择列这样的场景。警告:只有在你非常清楚自己在做什么时,才可以省略 accessor
。
id: String
- Required if
accessor
is a function
如果 accessor
是一个函数,则为必填项 - This is the unique ID for the column. It is used by reference in things like sorting, grouping, filtering etc.
这是该列的唯一 ID。它在排序、分组、过滤等操作中被引用。 - If a string accessor is used, it defaults as the column ID, but can be overridden if necessary.
如果使用字符串访问器,默认将其作为列 ID,但如果需要,可以覆盖。
columns: Array<Column>
- Optional 可选
- A nested array of columns.
嵌套的列数组。 - If defined, the column will act as a header group. Columns can be recursively nested as much as needed.
如果定义,该列将作为标题组。列可以根据需要递归嵌套。
Header: String | Function | React.Component => JSX
- Optional 可选
- Defaults to
() => null
默认为 () => null
- Receives the table instance and column model as props
接收表格实例和列模型作为属性 - Must either be a string or return valid JSX
必须是字符串或返回有效的 JSX - If a function/component is passed, it will be used for formatting the header value, eg. You can use a
Header
function to dynamically format the header using any table or column state.
如果传入的是函数/组件,它将用于格式化表头值,例如,你可以使用 Header
函数,根据任何表格或列的状态动态格式化表头。
Footer: String | Function | React.Component => JSX
- Optional 可选
- Defaults to
() => null
默认为 () => null
- Receives the table instance and column model as props
接收表格实例和列模型作为属性 - Must either be a string or return valid JSX
必须是字符串或返回有效的 JSX - If a function/component is passed, it will be used for formatting the footer value, eg. You can use a
Footer
function to dynamically format the footer using any table or column state.
如果传入的是函数/组件,则会用其格式化页脚的值,例如,你可以使用一个 Footer
函数,结合任何表格或列的状态,动态格式化页脚。
Cell: Function | React.Component => JSX
- Optional 可选
- Defaults to
({ value }) => String(value)
默认为 ({ value }) => String(value)
- Receives the table instance and cell model as props
接收表格实例和单元格模型作为属性 - Must return valid JSX 必须返回有效的 JSX
- This function (or component) is primarily used for formatting the column value, eg. If your column accessor returns a date object, you can use a
Cell
function to format that date to a readable format.
此函数(或组件)主要用于格式化列值,例如:如果你的列访问器返回一个日期对象,你可以使用一个 Cell
函数将该日期格式化为可读的格式。
width: Int
- Optional 可选
- Defaults to
150
默认为 150
- Specifies the width for the column (when using non-table-element layouts)
指定列的宽度(在使用非表格元素布局时)
minWidth: Int
- Optional 可选
- Defaults to
0
默认为 0
- Specifies the minimum width for the column (when using non-table-element layouts)
指定列的最小宽度(在使用非表格元素布局时) - Specifically useful when using plugin hooks that allow the user to resize column widths
在使用允许用户调整列宽的插件钩子时特别有用
maxWidth: Int
- Optional 可选
- Defaults to
0
默认为 0
- Specifies the maximum width for the column (when using non-table-element layouts)
指定列的最大宽度(在使用非表格元素布局时) - Specifically useful when using plugin hooks that allow the user to resize column widths
在使用允许用户调整列宽的插件钩子时特别有用
Instance Properties 实例属性
The following properties are available on the table instance returned from useTable
以下属性在从 useTable
返回的表实例中可用
state: Object
- Memoized - This object reference will not change unless the internal table state is modified.
已缓存 - 只有在内部表状态被修改时,此对象引用才会发生变化 - This is the final state object of the table, which is the product of the
initialState
, internal table reducer and (optionally) a custom reducer
supplied by the user.
这是表格的最终状态对象,它是由 initialState
内部表格缩减器和(可选)由用户提供的自定义 reducer
共同生成的。
columns: Array<Column>
- A nested array of final column objects, similar in structure to the original columns configuration option.
一个嵌套的最终列对象数组,结构类似于原始列配置选项。 - See Column Properties for more information
有关更多信息,请参阅列属性。
allColumns: Array<Column>
- A flat array of all final column objects.
所有最终列对象的扁平数组。 - See Column Properties for more information
查看更多关于列属性的信息
visibleColumns: Array<Column>
- A flat array of all visible column objects derived from
allColumns
.
由 allColumns
派生的所有可见列对象的扁平数组。 - See Column Properties for more information
查看更多关于列属性的信息
headerGroups: Array<HeaderGroup>
- An array of normalized header groups, each containing a flattened array of final column objects for that row.
一个规范化的表头组数组,每个组包含该行最终列对象的扁平数组。 - Some of these headers may be materialized as placeholders
部分这些标题可能会作为占位符实现 - See HeaderGroup Properties for more information
查看更多 HeaderGroup 属性信息
footerGroups: Array<HeaderGroup>
- An array of normalized header groups, but in reverse order, each containing a flattened array of final column objects for that row.
一个已规范化的标题组数组,但顺序相反,每个包含该行最终列对象的扁平化数组。 - Some of these headers may be materialized as placeholders
部分这些标题可能会作为占位符实现 - See HeaderGroup Properties for more information
查看更多 HeaderGroup 属性以获取详细信息
headers: Array<Column>
- A nested array of final header objects, similar in structure to the original columns configuration option, but rebuilt for ordering
一个嵌套的最终表头对象数组,结构类似于原始列配置选项,但已重新构建以实现排序 - Each contains the headers that are displayed underneath it.
每个都包含其下显示的表头。 - Some of these headers may be materialized as placeholders
其中一些表头可能被作为占位符呈现 - See Column Properties for more information
查看更多列属性以获取详细信息
flatHeaders: Array<Column>
- A flat array of final header objects found in each header group.
在每个列头组中找到的一维最终列头对象数组。 - Some of these headers may be materialized as placeholders
其中一些列头可能作为占位符出现 - See Column Properties for more information
查看更多列属性以获取详细信息
rows: Array<Row>
- An array of materialized row objects from the original
data
array and columns
passed into the table options
来自原始 data
数组和传递到表格选项中的 columns
的已实例化行对象数组 - See Row Properties for more information
查看更多信息请参阅行属性
getTableProps: Function(?props)
- Required 必需
- This function is used to resolve any props needed for your table wrapper.
此函数用于解析表格包装器所需的任何属性。 - Custom props may be passed. NOTE: Custom props will override built-in table props, so be careful!
可以传递自定义属性。注意:自定义属性将覆盖内置的表格属性,请小心!
getTableBodyProps: Function(?props)
- Required 必需
- This function is used to resolve any props needed for your table body wrapper.
此函数用于解决表格主体包装器所需的任何属性。 - Custom props may be passed. NOTE: Custom props will override built-in table body props, so be careful!
可以传递自定义属性。注意:自定义属性将覆盖内置的表格主体属性,因此请小心!
prepareRow: Function(Row)
- Required 必需
- This function is responsible for lazily preparing a row for rendering. Any row that you intend to render in your table needs to be passed to this function before every render.
此函数负责惰性地准备行以供渲染。任何你打算在表格中渲染的行,都需要在每次渲染前传递给此函数。 - Why? Since table data could potentially be very large, it can become very expensive to compute all of the necessary state for every row to be rendered regardless if it actually is rendered or not (for example if you are paginating or virtualizing the rows, you may only have a few rows visible at any given moment). This function allows only the rows you intend to display to be computed and prepped with the correct state.
为什么?因为表格数据可能非常庞大,计算每一行所需的所有状态可能会变得非常昂贵,无论该行是否实际被渲染(例如,如果你在分页或虚拟化行,你可能在任何时刻只看到少数几行)。此函数只允许计算和准备你打算显示的行,并赋予其正确的状态。
flatRows: Array<Row>
- An array of all rows, including subRows which have been flattened into the order in which they were detected (depth first)
所有行的数组,包括已被扁平化为检测顺序(深度优先)的 subRows - This can be helpful in calculating total row counts that must include subRows
这在计算必须包括 subRows 的总行数时非常有用
totalColumnsWidth: Int
- This is the total width of all visible columns (only available when using non-table-element layouts)
这是所有可见列的总宽度(仅在使用非表元素布局时可用)
toggleHideColumn: Function(columnId: String, ?value: Boolean) => void
- This function can be used to toggle or set a column's hidden state
此函数可用于切换或设置列的隐藏状态 - Passing a
value
is optional. If passed, the hidden state will be set to that Boolean value.
传递一个 value
是可选的。如果传递了,隐藏状态将被设置为该布尔值。 - If a
value
is not passed, the visibility for this column will be toggled.
如果没有传递 value
,则该列的可见性将被切换。
setHiddenColumns: Function(Array<ColumnId: String> | Function(oldHiddenColumns) => Array<ColumnId: String>) => void
- This function can be used to set the
hiddenColumns
state for the entire table.
此函数可用于设置整个表格的 hiddenColumns
状态。 - If a value is passed,
hiddenColumns
will be set to that value
如果传递了一个值, hiddenColumns
将被设置为该值 - If a function is passed, it will received the previous
hiddenColumns
value and will be expected to return the new value.
如果传入的是一个函数,它将接收前一个 hiddenColumns
的值,并且需要返回新的值。
toggleHideAllColumns: Function(?value: Boolean) => void
- This function can be used to toggle or set the visibility for all columns to
true
or false
这个函数可以用来切换或设置所有列的可见性为 true
或 false
- If a value is not passed, the visibility for all columns will be toggled back and forth from
true
to false
如果没有传入值,所有列的可见性将会在 true
和 false
之间切换 - If
true
is passed, all columns will be hidden
如果传入 true
,所有列将被隐藏 - If a
false
is passed, all columns will be visible
如果传入 false
,所有列都将显示
getToggleHideAllColumnsProps: Function(userProps) => props
- This function can be used to retrieve all necessary props to be placed on an
<input type='checkbox'>
component that will control the visibility of all columns
此函数可用于获取所有必要的属性,这些属性应放置在控制所有列可见性的 <input type='checkbox'>
组件上
The following additional properties are available on every headerGroup
object returned by the table instance.
表格实例返回的每个 headerGroup
对象都具有以下附加属性。
headers: Array<Column>
- Required 必需
- The columns in this header group.
此标题组中的列。
getHeaderGroupProps: Function(?props)
- Required 必需
- This function is used to resolve any props needed for this header group's row.
此函数用于解决此标题组行所需的任何属性。 - You can use the
getHeaderGroupProps
hook to extend its functionality.
你可以使用 getHeaderGroupProps
钩子来扩展其功能。 - Custom props may be passed. NOTE: Custom props will override built-in table props, so be careful!
可以传递自定义属性。注意:自定义属性将覆盖内置的表格属性,请小心!
getFooterGroupProps: Function(?props)
- Required 必需
- This function is used to resolve any props needed for this header group's footer row.
此函数用于解析此标题组页脚行所需的任何属性。 - You can use the
getFooterGroupProps
hook to extend its functionality.
你可以使用 getFooterGroupProps
钩子来扩展其功能。 - Custom props may be passed. NOTE: Custom props will override built-in table props, so be careful!
可以传递自定义属性。注意:自定义属性将覆盖内置的表格属性,请小心!
Column Properties 列属性
The following properties are available on every Column
object returned by the table instance.
以下属性在表格实例返回的每个 Column
对象上都可用。
id: String
- The resolved column ID from either the column's
accessor
or the column's hard-coded id
property
从列的 accessor
或硬编码的 id
属性中解析出的列 ID
isVisible: Boolean
- Whether the column should be currently visible or not.
该列当前是否应显示。 - Columns that are not visible are still used for sorting, filtering, etc.
未显示的列仍然用于排序、过滤等操作。
render: Function(type: String | Function | Component, ?props)
- This function is used to render content with the added context of a column.
此函数用于在渲染内容时添加列的上下文。 - The entire table
instance
will be passed to the renderer with the addition of a column
property, containing a reference to the column
整个表格 instance
将传递给渲染器,并附加一个 column
属性,包含对该列的引用。 - If
type
is a string, will render using the column[type]
renderer. React Table ships with default Header
and Footer
renderers. Other renderers like Filter
and Aggregated
are available via plugin hooks.
如果 type
是字符串,则会使用 column[type]
渲染器进行渲染。React Table 内置了默认的 Header
和 Footer
渲染器。其他渲染器如 Filter
和 Aggregated
可以通过插件钩子获取。 - If a function or component is passed instead of a string, it will be be passed the table instance and column model as props and is expected to return any valid JSX.
如果传递的是函数或组件而非字符串,则会将表格实例和列模型作为 props 传递给它,并期望返回任何有效的 JSX。
totalLeft: Int
- This is the total width in pixels of all columns to the left of this column
这是该列左侧所有列的总宽度(以像素为单位) - Specifically useful when using plugin hooks that allow the user to resize column widths
在使用允许用户调整列宽的插件钩子时特别有用
totalWidth: Int
- This is the total width in pixels for this column (if it is a leaf-column) or or all of its sub-columns (if it is a column group)
这是该列(如果是叶子列)的总宽度,或其所有子列(如果是列组)的总宽度(以像素为单位) - Specifically useful when using plugin hooks that allow the user to resize column widths
在使用允许用户调整列宽的插件钩子时特别有用
getHeaderProps: Function(?props)
- Required 必需
- This function is used to resolve any props needed for this column's header cell.
此函数用于解析该列标题单元格所需的任何属性。 - You can use the
getHeaderProps
hook to extend its functionality.
你可以使用 getHeaderProps
钩子来扩展其功能。 - Custom props may be passed. NOTE: Custom props will override built-in table props, so be careful!
可以传递自定义属性。注意:自定义属性将覆盖内置的表格属性,请小心!
getFooterProps: Function(?props)
- Required 必需
- This function is used to resolve any props needed for this column's footer cell.
此函数用于解析该列页脚单元格所需的任何属性。 - You can use the
getFooterProps
hook to extend its functionality.
你可以使用 getFooterProps
钩子来扩展其功能。 - Custom props may be passed. NOTE: Custom props will override built-in table props, so be careful!
可以传递自定义属性。注意:自定义属性将覆盖内置的表格属性,请小心!
toggleHidden: Function(?hidden: Boolean) => void
- This function can be used to hide or show this column.
此函数可用于隐藏或显示此列。 - If no value is passed, the visibility of this column will be toggled.
如果未传递任何值,将切换此列的可见性。 - Optionally pass a value to set the visible.
可选地传递一个值以设置可见性。
getToggleHiddenProps: Function(userProps) => props
- This function can be used to retrieve all necessary props to be placed on an
<input type='checkbox'>
component that will control the visibility of this column.
此函数可用于获取所有必要的属性,这些属性应放置在一个 <input type='checkbox'>
组件上,以控制此列的可见性。
Row Properties 行属性
The following additional properties are available on every row
object returned by the table instance.
表实例返回的每个 row
对象都具有以下附加属性。
Cell Properties 单元格属性
The following additional properties are available on every Cell
object returned in an array of cells
on every row object.
以下额外属性在每个 cells
数组中的每个行对象返回的每个 Cell
对象上都可用。
column: Column
- The corresponding column object for this cell
该单元格对应的列对象
row: Row
- The corresponding row object for this cell
该单元格对应的行对象
value: any
- The resolved value for this cell.
该单元格的解析值 - By default, this value is displayed on the table via the default
Cell
renderer. To override the way a cell displays override the Cell property of the column object.
默认情况下,此值通过默认的 Cell
渲染器显示在表格上。要覆盖单元格的显示方式,可以覆盖列对象的 Cell 属性。
getCellProps: Function(?props)
- Required 必需
- This function is used to resolve any props needed for this cell.
此函数用于解析此单元格所需的任何属性。 - You can use the
getCellProps
hook to extend its functionality.
你可以使用 getCellProps
钩子来扩展其功能。 - Custom props may be passed. NOTE: Custom props will override built-in table props, so be careful!
可以传递自定义属性。注意:自定义属性将覆盖内置的表格属性,请小心!
render: Function(type: String | Function | Component, ?props)
- Required 必需
- This function is used to render content with the added context of a cell.
此函数用于在渲染内容时添加单元格的上下文信息。 - The entire table
instance
will be passed to the renderer with the addition of column
, row
and cell
properties, containing a reference to each respective item.
整个表格 instance
将传递给渲染器,同时附加 column
、 row
和 cell
属性,这些属性包含对各自项目的引用。 - If
type
is a string, will render using the column[type]
renderer. React Table ships with a default Cell
renderer. Other renderers like Aggregated
are available via hooks like useFilters
.
如果 type
是字符串,则会使用 column[type]
渲染器进行渲染。React Table 内置了一个默认的 Cell
渲染器。其他渲染器如 Aggregated
可以通过钩子 useFilters
获取。 - If a function or component is passed instead of a string, it will be be passed the table instance and cell model as props and is expected to return any valid JSX.
如果传入的是函数或组件而非字符串,则会将表格实例和单元格模型作为 props 传递给它,并期望返回任何有效的 JSX。
Example 示例
Was this page helpful? 这页内容对您有帮助吗?