React Bootstrap logoReact Bootstrap

Table

基础布局

基于 Bootstrap 5 的表格组件,提供表格容器与表头/表体/表尾、行、单元格、标题等结构组件,支持情景颜色、条纹行/列、悬停与激活状态、边框、紧凑尺寸、分组分隔线、垂直对齐、嵌套、标题置顶与响应式滚动容器;并通过选择单元格、行内编辑单元格、加载/空状态行以及 useTable、useTableSelection、useTableEditing 钩子完整支持多选、增删改查等交互场景,配合展开开关单元格、详情行与 useTableExpansion 钩子可实现展开行、主从视图、详情弹窗、详情抽屉与表格/卡片视图切换等多种查看详情方式;此外通过 useTableSearch、useTableFilter、useTableSorting、useTablePagination、useTableColumns 钩子与 exportTableCsv 导出能力,完整覆盖搜索、筛选、排序、分页、列偏好与列宽选项设置、批量操作与数据导出等数据场景

Component Demo

Basic usage and examples of the Table component

基础示例

#姓氏名字用户名
1@zhangwei
2@lilei
3@wangfang

情景颜色

主要样式
次要样式
成功样式
危险样式
警告样式
信息样式
浅色样式
深色样式

条纹行

#姓氏名字用户名
1@zhangwei
2@lilei
3@wangfang
4@liuqiang
5@chenjing

条纹列

#姓氏名字用户名
1@zhangwei
2@lilei
3@wangfang
4@liuqiang
5@chenjing

悬停行

#姓氏名字用户名
1@zhangwei
2@lilei
3@wangfang
4@liuqiang
5@chenjing

激活状态

1激活的行整行高亮
2普通行默认样式
1激活的单元格单个单元格高亮
2普通单元格默认样式

边框表格

#姓氏名字用户名
1@zhangwei
2@lilei
3@wangfang

无边框表格

#姓氏名字用户名
1@zhangwei
2@lilei
3@wangfang

紧凑表格

#姓氏名字用户名
1@zhangwei
2@lilei
3@wangfang

分组分隔线

#姓氏名字用户名
1@zhangwei
2@lilei
3@wangfang
4@liuqiang

垂直对齐

#对齐方式内容
1继承表格的垂直对齐这里是一段很长的内容,用于把整行撑高,
以便观察单元格的垂直对齐效果,
表格设置了对齐方式为 middle。
顶部对齐垂直居中底部对齐

嵌套表格

#姓氏名字用户名
1嵌套表格:
标签
角色管理员
状态在线

表格结构

用户列表
#姓氏名字用户名
1@zhangwei
2@lilei
3@wangfang
总计3 人

标题置顶

用户列表
#姓氏名字用户名
1@zhangwei
2@lilei
3@wangfang

响应式表格

#姓氏名字用户名
1@zhangwei
2@lilei
3@wangfang
#姓氏名字用户名
1@zhangwei
2@lilei
3@wangfang
#姓氏名字用户名
1@zhangwei
2@lilei
3@wangfang

多选

已选 0
#姓氏名字用户名
1@zhangwei
2@lilei
3@wangfang

行内编辑

#姓氏名字用户名状态备注操作
1@zhangwei在线核心成员
2@lilei离线新加入
3@wangfang忙碌管理员

新增行

#姓氏名字用户名
1@zhangwei
2@lilei
3@wangfang

删除行

#姓氏名字用户名操作
1@zhangwei
2@lilei
3@wangfang

完整 CRUD 示例

#姓氏名字用户名操作
1@zhangwei
2@lilei
3@wangfang

加载状态

#姓氏名字用户名
加载中…

空状态

#姓氏名字用户名
暂无数据,

展开行详情

订单号客户金额状态
202501120001张伟¥129已发货
202501120002李磊¥59.9待发货
202501130003王芳¥358.5已完成

主从视图

#姓氏名字用户名
1@zhangwei
2@lilei
3@wangfang
用户详情
编号
1
姓名
用户名
@zhangwei
状态
在线
备注
核心成员

详情弹窗

#姓氏名字用户名操作
1@zhangwei
2@lilei
3@wangfang

详情抽屉

#姓氏名字用户名操作
1@zhangwei
2@lilei
3@wangfang

视图切换

