QModelRoleDataSpan Class
QModelRoleDataSpan 类提供了一个覆盖QModelRoleData 对象的跨度。更多内容...
| 头文件： | #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 的主要用例是使模型能够通过一次调用返回对应于不同角色的数据。
为了从模型中绘制一个元素，视图（通过其委托）通常会通过调用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 对象数组（以及可能的对应span），并在后续对模型的调用中重复使用它。这有助于减少与创建和返回QVariant 对象相关的内存分配。
最后，给定一个 QModelRoleDataSpan 对象，模型的职责是填充该范围中每个角色对应的数据。具体实现方式取决于具体的模型类。以下是一个可能的实现示例，它遍历该范围，并对每个元素调用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> requires if_compatible_container<Container> 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，将其视为一个包含1个元素的数组。
[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
返回该 span 中第一个角色为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
返回对QModelRoleData 在span中位置index 处的可修改引用。
注意： index 必须是该 span 的有效索引（0 <=index <size())。
© 2026 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.
