QT编程(18): Qt QItemSelectionModel介绍

娇娇yyyyyy

474人浏览 · 2026-03-23 14:01:55

娇娇yyyyyy · 2026-03-23 14:01:55 发布

Qt QItemSelectionModel介绍

QItemSelectionModel是Qt模型/视图（Model/View）框架中的核心组件之一，继承自QObject，主要用于跟踪一个或多个视图中选中项的状态，同时管理当前焦点选中项，是连接视图（如QTableView、QTreeView、QListView）与数据模型（QAbstractItemModel子类）的“选择桥梁”，负责协调选中状态的更新、查询与信号通知，无需开发者手动维护选中项的状态，大幅简化了交互式选择功能的开发难度。

一、核心定位与作用

在Qt模型/视图架构中，数据模型（Model）负责存储和提供数据，视图（View）负责展示数据，而QItemSelectionModel则专门负责“选中状态”的管理，其核心作用体现在三个方面：

状态追踪：记录视图中所有被选中的项（通过QModelIndex索引标识），支持单个、多个连续或离散项的选中状态管理，同时区分“已提交的选中项”和“当前交互中的选中项”两层选择逻辑。
交互协调：响应视图的用户操作（如点击、拖拽、Ctrl/Shift组合选择），自动更新选中状态，也支持通过代码主动修改选中项。
信号通知：当选中项发生变化（新增选中、取消选中）或当前焦点项变化时，发出对应信号，供开发者响应处理，实现自定义业务逻辑（如选中项数据编辑、删除等）。

注意：QItemSelectionModel本身不存储数据，仅维护选中状态，其工作依赖于关联的数据模型（QAbstractItemModel子类），一个数据模型可以对应多个QItemSelectionModel，实现不同视图对同一数据的独立选中状态管理。

二、核心特性与关键概念

2.1 核心类型：SelectionFlag（选择标志）

QItemSelectionModel通过SelectionFlag枚举定义选中操作的行为，常用标志及说明如下，可通过位或（|）组合使用，满足复杂选择需求：

选择标志	说明
NoUpdate	不执行任何选中操作，仅占位使用。
Clear	清除所有已选中的项，重置选中状态。
Select	将指定索引（或范围）的项设为选中状态。
Deselect	将指定索引（或范围）的项取消选中。
Toggle	切换指定索引的选中状态（选中→取消，取消→选中）。
Current	更新当前焦点项（与选中状态独立，焦点项不一定是选中项）。
Rows	将指定索引扩展为整行选中（适用于按行选择场景）。
Columns	将指定索引扩展为整列选中（适用于按列选择场景）。
ClearAndSelect	组合标志（Clear
SelectCurrent	组合标志（Select

2.2 关键属性

QItemSelectionModel提供了常用属性，方便快速查询选中状态，从Qt 5.5开始，部分属性支持通过元对象系统访问（可用于QML交互）：

selectedIndexes：只读属性，返回所有被选中项的QModelIndex列表，列表无重复项且未排序，是获取选中项的核心属性。
currentIndex：当前焦点项的QModelIndex，可通过setCurrentIndex()手动设置，与选中状态相互独立（焦点项可未被选中）。
hasSelection：只读属性，返回bool值，判断是否有任何项被选中，用于前置判断避免空操作。

2.3 选择行为与模式配合

QItemSelectionModel的选中逻辑需与视图的选择行为（SelectionBehavior）和选择模式（SelectionMode）配合使用，才能实现符合预期的选择效果，常用组合场景如下：

按行选择：视图设置setSelectionBehavior(QAbstractItemView::SelectRows)，配合SelectionFlag::Rows，实现点击行任意位置选中整行。
按列选择：视图设置setSelectionBehavior(QAbstractItemView::SelectColumns)，配合SelectionFlag::Columns，实现点击列任意位置选中整列。
多选模式：视图设置setSelectionMode(QAbstractItemView::ExtendedSelection)，支持Ctrl键多选、Shift键连续选，QItemSelectionModel自动跟踪所有选中项。