#姓氏名字用户名
1@zhangwei
2@lilei
3@wangfang

搜索

3 条记录

#姓氏名字用户名
1@zhangwei
2@lilei
3@wangfang

筛选

3 条记录

#姓氏名字状态
1在线
2离线
3忙碌

排序

客户状态
202501120001张伟¥129已发货
202501120002李磊¥59.9待发货
202501130003王芳¥358.5已完成

分页

#姓氏名字用户名
1用户姓1@user1
2用户姓2@user2
3用户姓3@user3
4用户姓4@user4
5用户姓5@user5
每页12 条,第 1 / 3

列偏好

#姓氏名字用户名状态
1@zhangwei在线
2@lilei离线
3@wangfang忙碌

当前显示 5 / 6 列,偏好已保存到 localStorage

自定义列宽

#
姓氏
名字
用户名
备注
1@zhangwei核心成员
2@lilei新加入
3@wangfang管理员

通过表头下拉选择每列宽度,设置已保存到 localStorage

批量操作

已选 0
#姓氏名字状态
1用户姓1在线
2用户姓2离线
3用户姓3忙碌
4用户姓4在线
5用户姓5离线
6用户姓6忙碌
7用户姓7在线
8用户姓8离线
9用户姓9忙碌
10用户姓10在线
11用户姓11离线
12用户姓12忙碌

API Documentation

Complete API reference for the Table component

Props

Table

属性名类型默认值描述
alignTableAlign-表格整体的垂直对齐方式,渲染为 `align-top`、`align-middle` 或 `align-bottom` 类
asElementType'table'渲染的元素标签
borderedbooleanfalse为表格与所有单元格添加边框,渲染为 `table-bordered` 类
borderlessbooleanfalse去除表格与单元格的边框,渲染为 `table-borderless` 类
hoverbooleanfalse悬停时高亮行,渲染为 `table-hover` 类
responsiveTableBreakpoint | booleanfalse响应式横向滚动容器,`true` 渲染 `table-responsive`,或传入断点 `sm`、`md`、`lg`、`xl`、`xxl` 从该断点起滚动
sizeTableSize-紧凑尺寸,渲染为 `table-sm` 类
stripedTableStripedfalse条纹样式,`true` 渲染 `table-striped`,或传 `columns` 渲染 `table-striped-columns`
variantTableVariant-情景颜色变体,渲染为 `table-*` 类

TableCaption

属性名类型默认值描述
asElementType'caption'渲染的元素标签
captionTopbooleanfalse将标题置于表格顶部,渲染为 `caption-top` 类

TableHead

属性名类型默认值描述
asElementType'thead'渲染的元素标签
variantTableVariant-情景颜色变体,渲染为 `table-*` 类

TableBody

属性名类型默认值描述
asElementType'tbody'渲染的元素标签
variantTableVariant-情景颜色变体,渲染为 `table-*` 类

TableFooter

属性名类型默认值描述
asElementType'tfoot'渲染的元素标签
variantTableVariant-情景颜色变体,渲染为 `table-*` 类

TableRow

属性名类型默认值描述
activebooleanfalse激活状态,渲染为 `table-active` 类
asElementType'tr'渲染的元素标签
variantTableVariant-情景颜色变体,渲染为 `table-*` 类

TableCell

属性名类型默认值描述
activebooleanfalse激活状态,渲染为 `table-active` 类
alignTableAlign-单元格垂直对齐方式,渲染为 `align-top`、`align-middle` 或 `align-bottom` 类
asElementType'td'渲染的元素标签,默认 `td`,可传 `th` 渲染表头单元格
scopeTableCellScope-表头单元格的关联范围,渲染为 `th` 时使用
colSpannumber-单元格跨越的列数
rowSpannumber-单元格跨越的行数
variantTableVariant-情景颜色变体,渲染为 `table-*` 类

TableSelectCell

