DataTable 高级表格¶

MkDataTable 是基于 QTableWidget 深度定制的 shadcn-ui 风格高级数据表格。它集成了声明式列配置、全选/跨页多选记忆、图像灯箱大图预览、视频弹窗播放、操作栏动作按钮以及分页联动等企业级高级功能。

基础用法¶

高级表格预览

import os
from monkeyqt import MkDataTable

# 1. 声明式列配置
columns = [
    {"key": "date", "label": "录入日期", "width": 120},
    {"key": "name", "label": "操作人", "width": 80},
    {"key": "avatar", "label": "结果图片", "type": "image", "width": 80},
    {"key": "video", "label": "演示视频", "type": "video", "width": 80},
    {"key": "status", "label": "状态"},
    {"key": "action", "label": "操作", "type": "action", "width": 100}
]

# 2. 模拟数据集
mock_data = [
    {
        "id": "101", 
        "date": "2026-06-01", 
        "name": "王小虎", 
        "avatar": "assets/before.png", 
        "video": "assets/demo_video.mp4", 
        "status": "进行中"
    },
    {
        "id": "102", 
        "date": "2026-06-02", 
        "name": "李二狗", 
        "avatar": "assets/after.png", 
        "video": "assets/demo_video.mp4", 
        "status": "已完成"
    }
]

# 3. 实例化高级表格（每页展示 5 条数据）
data_table = MkDataTable(
    columns=columns, 
    data=mock_data, 
    page_size=5, 
    selection_enabled=True
)

# 4. 连接交互信号
data_table.selectionChanged.connect(lambda selected: print(f"当前选中：{len(selected)} 项"))
data_table.editRequested.connect(lambda index, row: print(f"编辑行号：{index}, 数据：{row['name']}"))
data_table.deleteRequested.connect(lambda index, row: print(f"删除行号：{index}, 数据：{row['name']}"))

核心特性¶

1. 声明式列类型¶

通过在列配置 columns 中指定 type 字段，可以极简地启用高级渲染单元格： - text (默认): 纯文本渲染，支持垂直居中与左对齐。 - image: 渲染为缩略图卡片，悬浮时高亮并显示预览图标，点击后弹出 MkLightboxDialog 渐入式大图灯箱。 - video: 渲染为带播放图标的暗底卡片，点击后弹出 MkVideoPlayerDialog 无边框渐入式视频播放弹窗。 - action: 渲染为编辑和删除动作按钮，分别内置 pencil 和 trash 的 Phosphor 图标，并支持悬浮变色 tooltip。

2. 跨页多选记忆¶

selection_enabled 设为 True 时，表头自动生成全选复选框，每行首列渲染选择框。 - 表格在换页或过滤刷新时，会自动记住跨页选中的行记录（依据数据项的 id 属性或绝对索引）。 - 点击表头复选框仅控制当前页的所有项勾选状态，不会清除其他已选中页的数据状态。

3. 开箱即用分页联动¶

组件底层封装了 MkPagination 组件，外部只需传入完整数据集，组件将自动进行客户端切片分页。

API¶

构造函数¶

MkDataTable(columns=None, data=None, page_size=10, selection_enabled=True, parent=None)

参数	类型	默认值	说明
`columns`	`list`	`None`	列配置信息列表，具体结构参考下方 `Column Schema`
`data`	`list`	`None`	初始数据集，每个元素为包含各列 `key` 值的字典
`page_size`	`int`	`10`	每页显示条数
`selection_enabled`	`bool`	`True`	是否启用多选复选框列
`parent`	`QWidget`	`None`	父组件

Column Schema 结构¶

列配置 columns 中的每个字典支持以下属性： - key: str (必须) 数据字字典的对应键值。 - label: str (必须) 列显示的标题文字。 - type: str (可选) 列渲染类型，可选值为 text / image / video / action，默认为 text。 - width: int (可选) 列固定宽度，若不填则拉伸填充。

方法¶

方法	返回类型	说明
`set_data(data)`	`None`	填充/更新数据集，重置跨页选中状态并返回第一页
`refresh_table()`	`None`	刷新当前页面表格单元格渲染
`get_selected_rows()`	`list`	获取当前选中的所有行记录字典列表

信号¶

信号	参数	说明
`selectionChanged`	`list`	选中状态发生变化时触发，传递所有选中的行记录字典列表
`editRequested`	`int, dict`	点击操作列中的编辑按钮时触发，传递 `(absolute_row_index, row_dict)`
`deleteRequested`	`int, dict`	点击操作列中的删除按钮时触发，传递 `(absolute_row_index, row_dict)`

继承¶

MkDataTable 继承自 QWidget。内部包含一个可利用 table_widget 属性访问 of QTableWidget 实例以及 pagination 属性访问 of MkPagination 实例。