三、核心接口（常用函数、槽函数与信号）

3.1 构造函数与关联模型

QItemSelectionModel必须关联一个数据模型才能工作，常用构造函数如下，也可通过setModel()后续设置模型，模型变化时会发出modelChanged信号：

// 关联模型并指定父对象
QItemSelectionModel(QAbstractItemModel *model, QObject *parent = nullptr);
// 仅关联模型，无父对象
QItemSelectionModel(QAbstractItemModel *model = nullptr);
// 后续设置模型
void setModel(QAbstractItemModel *model);
// 获取关联的模型
QAbstractItemModel *model() const;

3.2 常用操作函数（选中、取消选中）

核心用于通过代码控制选中状态，支持单个索引、连续范围两种操作方式，操作后会触发selectionChanged信号：

单个索引操作：select(const QModelIndex &index, SelectionFlags command)
// 选中索引(0,0)对应的项 selectionModel->select(model->index(0, 0), QItemSelectionModel::Select); // 取消选中索引(0,0)对应的项 selectionModel->select(model->index(0, 0), QItemSelectionModel::Deselect); // 切换索引(0,0)的选中状态 selectionModel->select(model->index(0, 0), QItemSelectionModel::Toggle);
连续范围操作：先通过QItemSelection定义选择范围（左上、右下索引），再调用select()
// 定义从(0,0)到(2,1)的连续范围（3行2列） QModelIndex topLeft = model->index(0, 0); QModelIndex bottomRight = model->index(2, 1); QItemSelection selection(topLeft, bottomRight); // 清除原有选中项，选中该范围 selectionModel->select(selection, QItemSelectionModel::ClearAndSelect);

3.3 常用查询函数

用于查询选中状态和选中项信息，覆盖单个索引、行、列等场景，效率高于手动遍历索引：

bool isSelected(const QModelIndex &index)：判断指定索引是否被选中。
QModelIndexList selectedRows(int column = 0)：返回选中行的索引列表，每行仅返回指定列（默认第0列）的索引，适用于按行选择场景。
QModelIndexList selectedColumns(int row = 0)：返回选中列的索引列表，每列仅返回指定行（默认第0行）的索引。
bool isRowSelected(int row, const QModelIndex &parent = QModelIndex())：判断指定行（父索引下）是否全部被选中。
bool rowIntersectsSelection(int row, const QModelIndex &parent = QModelIndex())：判断指定行（父索引下）是否有任何项被选中。

3.4 槽函数（重置与清除）

用于快速重置选中状态，部分槽函数会触发信号，便于开发者同步更新界面：

void clear()：清除所有选中项和当前焦点项，发出selectionChanged和currentChanged信号。
void clearSelection()：仅清除选中项，不影响当前焦点项，发出selectionChanged信号。
void clearCurrentIndex()：仅清除当前焦点项，发出currentChanged信号。
void reset()：清除所有选中状态和焦点项，不发出任何信号（适用于模型数据大幅更新时，避免频繁信号触发）。

3.5 核心信号（响应选中变化）

QItemSelectionModel通过信号通知选中状态变化，开发者可连接这些信号，实现自定义业务逻辑，常用信号如下：

selectionChanged(const QItemSelection &selected, const QItemSelection &deselected)：选中项变化时触发，参数分别为“新增选中的范围”和“取消选中的范围”，是最常用的信号。
currentChanged(const QModelIndex &current, const QModelIndex &previous)：当前焦点项变化时触发，参数分别为“新焦点项”和“旧焦点项”。
currentRowChanged(const QModelIndex &current, const QModelIndex &previous)：焦点项所在行变化时触发（列变化不触发）。
currentColumnChanged(const QModelIndex &current, const QModelIndex &previous)：焦点项所在列变化时触发（行变化不触发）。
modelChanged(QAbstractItemModel *model)：关联的模型变化时触发。