属性名类型默认值描述
activebooleanfalse激活状态,渲染为 `table-active` 类
alignTableAlign-单元格垂直对齐方式,渲染为 `align-top`、`align-middle` 或 `align-bottom` 类
asElementType'td'渲染的元素标签,可传 `th` 作为表头全选单元格
checkedboolean-受控选中状态
disabledbooleanfalse禁用复选框
indeterminatebooleanfalse半选状态,常用于表头全选单元格
labelstring-复选框无障碍标签,渲染为 `aria-label`
namestring-复选框原生 `name`
onChange(checked: boolean, event: ChangeEvent<HTMLInputElement>) => void-选中状态变化回调,携带选中值与原生事件
valuestring-复选框原生 `value`,通常传行唯一键
variantTableVariant-情景颜色变体,渲染为 `table-*` 类

TableExpandCell

属性名类型默认值描述
activebooleanfalse激活状态,渲染为 `table-active` 类
alignTableAlign-单元格垂直对齐方式,渲染为 `align-top`、`align-middle` 或 `align-bottom` 类
asElementType'td'渲染的元素标签
collapseLabelstring'Collapse'展开状态下的开关无障碍标签,渲染为 `aria-label`
disabledbooleanfalse禁用展开开关
expandLabelstring'Expand'收起状态下的开关无障碍标签,渲染为 `aria-label`
expandedbooleanfalse展开状态,设置 `aria-expanded` 并切换箭头方向
onToggle(expanded: boolean, event: MouseEvent<HTMLButtonElement>) => void-开关点击回调,携带切换后的展开状态与原生事件
variantTableVariant-情景颜色变体,渲染为 `table-*` 类

TableEditCell

属性名类型默认值描述
activebooleanfalse激活状态,渲染为 `table-active` 类
alignTableAlign-单元格垂直对齐方式,渲染为 `align-top`、`align-middle` 或 `align-bottom` 类
asElementType'td'渲染的元素标签
cancelLabelstring'Cancel'取消按钮无障碍标签,渲染为 `aria-label`
childrenReactNode-自定义显示内容,不传时显示 `value`,双击单元格进入编辑
defaultEditingbooleanfalse非受控初始编辑状态
defaultValueTableEditValue''非受控初始值
disabledbooleanfalse禁用编辑
editingboolean-受控编辑状态
inputPropsInputHTMLAttributes<HTMLInputElement>-编辑输入框原生属性
onCancel() => void-取消编辑回调
onEditingChange(editing: boolean) => void-编辑状态变化回调,受控时由使用者更新 `editing`
onSave(value: TableEditValue) => void-保存回调,携带校验通过后提交的值
optionsTableEditOption[]-`type` 为 `select` 时的选项列表
placeholderstring-编辑器占位文本
saveLabelstring'Save'保存按钮无障碍标签,渲染为 `aria-label`
selectPropsSelectHTMLAttributes<HTMLSelectElement>-`type` 为 `select` 时透传的原生属性
textareaPropsTextareaHTMLAttributes<HTMLTextAreaElement>-`type` 为 `textarea` 时透传的原生属性
typeTableEditType'text'编辑器类型,支持 `text`、`number`、`select` 与 `textarea`
validator(value: TableEditValue) => string | undefined-校验函数,返回错误信息时阻止保存并显示错误
valueTableEditValue-受控值,进入编辑时作为初始草稿

TableEmpty

属性名类型默认值描述
cellClassNamestring-空状态单元格自定义类名
childrenReactNode-空状态内容,可放置提示文字与操作按钮
classNamestring-空状态行自定义类名
colSpannumber-空状态单元格跨列数,通常传表格总列数

TableLoading

属性名类型默认值描述
cellClassNamestring-加载状态单元格自定义类名
childrenReactNode-加载状态内容,渲染在加载指示器右侧
classNamestring-加载状态行自定义类名
colSpannumber-加载状态单元格跨列数,通常传表格总列数

TableResponsive

属性名类型默认值描述
asElementType'div'渲染的元素标签
breakpointTableBreakpoint | boolean-响应式断点,`true` 始终横向滚动,或传入断点 `sm`、`md`、`lg`、`xl`、`xxl`

TableDetailRow

属性名类型默认值描述
cellClassNamestring-详情单元格自定义类名
childrenReactNode-展开后的详情内容,可放置字段网格、嵌套表格等任意内容
classNamestring-详情行自定义类名
colSpannumber-详情单元格跨列数,通常传表格总列数

Common Props

属性名类型默认值描述
childrenReactNode-表格内容
classNamestring-自定义类名
...restHTMLAttributes-透传原生元素属性(如 `onClick`、`style` 等)

