QtShadcn
组件

ShadcnTable

基于 ShadcnTableModel + QQC.TableView 的表格组件。

用法

import QtShadcn

ShadcnTableModel {
    id: model
    columns: [
        { key: "name",  title: "姓名", width: 140, align: "left" },
        { key: "email", title: "邮箱", width: 240, align: "left" }
    ]
    rows: [
        { name: "Alice", email: "alice@qtshadcn.dev" },
        { name: "Bob",   email: "bob@qtshadcn.dev" }
    ]
}

ShadcnTable {
    model: model
    onRowClicked: row => console.log(model.getRow(row))
}

API

ShadcnTableModel(C++ / QML_ELEMENT)

属性 / 方法说明
rows: list行数据,元素为 QObject* 或 { key: value } 对象
columns: list列定义 { key, title, width, align }
cellData(row, col)取单元格值(QML 内部用,业务一般不需直接调)
getRow(row)取整行属性 map
updateRow(row, map)更新某行字段并刷新视图
sortBy(col, asc=true)按列排序(字符串/数字自动比较)

ShadcnTable(QML)

属性默认说明
modelnullShadcnTableModel
rowHeight40行高
headerHeight40表头高
currentRow-1选中行(点击行后由组件写入)
rowClicked(row)—点击行信号
columnCount / rowCount0只读,当前模型的列数/行数,随模型信号更新
columnWidths—只读,拉伸后的实际列宽数组
totalWidth—只读,columnWidths 之和(不小于组件宽度),横向滚动范围

列宽分配

列宽是期望宽度,不是绝对宽度(对齐 shadcn 的 <table class="w-full">):

  • 列宽合计 < 组件宽度:按各列期望宽度比例放大,铺满整个组件。 例:三列 100/100/100 放在 600 宽的表格里 → 各变 200; 40/20/40 放在 600 里 → 240/120/240
  • 列宽合计 ≥ 组件宽度:保持各列原宽,超出部分靠 totalWidth 横向滚动

各列之和精确等于组件宽度(取整误差补到最后一列),所以表头、单元格、行底 分隔线始终在同一个右边缘收尾。

曾经的缺陷:只把 totalWidth 取 Math.max(列宽和, 组件宽),列本身没跟着 撑开 —— 表头和行分隔线停在「列宽合计」处,右侧空出一整块(showcase 里空 141px)。用 tst_ShadcnTable 的两条用例锁住(数据层 + 实际渲染层,两者不同: 数据对了但 delegate 仍用原始列宽,视觉上照样缺一块)。

交互

  • 点击行:写入 currentRow 并发出 rowClicked(row)
  • 点击表头:按该列排序;同一列再次点击切换升降序,换列回到升序
  • 横向滚动:表体横向滚动时表头同步平移,列不错位

风格:行 hover = theme.muted 半透明,选中行 = theme.muted;圆角/边框对齐既有组件体系。

实现注意:columnMeta() / cellData() 是 Q_INVOKABLE,没有属性通知信号。 组件内部把它们的结果抽成带 NOTIFY 的 columnCount / revision,由模型的 columnsChanged / modelReset / dataChanged 驱动刷新。直接绑 model ? model.columnCount() : 0 会在「模型晚于组件赋值」时永久停在 0(表头空白),自定义封装时不要踩这个坑。

Copyright © 2026