四、实战示例（C++）

以下示例基于QTableView、QStandardItemModel和QItemSelectionModel，实现“表格选中行监控”功能，包含模型创建、视图配置、选中信号响应等核心步骤，可直接复用修改：

#include <QApplication>
#include <QTableView>
#include <QStandardItemModel>
#include <QItemSelectionModel>
#include <QDebug>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    // 1. 创建数据模型（4行2列）
    QStandardItemModel *model = new QStandardItemModel(4, 2);
    for (int i = 0; i < 4; ++i) {
        model->setItem(i, 0, new QStandardItem(QString("Name %1").arg(i)));
        model->setItem(i, 1, new QStandardItem(QString("Age %1").arg(20 + i)));
    }
    model->setHorizontalHeaderLabels({"姓名", "年龄"});

    // 2. 创建视图并配置选择模式/行为
    QTableView *tableView = new QTableView;
    tableView->setModel(model);
    // 按行选择，支持Ctrl/Shift多选
    tableView->setSelectionBehavior(QAbstractItemView::SelectRows);
    tableView->setSelectionMode(QAbstractItemView::ExtendedSelection);

    // 3. 获取视图关联的QItemSelectionModel（视图会自动创建，也可手动创建）
    QItemSelectionModel *selectionModel = tableView->selectionModel();

    // 4. 连接选中变化信号，处理选中逻辑
    QObject::connect(selectionModel, &QItemSelectionModel::selectionChanged,
                     [&](const QItemSelection &selected, const QItemSelection &deselected) {
        // 打印取消选中的项
        qDebug() << "取消选中的项：";
        for (const QModelIndex &idx : deselected.indexes()) {
            qDebug() << "行" << idx.row() << "列" << idx.column() << ":" << idx.data().toString();
        }

        // 打印新增选中的项，并获取选中行数据
        qDebug() << "新增选中的项：";
        QModelIndexList selectedRows = selectionModel->selectedRows();
        for (const QModelIndex &idx : selectedRows) {
            int row = idx.row();
            QString name = model->item(row, 0)->text();
            QString age = model->item(row, 1)->text();
            qDebug() << "选中行" << row << ":" << name << "," << age;
        }
    });

    // 5. 手动设置选中项（可选）
    QModelIndex topLeft = model->index(0, 0);
    QModelIndex bottomRight = model->index(1, 1);
    QItemSelection selection(topLeft, bottomRight);
    selectionModel->select(selection, QItemSelectionModel::Select | QItemSelectionModel::Rows);

    tableView->show();
    return app.exec();
}

五、注意事项

QItemSelectionModel与模型强关联，若模型数据发生大幅更新（如清空、重置），建议调用reset()方法重置选中状态，避免选中索引失效。
selectedIndexes()返回的列表未排序，若需按行/列顺序处理，需手动对列表进行排序（可通过QModelIndex的row()/column()排序）。
选择行为（SelectionBehavior）与SelectionFlag需匹配，例如按行选择时，需配合Rows标志，否则可能出现选中单个单元格而非整行的情况。
多个视图共享同一模型时，可创建多个QItemSelectionModel，实现各视图独立的选中状态管理；若需共享选中状态，多个视图可设置同一个QItemSelectionModel。
从Qt 5.15开始，部分查询函数（如columnIntersectsSelection）支持QML调用，可用于跨QWidget和QML的交互场景。

六、总结

QItemSelectionModel是Qt模型/视图框架中实现“选中功能”的核心组件，其核心价值在于解耦选中状态的管理与视图、模型，提供了丰富的接口用于选中操作、状态查询和信号响应，支持单个、多个、连续范围等多种选中场景，适配表格、树状、列表等各类视图。掌握其SelectionFlag、核心接口及与视图的配合方式，能快速实现灵活、高效的交互式选择功能，是Qt桌面应用开发中不可或缺的知识点。