Type Definitions

TableAlign

表格与单元格垂直对齐方式类型

export type TableAlign = 'bottom' | 'middle' | 'top';

TableBreakpoint

响应式表格断点类型

export type TableBreakpoint = 'lg' | 'md' | 'sm' | 'xl' | 'xxl';

TableCellScope

表头单元格关联范围类型

export type TableCellScope = 'col' | 'colgroup' | 'row' | 'rowgroup';

TableEditOption

行内编辑下拉选项类型

export interface TableEditOption {
  disabled?: boolean;
  label: string;
  value: string;
}

TableEditType

行内编辑器类型

export type TableEditType = 'number' | 'select' | 'text' | 'textarea';

TableEditValue

行内编辑值类型

export type TableEditValue = number | string;

TableSortDirection

表格排序方向类型

export type TableSortDirection = 'ascending' | 'descending';

TableSortValue

表格排序值类型

export type TableSortValue = number | string | undefined;

TableSize

表格尺寸类型

export type TableSize = 'sm';

TableStriped

表格条纹样式类型

export type TableStriped = 'columns' | boolean;

TableVariant

表格情景颜色变体类型

export type TableVariant =
  'danger' | 'dark' | 'info' | 'light' | 'primary' | 'secondary' | 'success' | 'warning';

TableCaptionProps

表格标题组件属性接口

export interface TableCaptionProps extends HTMLAttributes<HTMLElement> {
  as?: ElementType;
  captionTop?: boolean;
  children?: ReactNode;
  className?: string;
}

TableCellProps

表格单元格组件属性接口

export interface TableCellProps extends HTMLAttributes<HTMLElement> {
  active?: boolean;
  align?: TableAlign;
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  colSpan?: number;
  rowSpan?: number;
  scope?: TableCellScope;
  variant?: TableVariant;
}

TableDetailRowProps

展开详情行组件属性接口

export interface TableDetailRowProps extends HTMLAttributes<HTMLTableRowElement> {
  cellClassName?: string;
  children?: ReactNode;
  className?: string;
  colSpan?: number;
}

TableEditCellProps

行内编辑单元格组件属性接口

export interface TableEditCellProps extends HTMLAttributes<HTMLElement> {
  active?: boolean;
  align?: TableAlign;
  as?: ElementType;
  cancelLabel?: string;
  children?: ReactNode;
  className?: string;
  defaultEditing?: boolean;
  defaultValue?: TableEditValue;
  disabled?: boolean;
  editing?: boolean;
  inputProps?: Omit<InputHTMLAttributes<HTMLInputElement>, 'onChange' | 'type' | 'value'>;
  onCancel?: () => void;
  onEditingChange?: (editing: boolean) => void;
  onSave?: (value: TableEditValue) => void;
  options?: readonly TableEditOption[];
  placeholder?: string;
  saveLabel?: string;
  selectProps?: Omit<SelectHTMLAttributes<HTMLSelectElement>, 'onChange' | 'value'>;
  textareaProps?: Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'onChange' | 'value'>;
  type?: TableEditType;
  validator?: (value: TableEditValue) => string | undefined;
  value?: TableEditValue;
}

TableEmptyProps

空状态行组件属性接口

export interface TableEmptyProps extends HTMLAttributes<HTMLTableRowElement> {
  cellClassName?: string;
  children?: ReactNode;
  className?: string;
  colSpan?: number;
}

TableExpandCellProps

展开开关单元格组件属性接口

export interface TableExpandCellProps extends Omit<HTMLAttributes<HTMLElement>, 'onToggle'> {
  active?: boolean;
  align?: TableAlign;
  as?: ElementType;
  className?: string;
  collapseLabel?: string;
  disabled?: boolean;
  expandLabel?: string;
  expanded?: boolean;
  onToggle?: (expanded: boolean, event: MouseEvent<HTMLButtonElement>) => void;
  variant?: TableVariant;
}

TableLoadingProps

加载状态行组件属性接口

export interface TableLoadingProps extends HTMLAttributes<HTMLTableRowElement> {
  cellClassName?: string;
  children?: ReactNode;
  className?: string;
  colSpan?: number;
}

TableProps

表格容器组件属性接口

