Back to Qt.io
Contact Us Blog Download Qt

QModelRoleDataSpan Class

QModelRoleDataSpan 类为QModelRoleData 对象提供了一个跨度。更多

Header： #include <QModelRoleDataSpan>
CMake： find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake： QT += core
自Qt 6.0

公共函数

QModelRoleDataSpan()
QModelRoleDataSpan(Container &c)
QModelRoleDataSpan(QModelRoleData &modelRoleData)
QModelRoleDataSpan(QModelRoleData *modelRoleData, qsizetype len)
QModelRoleData *begin() const
QModelRoleData *data() const
QVariant *dataForRole(int role) const
QModelRoleData *end() const
qsizetype length() const
qsizetype size() const
QModelRoleData &operator[](qsizetype index) const

详细说明

QModelRoleDataSpan 用作QModelRoleData 对象数组的抽象。

与视图一样，QModelRoleDataSpan 提供了一个小对象（指针和大小），可传递给需要检查数组内容的函数。QModelRoleDataSpan 可以从任何类似数组的序列（普通数组、QVector 、std::vector、QVarLengthArray 等）构造。此外，QModelRoleDataSpan 并不拥有序列，因此序列的存活时间必须长于任何引用它的 QModelRoleDataSpan 对象。

与视图不同，QModelRoleDataSpan 是一个 span，因此它允许修改底层元素。

QModelRoleDataSpan 的主要用例是使模型能在一次调用中返回不同角色对应的数据。

为了从模型中绘制一个元素，视图（通过其委托）通常会根据需要多次调用data() ，从而请求同一索引的多个角色：

QVariant text = model->data(index, Qt::DisplayRole);
QVariant decoration = model->data(index, Qt::DecorationRole);
QVariant checkState = model->data(index, Qt::CheckStateRole);
// etc.

QModelRoleDataSpan 允许视图只调用一次函数就能请求相同的数据。

这可以通过让视图准备一个合适的QModelRoleData 对象数组来实现，每个对象都用应获取的角色来初始化。然后将该数组封装在 QModelRoleDataSpan 对象中，再将其传递给模型的multiData() 函数。

std::array<QModelRoleData, 3> roleData = { {
    QModelRoleData(Qt::DisplayRole),
    QModelRoleData(Qt::DecorationRole),
    QModelRoleData(Qt::CheckStateRole)
} };

// Usually, this is not necessary: A QModelRoleDataSpan
// will be built automatically for you when passing an array-like
// container to multiData().
QModelRoleDataSpan span(roleData);

model->multiData(index, span);

// Use roleData[0].data(), roleData[1].data(), etc.

我们鼓励视图存储QModelRoleData 对象数组（可能还有相应的跨度），并在随后对模型的调用中重复使用。这样可以减少与创建和返回QVariant 对象相关的内存分配。

最后，给定一个 QModelRoleDataSpan 对象后，模型的责任就是填写 span 中每个角色对应的数据。如何填写取决于具体的模型类。下面是一个可能实现的草图，该草图会遍历 span 并在每个元素上使用setData() ：

void MyModel::multiData(const QModelIndex &index, QModelRoleDataSpan roleDataSpan) const
{
    for (QModelRoleData &roleData : roleDataSpan) {
        int role = roleData.role();

        // ... obtain the data for index and role ...

        roleData.setData(result);
    }
}

另请参阅 模型/视图编程和QAbstractItemModel::multiData()。

成员函数文档

[constexpr noexcept] QModelRoleDataSpan::QModelRoleDataSpan()

构造一个空的 QModelRoleDataSpan。它的data() 将设为nullptr ，长度设为零。

[constexpr noexcept(...)] template <typename Container, QModelRoleDataSpan::if_compatible_container<Container> = true> QModelRoleDataSpan::QModelRoleDataSpan(Container &c)

构造一个跨容器c 的 QModelRoleDataSpan，该容器可以是QModelRoleData 对象的任何连续容器。例如，它可以是一个QVector<QModelRoleData> 、一个std::array<QModelRoleData, 10> 等。

注： 只要该对象未被销毁，容器就必须保持存活。

注： 当noexcept(std::data(c)) && noexcept(std::size(c)) 为true 时，此函数为 noexcept。

[constexpr noexcept] QModelRoleDataSpan::QModelRoleDataSpan(QModelRoleData &modelRoleData)

构造一个跨modelRoleData 的 QModelRoleDataSpan，将其视为一个单元素数组。

[constexpr] QModelRoleDataSpan::QModelRoleDataSpan(QModelRoleData *modelRoleData, qsizetype len)

构造一个 QModelRoleDataSpan，从modelRoleData 开始跨数组，长度为len 。

注意： 只要该对象未被析构，数组就必须保持有效。

[constexpr noexcept] QModelRoleData *QModelRoleDataSpan::begin() const

返回指向该对象所代表的跨度起点的指针。

[constexpr noexcept] QModelRoleData *QModelRoleDataSpan::data() const

返回指向该对象所代表的跨度起点的指针。

[constexpr] QVariant *QModelRoleDataSpan::dataForRole(int role) const

返回与跨中第一个角色等于role 的QModelRoleData 相关联的数据。如果不存在这样的QModelRoleData 对象，则行为未定义。

注意： 避免从模型端调用此函数，因为模型不可能事先知道给定的QModelRoleDataSpan 中有哪些角色。该函数适用于视图和委托，因为视图和委托可以控制 span 中的角色。

另请参阅 QModelRoleData::data() 。

[constexpr noexcept] QModelRoleData *QModelRoleDataSpan::end() const

返回指向该对象所代表的跨度末端之后一个虚元的指针。

[constexpr noexcept] qsizetype QModelRoleDataSpan::length() const

返回此对象所代表的跨度的长度。

[constexpr noexcept] qsizetype QModelRoleDataSpan::size() const

返回此对象所代表的跨度的长度。

[constexpr] QModelRoleData &QModelRoleDataSpan::operator[](qsizetype index) const

返回位于跨距中index 位置的QModelRoleData 的可修改引用。

注意： index 必须是该跨度的有效索引（0 <=index <size() ）。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.