直接跳到内容

Tabulator 表格

Tabulator组件提供了一个功能丰富的交互式表格,可用于显示、编辑和操作Pandas DataFrame数据。

底层实现为panel.widgets.Tabulator,参数基本一致,参考文档:https://panel.holoviz.org/reference/widgets/Tabulator.html

基本用法

在编辑单元格时,Tabulator 的 value 数据会实时更新,你可以通过常规的 @change 监听变化。但如果需要精确获取被修改的单元格信息,还可以绑定 @edit,该回调会接收一个 TableEditEvent 对象,其中包含以下字段:

  • column:被编辑列的名称
  • row:被编辑行在 DataFrame 中的整数索引
  • old:单元格的旧值
  • value:单元格的新值

Formatter 格式化器

使用 Bokeh Formatter

默认情况下,该组件会根据列的数据类型自动选择适合的Bokeh CellFormatter(单元格格式化器)和CellEditor(单元格编辑器)类型。用户也可以通过显式指定字典来覆盖默认设置,将列名映射到特定的编辑器或格式化器实例。例如在下面的示例中,我们创建了一个NumberFormatter来定制float列的数字格式,并使用BooleanFormatter实例以勾选/叉号形式显示bool列的值。

有效的 Bokeh 格式化程序列表包括:

使用 Tabulator Formatter

除了使用 Bokeh 提供的格式化器之外,还可以使用 Tabulator 库内置的有效格式化器。这些格式化器可以定义为字符串,或者以字典形式声明类型及其他参数(作为 formatterParams 传递给 Tabulator)。

可用的 Tabulator 格式化器列表可在 Tabulator 文档中查阅。

需要注意的是,类似的规则也可通过 title_formatters 参数应用于列标题(但不支持 Bokeh 的 CellFormatter 类型)。

Editors 编辑器

与格式化器类似,Tabulator 能够原生支持 Bokeh 的编辑器类型,但在底层实现中,它会将大部分 Bokeh 编辑器替换为 Tabulator 库原生支持的等效编辑器。

因此,通常更推荐直接使用 Tabulator 的原生编辑器。将某列的编辑器设为 None 会使该列不可编辑。需要注意的是,除了标准的 Tabulator 编辑器外,Tabulator 组件还额外支持 'date'(日期)和 'datetime'(日期时间)编辑器。

嵌套编辑器

假设你需要让某个单元格的编辑器依赖于另一个单元格的值,可以使用 nested type。嵌套类型需要两个参数:optionslookup_order,其中 lookup_order 用于指定选项的查找顺序。

我们创建一个包含三列的简单 DataFrame,其中第 2 列的选项取决于第 0 列和第 1 列的值:

  • 如果第 0 列的值为 A,则第 2 列的选项范围固定为 15
  • 如果第 0 列的值为 B,则第 2 列的选项还会进一步取决于第 1 列的值。

关于嵌套编辑器,需要注意以下几点:

  • options 字典的键只能是字符串。
  • 必须确保 nested 编辑器始终有可用的有效选项。
  • 无法保证当前显示的值一定是有效选项(可能存在依赖关系变化导致的值失效)。

针对最后一点,你可以使用 @edit来修正或清空无效值。以下是一个清空无效值的示例:

列布局

默认情况下,DataFrame 组件会根据内容自动调整列宽和表格大小,这对应参数 layout="fit_data_table" 的默认行为。此外,还支持其他布局模式,例如手动指定列宽、均分列宽或仅调整列尺寸。

手动设置列宽

如需手动设置列宽,只需为每列显式指定宽度:

自动调整列宽

通过 layout 参数自动调整列宽:

  • fit_data_table(默认模式):自动调整列宽并优化表格整体尺寸(最常用且推荐):
  • fit_data:根据列内容自动调整列宽(不拉伸表格整体宽度)。
  • fit_data_stretch:在适应内容的同时,拉伸最后一列以填满可用空间。
  • fit_data_fill:适应内容并填充空间,但不拉伸最后一列(其余列均分剩余宽度)。
  • fit_columns:每列相同大小

对齐方式

样式设置

基本样式设置