export interface TableProps extends HTMLAttributes<HTMLTableElement> {
  align?: TableAlign;
  as?: ElementType;
  bordered?: boolean;
  borderless?: boolean;
  children?: ReactNode;
  className?: string;
  hover?: boolean;
  responsive?: boolean | TableBreakpoint;
  size?: TableSize;
  striped?: TableStriped;
  variant?: TableVariant;
}

TableResponsiveProps

响应式表格容器组件属性接口

export interface TableResponsiveProps extends HTMLAttributes<HTMLDivElement> {
  as?: ElementType;
  breakpoint?: boolean | TableBreakpoint;
  children?: ReactNode;
  className?: string;
}

TableRowProps

表格行组件属性接口

export interface TableRowProps extends HTMLAttributes<HTMLTableRowElement> {
  active?: boolean;
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  variant?: TableVariant;
}

TableSectionProps

表格分区(表头/表体/表尾)组件属性接口

export interface TableSectionProps extends HTMLAttributes<HTMLElement> {
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  variant?: TableVariant;
}

TableSelectCellProps

选择单元格组件属性接口

export interface TableSelectCellProps extends Omit<HTMLAttributes<HTMLElement>, 'onChange'> {
  active?: boolean;
  align?: TableAlign;
  as?: ElementType;
  checked?: boolean;
  className?: string;
  disabled?: boolean;
  indeterminate?: boolean;
  label?: string;
  name?: string;
  onChange?: (checked: boolean, event: ChangeEvent<HTMLInputElement>) => void;
  value?: string;
  variant?: TableVariant;
}

ExportTableCsvOptions

导出 CSV 配置参数接口

export interface ExportTableCsvOptions<Row> {
  columns: readonly TableCsvColumn<Row>[];
  filename?: string;
  rows: readonly Row[];
}

TableColumnPreference

列偏好定义类型

export interface TableColumnPreference {
  key: string;
  label: string;
  visible: boolean;
  width?: number;
}

TableCsvColumn

CSV 导出列定义类型

export interface TableCsvColumn<Row> {
  key: string;
  label?: string;
  value?: (row: Row) => number | string | undefined;
}

UseTableEditingOptions

useTableEditing 配置参数接口

export interface UseTableEditingOptions<Key> {
  defaultEditingKey?: Key | null;
  editingKey?: Key | null;
  onEditingKeyChange?: (key: Key | null) => void;
}

UseTableEditingResult

useTableEditing 返回值接口

export interface UseTableEditingResult<Key> {
  cancelEdit: () => void;
  editingKey: Key | null;
  isEditing: (key: Key) => boolean;
  startEdit: (key: Key) => void;
}

UseTableExpansionOptions

useTableExpansion 配置参数接口

export interface UseTableExpansionOptions<Key> {
  initialExpandedKeys?: Iterable<Key>;
}

UseTableExpansionResult

useTableExpansion 返回值接口

export interface UseTableExpansionResult<Key> {
  collapse: (key: Key) => void;
  collapseAll: () => void;
  expand: (key: Key) => void;
  expandAll: (keys: Iterable<Key>) => void;
  expandedCount: number;
  expandedKeys: ReadonlySet<Key>;
  isExpanded: (key: Key) => boolean;
  setExpandedKeys: (keys: Iterable<Key>) => void;
  toggle: (key: Key) => void;
  toggleAll: (keys: Iterable<Key>) => void;
}

UseTableOptions

useTable 配置参数接口

export interface UseTableOptions<Row, Key> {
  getRowKey: (row: Row) => Key;
  initialRows?: readonly Row[];
}

UseTableResult

useTable 返回值接口

export interface UseTableResult<Row, Key> {
  addRow: (row: Row, index?: number) => void;
  clear: () => void;
  getRowKey: (row: Row) => Key;
  keys: readonly Key[];
  removeRow: (key: Key) => void;
  removeRows: (keys: Iterable<Key>) => void;
  rows: readonly Row[];
  setRows: (rows: readonly Row[]) => void;
  updateRow: (key: Key, updater: (row: Row) => Row) => void;
}

UseTableSelectionOptions

useTableSelection 配置参数接口

export interface UseTableSelectionOptions<Key> {
  initialSelectedKeys?: Iterable<Key>;
}

UseTableSelectionResult

