NiceGUI `ui.table` 基础

NiceGUI ui.table 基础

ui.table 是 NiceGUI 提供的一个组件，用于在页面上展示数据表格

---

基本概念

官方简介

A table based on Quasar’s QTable component.

参数	参考
rows:	list of row objects; 行对象列表
columns:	list of column objects (defaults to the columns of the first row)；列对象列表（默认为第一行的列）
column_defaults:	optional default column properties; 可选的默认列属性
row_key:	name of the column containing unique data identifying the row (default: “id”); 包含标识行的唯一数据的列的名称（默认值：“id”）
title:	title of the table; 表格标题
selection:	selection type (“single” or “multiple”; default: None); 选择类型（“单”或“多”；默认值：无）
pagination:	a dictionary correlating to a pagination object or number of rows per page (None hides the pagination, 0 means “infinite”; default: None).; 与分页对象或每页行数相关的字典（None隐藏分页，0表示“无限”；默认值：None）
on_select:	callback which is invoked when the selection changes; 当选择更改时调用的回调
on_pagination_change:	callback which is invoked when the pagination changes; 当分页更改时调用的回调

If selection is ‘single’ or ‘multiple’, then a selected property is accessible containing the selected rows.

如果 selection 为 ‘single’ 或 ‘multiple’，则可访问包含所选行的所选属性。

简介

• columns：定义表格的列，包括列标题、数据字段映射、对齐方式等。
• rows：定义表格的数据，每行是一个字典，键需要与 columns 中的 field 值对应。

columns 和 rows 的关系

• columns 的 field 指定了表格从 rows 中取值的键。
• 如果 columns 中的 field 未定义或与 rows 数据不匹配，该列的数据会显示为空白。

---

columns 字段说明

必须定义的字段

1. name

   • 唯一标识列的名称，表格内部使用。
   • 必须是字符串类型。

2. label

   • 表头中显示的列标题。
   • 如果未定义，表头中该列将显示为空白。

3. field

   • 指定从 rows 的哪个键中取值，绑定列与行数据。
   • 如果未定义，表格无法显示该列对应的数据。

可选字段

1. align

   • 控制列内容的对齐方式。
   • 可选值：'left', 'center', 'right'。
   • 默认值：'left'。

2. sortable

   • 是否允许对该列进行排序。
   • 类型：布尔值，默认值为 False。

3. width

   • 设置列宽，可以是像素值（如 '100px'）或百分比（如 '20%'）。

4. classes

   • 自定义 CSS 类，用于控制列样式。

---

示例代码

以下代码展示了一个完整的表格定义，包括两列：condition 和 val。

from nicegui import ui

# 定义表格的列
columns = [
    {
        'name': 'condition',     # 必须：唯一标识列
        'label': 'Condition',    # 必须：表头名称
        'field': 'condition',    # 必须：对应行数据的键
        'align': 'left',         # 可选：对齐方式
        'sortable': True,        # 可选：启用排序
        'width': '50%',          # 可选：列宽
    },
    {
        'name': 'val',
        'label': 'Value',
        'field': 'val',
        'align': 'center',
        'sortable': False,       # 可选：禁用排序
    },
]

# 定义表格的数据行
rows = [
    {'condition': 'a > 10', 'val': True},
    {'condition': 'b > 20', 'val': True},
    {'condition': 'c > 30', 'val': False},
]

# 创建 UI 表格

ui.table(
    columns=columns,
    rows=rows
)

ui.run()

运行效果

Condition	Value
a > 10	True
b > 20	True
c > 30	False

---

常见问题

示例：未定义 field

field 是表格列与行数据绑定的关键字段。表格通过 field 去 rows 中取值，如果未定义 field，表格无法知道该列需要显示哪些数据。

columns = [
    {'name': 'condition', 'label': 'Condition', 'align': 'left'},  # 缺少 field
    {'name': 'val', 'label': 'Value', 'align': 'center'},         # 缺少 field
]

结果：表头显示 Condition 和 Value，但行数据为空白。

正确方式

columns = [
    {'name': 'condition', 'label': 'Condition', 'field': 'condition', 'align': 'left'},
    {'name': 'val', 'label': 'Value', 'field': 'val', 'align': 'center'},
]

NiceGUI 官方文档：https://nicegui.io