根据表格内容或其他条件进行样式定制是一项非常重要的功能。幸运的是,pandas 提供了一个强大的 styling APIiiii,可与 Tabulator 组件配合使用。具体来说,Tabulator 组件暴露了与 pandas.DataFrame 类似的 .style 属性,允许用户通过 .apply.applymap 等方法应用自定义样式。详细指南可参考 Pandas 官方文档

渐变样式设置

通过 .text_gradient(文本渐变)或 .background_gradient(背景渐变)方法,配合 Matplotlib 配色方案,可以为表格添加渐变效果:

主题

Tabulator 库内置了多种主题,这些主题以 CSS 样式表的形式定义。因此,更改一个表格的主题会影响页面上的所有表格。通常建议在类级别统一设置主题,例如:

完整的主题列表请参阅 Tabulator 文档,默认提供的主题包括:

  • 'simple'
  • 'default'
  • 'midnight'
  • 'site'
  • 'modern'
  • 'bootstrap'
  • 'bootstrap4'
  • 'materialize'
  • 'semantic-ui'
  • 'bulma'

此外,您还可以按照 官方说明 添加自定义主题类。

更改字体大小

不同主题的字体大小可能有所不同。例如,“bootstrap”主题的字体大小为 13px,而“bootstrap5”主题的字体大小为 16px。以下是将主题“bootstrap5”的字体大小值覆盖为 10px 的一种方法。

python
 <PnTabulator :stylesheets='[":host .tabulator {font-size: 10px;}"]' ...

选择/点击

冻结行列

冻结列

冻结行

Row Content 行内容扩展

Groupby 分组

分层多级索引

分页

过滤

客户端过滤

下载

按钮

流式数据

数据补丁

静态配置

API

属性

属性名说明类型默认值
aggregators多级索引聚合配置(支持'min','max','mean','sum')dict {}
buttons表格按钮配置(列名到HTML内容的映射)dict {}
configurationTabulator原生配置选项dict {}
editors列编辑器配置(列名到编辑器实例的映射)dict {}
embed_content是否嵌入展开行内容bool False
expanded当前展开的行索引列表list []
filters客户端过滤器配置列表list []
formatters列格式化器配置(列名到格式化器的映射)dict {}
frozen_columns固定列配置(列表或字典形式)list|dict []
frozen_rows固定行索引列表list []
groupby分组依据列名列表list []
header_align表头对齐方式('left','center','right')dict|str 'left'
header_filters表头过滤器配置(布尔值或列配置字典)bool|dict False
header_tooltips表头提示文本映射dict {}
hidden_columns隐藏列名列表list []
hierarchical是否启用多级索引分层显示bool False
initial_page_size初始每页行数(分页启用时)int 20
layout列布局模式('fit_columns','fit_data'等)str 'fit_data_table'
page当前页码(分页启用时)int 1
page_size每页行数(None时自动计算)int|None None
pagination分页模式('local','remote'或None禁用)str|None None
row_content行展开内容生成函数callable None
selection当前选中行索引列表list []
selectable选择模式配置(布尔/字符串/整数)bool|str|int True
selectable_rows可选行过滤函数callable None
show_index是否显示索引列bool True
sortable是否可排序(全局或按列配置)bool|dict True
sorters排序器配置列表list []
text_align文本对齐方式('left','center','right')dict|str 'left'
themeCSS主题('simple','bootstrap'等)str 'simple'
theme_classes额外CSS类列表list[str ][]
title_formatters标题格式化器配置dict {}
titles列标题重写映射dict {}
value显示的DataFrame数据pd.DataFrame None
widths列宽度配置映射dict {}
disabled是否禁用单元格编辑bool False

计算属性

属性名说明类型

事件

事件名说明类型
click单元格点击事件(含行列值信息)CellClickEvent 
edit单元格编辑事件(含新旧值信息)TableEditEvent 
change数据更新事件Event 

方法

方法名说明返回值类型
download下载表格数据Callable 
patch更新数据表格Callable 

Controls

src/examples/panel_vuepy/widgets/Tabulator

Tabulator 表格已经加载完毕