useTableSelection 返回值接口

export interface UseTableSelectionResult<Key> {
  clear: () => void;
  deselect: (key: Key) => void;
  isAllSelected: (keys: Iterable<Key>) => boolean;
  isIndeterminate: (keys: Iterable<Key>) => boolean;
  isSelected: (key: Key) => boolean;
  select: (key: Key) => void;
  selectAll: (keys: Iterable<Key>) => void;
  selectedCount: number;
  selectedKeys: ReadonlySet<Key>;
  setSelectedKeys: (keys: Iterable<Key>) => void;
  toggle: (key: Key) => void;
  toggleAll: (keys: Iterable<Key>) => void;
}

UseTableColumnsOptions

useTableColumns 配置参数接口

export interface UseTableColumnsOptions {
  initialColumns: readonly TableColumnPreference[];
  storageKey?: string;
}

UseTableColumnsResult

useTableColumns 返回值接口

export interface UseTableColumnsResult {
  columns: readonly TableColumnPreference[];
  getColumn: (key: string) => TableColumnPreference | undefined;
  reset: () => void;
  setColumns: (columns: readonly TableColumnPreference[]) => void;
  setColumnVisible: (key: string, visible: boolean) => void;
  setColumnWidth: (key: string, width: number) => void;
  toggleColumn: (key: string) => void;
  visibleColumns: readonly TableColumnPreference[];
  visibleCount: number;
}

UseTableFilterOptions

useTableFilter 配置参数接口

export interface UseTableFilterOptions<Row> {
  initialFilters?: Readonly<Record<string, unknown>>;
  predicate?: (row: Row, filters: Readonly<Record<string, unknown>>) => boolean;
}

UseTableFilterResult

useTableFilter 返回值接口

export interface UseTableFilterResult<Row> {
  clearFilters: () => void;
  filterCount: number;
  filterRows: (rows: readonly Row[]) => readonly Row[];
  filters: Readonly<Record<string, unknown>>;
  hasFilter: (key: string) => boolean;
  hasFilters: boolean;
  removeFilter: (key: string) => void;
  setFilter: (key: string, value: unknown) => void;
  setFilters: (filters: Readonly<Record<string, unknown>>) => void;
}

UseTablePaginationOptions

useTablePagination 配置参数接口

export interface UseTablePaginationOptions {
  initialPage?: number;
  initialPageSize?: number;
  pageSizeOptions?: readonly number[];
  totalCount?: number;
}

UseTablePaginationResult

useTablePagination 返回值接口

export interface UseTablePaginationResult {
  endIndex: number;
  firstPage: () => void;
  getPageRows: <Row>(rows: readonly Row[]) => readonly Row[];
  hasNextPage: boolean;
  hasPreviousPage: boolean;
  lastPage: () => void;
  nextPage: () => void;
  page: number;
  pageSize: number;
  pageSizeOptions: readonly number[];
  previousPage: () => void;
  setPage: (page: number) => void;
  setPageSize: (pageSize: number) => void;
  startIndex: number;
  totalPages: number;
}

UseTableSearchOptions

useTableSearch 配置参数接口

export interface UseTableSearchOptions<Row> {
  fields?: readonly string[];
  initialQuery?: string;
  match?: (row: Row, query: string) => boolean;
}

UseTableSearchResult

useTableSearch 返回值接口

export interface UseTableSearchResult<Row> {
  clear: () => void;
  hasQuery: boolean;
  matches: (row: Row) => boolean;
  query: string;
  searchRows: (rows: readonly Row[]) => readonly Row[];
  setQuery: (query: string) => void;
}

UseTableSortingOptions

useTableSorting 配置参数接口

export interface UseTableSortingOptions {
  initialDirection?: TableSortDirection;
  initialSortKey?: string;
}

UseTableSortingResult

useTableSorting 返回值接口

export interface UseTableSortingResult {
  clearSort: () => void;
  direction: TableSortDirection;
  isActive: (key: string) => boolean;
  setSort: (key: string, direction?: TableSortDirection) => void;
  sortKey: string | undefined;
  sortRows: <Row>(
    rows: readonly Row[],
    getValue?: (row: Row, key: string) => TableSortValue,
  ) => readonly Row[];
  toggleSort: (key: string) => void;
}