Back to Qt.io
Contact Us Blog Download Qt
本页内容

QRangeModelAdapter Class

QRangeModelAdapter 提供了符合 `QAbstractItemModel` 规范的任意 C++ 范围访问方式。更多内容...

头文件： #include <QRangeModelAdapter>
CMake： find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake： QT += core
自： Qt 6.11
状态： 技术预览

该类处于技术预览阶段，内容可能会有变动。

QRangeModelAdapter 比较

类别可比较类型
相等性QRangeModelAdapter
相等性Range.

公共类型

(technology preview) struct ColumnIterator
(technology preview) struct ConstColumnIterator
(technology preview) struct ConstRowIterator
(technology preview) struct ConstRowReference
(technology preview) struct DataReference
(technology preview) struct RowIterator
(technology preview) struct RowReference
(technology preview) struct RowReferenceBase

公共函数

QRangeModelAdapter(Range &&range)
QRangeModelAdapter(Range &&range, Protocol &&protocol)
void assign(NewRange &&newRange)
void assign(std::initializer_list<Row> newRange)
void assign(InputIterator first, Sentinel last)
auto at(QSpan<const int> path)
auto at(int listRow)
auto at(int tableRow)
auto at(int treeRow)
decltype(auto) at(QSpan<const int> path) const
auto at(int listRow) const
decltype(auto) at(int tableRow) const
auto at(QSpan<const int> path, int column)
auto at(int tableRow, int column)
auto at(QSpan<const int> path, int column) const
auto at(int tableRow, int column) const
(since 6.12) auto at(const QModelIndex &index)
(since 6.12) auto at(const QModelIndex &index) const
int columnCount() const
QVariant data(int listRow) const
QVariant data(QSpan<const int> path, int column) const
QVariant data(int listRow, int role) const
QVariant data(int tableRow, int column) const
QVariant data(QSpan<const int> path, int column, int role) const
QVariant data(int tableRow, int column, int role) const
(since 6.12) QVariant data(const QModelIndex &index) const
(since 6.12) QVariant data(const QModelIndex &index, int role) const
bool hasChildren(QSpan<const int> row) const
(since 6.12) bool hasChildren(const QModelIndex &index) const
bool hasChildren(int row) const
QModelIndex index(int listRow) const
QModelIndex index(QSpan<const int> path, int column) const
QModelIndex index(int tableRow, int column) const
bool insertColumn(int before)
bool insertColumn(int before, D &&data)
bool insertColumns(int before, C &&data)
bool insertRow(QSpan<const int> before)
bool insertRow(int before)
bool insertRow(QSpan<const int> before, D &&data)
bool insertRow(int before, D &&data)
bool insertRow(int before, const QModelIndex &parent)
bool insertRow(int before, const QModelIndex &parent, D &&data)
bool insertRows(QSpan<const int> before, C &&data)
bool insertRows(int before, C &&data)
bool insertRows(int before, const QModelIndex &parent, C &&data)
Model *model() const
bool moveColumn(int from, int to)
bool moveColumns(int from, int count, int to)
bool moveRow(QSpan<const int> source, QSpan<const int> destination)
bool moveRow(int source, int destination)
bool moveRow(const QModelIndex &sourceParent, int sourceRow, const QModelIndex &destinationParent, int destinationChild)
bool moveRows(QSpan<const int> source, int count, QSpan<const int> destination)
bool moveRows(int source, int count, int destination)
bool moveRows(const QModelIndex &sourceParent, int sourceRow, int count, const QModelIndex &destinationParent, int destinationChild)
const QRangeModelAdapter<Range, Protocol, Model>::range_type &range() const
bool removeColumn(int column)
bool removeColumns(int column, int count)
bool removeRow(QSpan<const int> path)
bool removeRow(int row)
bool removeRow(int row, const QModelIndex &parent)
bool removeRows(QSpan<const int> path, int count)
bool removeRows(int row, int count)
bool removeRows(int row, int count, const QModelIndex &parent)
int rowCount() const
int rowCount(QSpan<const int> row) const
(since 6.12) int rowCount(const QModelIndex &index) const
int rowCount(int row) const
bool setData(int listRow, const QVariant &value, int role = Qt::EditRole)
bool setData(QSpan<const int> path, int column, const QVariant &value, int role = Qt::EditRole)
bool setData(int tableRow, int column, const QVariant &value, int role = Qt::EditRole)
(since 6.12) bool setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole)
QRangeModelAdapter<Range, Protocol, Model> &operator=(NewRange &&newRange)
QRangeModelAdapter<Range, Protocol, Model> &operator=(std::initializer_list<Row> newRange)
auto operator[](QSpan<const int> path)
auto operator[](int listRow)
auto operator[](int tableRow)
auto operator[](int treeRow)
decltype(auto) operator[](QSpan<const int> path) const
auto operator[](int listRow) const
decltype(auto) operator[](int tableRow) const

私有类型

range_type
bool operator!=(const QRangeModelAdapter<Range, Protocol, Model> &lhs, const QRangeModelAdapter<Range, Protocol, Model> &rhs)
bool operator==(const QRangeModelAdapter<Range, Protocol, Model> &lhs, const QRangeModelAdapter<Range, Protocol, Model> &rhs)

详细说明

QRangeModelAdapter 为 C++ 范围和QRangeModel 提供了一种类型安全且支持结构的 C++ API。通过该适配器对 C++ 范围所做的修改，会将变更通知给QRangeModel 的客户端。这可确保项目视图得到更新、缓存被清理，并且持久化项目索引被正确失效并适配。

构造与模型所有权

QRangeModelAdapter 必须基于 C++ 范围进行构造。与QRangeModel 类似，该范围可以通过左值或右值引用、引用包装器，以及原始指针或智能指针的形式提供。

std::vector<int> data = {1, 2, 3, 4, 5};
QRangeModelAdapter adapter(&data);

具体构建的类型由编译器根据构造函数的参数推导得出，而值类之间的差异可能会导致不同的行为。 因此，不应显式指定模板参数。但 C++ 不允许对非静态类数据成员进行类模板参数推导。若要将 QRangeModelAdapter 作为类的数据成员，请使用以下模式：

class Backend
{
    using Adapter = decltype(QRangeModelAdapter(std::vector<Book>{}));
    Adapter adapter = Adapter(std::vector<Book>{});

这将创建一个操作于未命名（即右值引用）`Books` 向量上的 `QRangeModelAdapter`。若要使适配器操作于指向 `Books` 列表的引用包装器，请改用以下写法：

    QList<Book> books = { /* ... */ };
    using Adapter = decltype(QRangeModelAdapter(std::ref(books)));
    Adapter adapter = Adapter(std::ref(books));
};

从范围构造适配器时，系统会隐式地从该范围构造一个QRangeModel 实例。使用model()获取该实例，并像往常一样将其传递给Qt Widgets 或Qt Quick 项视图。

QListView listView;
listView.setModel(adapter.model());

适配器拥有模型。由于 QRangeModelAdapter 是值类型，因此可以被复制和移动。所有副本共享同一个QRangeModel ，当适配器的最后一个副本被销毁时，该模型也将被销毁。

如果适配器是从左值引用或右值引用创建的，则适配器和模型将操作原始范围对象的副本。否则，通过适配器或模型进行的修改将写入原始范围对象。要访问更新后的范围，请使用range()：

QList<Book> books = {
    // ...
};
QRangeModelAdapter adapter(books);
tableView.setModel(adapter.model());

// show UI and where the user can modify the list

QList<Book> modifiedBooks = adapter.range();

若要将整个范围数据替换为来自另一个（兼容）范围的数据，请使用 `assign()` 函数或赋值运算符。

// reset to the original
adapter = books;
// or
adapter.assign(books);

访问项目数据

QRangeModelAdapter API 为模型操作的范围提供了类型安全的读写访问。 该适配器 API 基于 C++ 容器和范围（包括迭代器）的典型 API。要访问单个行和项，请使用 `at()`、相应的下标 `operator[]` 或 `data()`。这些函数的哪些重载可用，取决于构建该适配器所针对的范围。

将项目数据读取为 QVariant

data() 函数始终返回一个QVariant ，其中包含存储在指定位置和角色上的值。在列表中，可以通过指定行号的单个整数值来访问项目：

QVariant listItem = listAdapter.data(row);

如果范围是一个表格，则通过行和列来指定项目：

QVariant tableItem = tableAdapter.data(row, column);

如果范围是树，则使用行路径和单个列值来定位项目：

QVariant treeItem = treeAdapter.data({path, to, branch}, column);

使用单个整数作为行号可访问树的顶级节点。

QRangeModelAdapter listOfBooks(QList<Book>{
    // ~~~
});
QString bookTitle = listOfBooks.data(0, Book::TitleRole).toString();
Book multiRoleItem = listOfBooks.data(0).value<Book>();

如果未指定角色，则QVariant 将保留该位置上的整个项目。请使用QVariant::fromValue()模板函数来获取该项目的副本。

使用 at() 进行读写

data() 函数返回QVariant 使其具有灵活性，但同时也失去了类型安全性。对于所有项类型相同的范围，at() 函数提供了一种更符合常规 C++ 容器且类型安全的替代方案。 与data()类似，at()也提供了重载版本，用于访问列表中某行、表格中某行/列对以及树中某路径/列对处的项。不过，at()始终返回指定位置处的整个项；无法单独读取项的各个角色值。

正如 C++ 容器 API 所预期的那样，at() 的 const 重载（以及相应的下标操作符operator[]()）提供对值的不可变访问，而可变重载则返回一个可被赋予新值的引用对象。 请注意，对 const 范围进行操作的 QRangeModelAdapter 在这方面的行为与 const QRangeModelAdapter 相同。 可变重载已被从重载集移除，因此编译器将始终选择 const 版本。尝试调用会修改范围的函数将导致编译器报错，即使适配器本身是可变的：

const QStringList strings = {"On", "Off"};
QRangeModelAdapter adapter(strings);
adapter.at(0) = "Undecided"; // compile error: return value of 'at' is const
adapter.insertRow(0); // compiler error: requirements not satisfied

返回的引用对象是包装器，它们会隐式转换为底层类型，具有用于显式访问底层值的get()函数，以及用于直接访问const成员函数的operator->()函数。然而，为了防止绕过QAbstractItemModel 通知协议的意外数据更改，这些引用对象会阻止对项的直接修改。

注意：访问 引用对象时，系统总会调用模型以获取值的副本。此操作可能消耗较大资源；对于对性能要求较高的数据访问，请存储一份副本。

项访问

如果范围以列表形式表示，则仅可使用接受一行作为参数的重载方法。

QRangeModelAdapter list(std::vector<int>{1, 2, 3, 4, 5});
listView.setModel(list.model());

int firstValue = list.at(0); // == 1
list.at(0) = -1;
list.at(1) = list.at(4);

const 重载返回该行处的元素，而可变重载则返回一个包装器，该包装器会隐式地与列表的值类型进行相互转换。

QRangeModelAdapter books(QList<Book>{
    // ~~~
});
Book firstBook = books.at(0);
Book newBook = {};
books.at(0) = newBook; // dataChanged() emitted

向包装器赋值即可修改列表中的数据。模型将为所有角色发出dataChanged()方法。

在使用可变重载时，您还可以通过重载的箭头运算符访问项类型的 const 成员。

QString title = books.at(0)->title();

无法访问项的非 const 成员。此类修改将绕过适配器，导致适配器无法将更改通知给模型。若要修改模型中存储的值，请先创建一份副本，修改副本的属性，然后将该副本写回模型。

// books.at(0)->setRating(5); - not possible even though 'books' is not const
firstBook = books.at(0);
firstBook.setRating(5);
books.at(0) = firstBook; // dataChanged() emitted

这将促使模型针对该项以及所有角色触发dataChanged()方法。

如果范围以表格形式表示，则可以使用at(row, column)重载方法，通过行和列来访问单个项。对于树结构，该重载方法可访问顶级项，而at(path, column)重载方法则可访问树中嵌套的项。

访问表或树中的单个项，相当于访问列表中的项。

QRangeModelAdapter table(std::vector<std::vector<double>>{
    {1.0, 2.0, 3.0, 4.0, 5.0},
    {6.0, 7.0, 8.0, 9.0, 10.0},
});
tableView.setModel(table.model());

double value = table.at(0, 2); // value == 3.0
table.at(0, 2) = value * 2; // table[0, 2] == 6.0

如果范围中各列未采用相同的数据类型，则at(row,column) 将返回一个包含该项的QVariant （或其引用包装器）。

QRangeModelAdapter table(std::vector<std::tuple<int, QString>>{
    // ~~~
});
int number = table.at(0, 0)->toInt();
QString text = table.at(0, 1)->toString();

访问表和树中的行

对于表格和树，at() 的重载以及不带列参数的下标operator[]()，均可访问整行数据。 const 重载返回的值将是一个引用类型，可用于访问该行数据。如果该行包含指针，则该引用类型将作为该行的视图，提供对 const 项指针的访问权限。

表行访问

at(int) 重载仍可用，但它返回整个表行。这使得可以一次性处理行中的所有值。

const auto &constTable = table;
const std::vector<double> &topRow = constTable.at(0);

与项（item）类似，const 重载可直接访问行类型，而可变重载则返回一个作为行引用使用的包装器。该包装器允许通过重载的箭头运算符访问 const 成员函数。若要修改值，请将修改后的行类型写回原处。

auto lastRow = table.at(table.rowCount() - 1);
lastRow = { 6.5, 7.5, 8.0, 9.0, 10 }; // emits dataChanged() for entire row

当为行赋予新值时，模型会针对该行中的所有项以及所有角色发出dataChanged()信号。

注意：当 使用具有运行时大小的行类型（例如std::vector 或QList ）时， 请确保新行的尺寸正确。

树行访问

树中的行由一组整数序列指定，树中的每一层对应一个条目。请注意，在下面的代码片段中，Tree 是一个包含原始行指针的范围，且适配器是通过该范围的右值引用创建的。这使得 `QRangeModel ` 拥有对行数据的所有权。

QRangeModelAdapter tree = QRangeModelAdapter(Tree{
    new TreeRow{"Germany", 357002, Tree{
            new TreeRow("Bavaria", 70550)
        },
    },
    new TreeRow{"France", 632702},
});
treeView.setModel(tree.model());

auto germanyData = tree.at(0);
auto bavariaData = tree.at({0, 0});

at() 的重载版本接受单个行值，用于访问顶级行或顶级行中的项。

auto germanyName = tree.at(0, 0);
auto bavariaSize = tree.at({0, 0}, 1);

访问树中行和项的基本模式与访问表中行和项完全相同。不过，在修改整行时，适配器会确保树结构得以保留。

// deletes the old row - tree was moved in
tree.at({0, 0}) = new TreeRow{"Berlin", 892};

在此示例中，创建了一个新的行对象，并将其赋值给第一个顶级项的第一个子项。

迭代器 API

使用 begin() 和 end() 获取模型中各行的迭代器，或使用 ranged-for。如果范围是一个项目列表，解引用迭代器即可访问项目数据。

for(const auto &book: std::as_const(books)) {
    qDebug() << "The book" << book.title()
            << "作者：" <<book.author()
             << "评分：" <<book.rating()<< "星";
}

与 `at()` 的 const 和 mutable 重载类似，可变迭代器解引用后将指向一个包装器。

for(autobook : books) {
    qDebug() << "The book" << book->title()
            < < "作者："<< book->author()
             << "评分：" << book->rating()<< "星";

    Book copy=book;
    copy.setRating(copy.rating()+ 1);
    book=copy;
}

使用重载的箭头运算符访问项类型的 const 成员，并将其赋值给包装器以替换该值。

如果范围是一个表或树，那么遍历模型即可访问各行。

QRangeModelAdapter table(std::vector<std::pair<int,QString>>{
    // ~~~
});

for(const auto &row: std::as_const(table)) {
    qDebug() << "Number is" << row->first << "and string is" << row->second;
}

无论是常量迭代器还是可变迭代器，解引用后都会指向该行的包装类型。这确保了即使底层行类型不是范围（例如，它可能是元组或小工具），我们也能一致地遍历行中的每个项。

for(const auto &row: std::as_const(table)) {
    for(const auto &item: row) {
        qDebug() << item; // item is a QVariant
    }
}

在遍历可变表时，我们可以覆盖整行数据。

for(autorow : table) {
    qDebug() << "Number is" << row->first << "and string is" << row->second;
    row=std::make_pair(42,u"forty-two"_s);
}

该模型会针对所有行中的所有项以及所有角色，发出dataChanged()信号。

for (auto row : table) {
    for (auto item : row) {
        item = 42;
    }
}

通过遍历可变行，我们可以修改单个项目。

在遍历树时，行包装器还提供了两个额外的成员函数：hasChildren() 和 children()，它们允许我们使用迭代器遍历整个树。

for (auto row : tree) {
    if (row.hasChildren()) {
        for (auto child : row.children()) {
            // ~~~
        }
    }
}

children() 返回的对象是一个 QRangeModelAdapter，它操作的模型与被调用者相同，但所有操作都会将源行索引作为父索引。

另请参阅 QRangeModel 。

成员类型文档

[alias] QRangeModelAdapter::range_type

成员函数文档

[implicit] QRangeModelAdapter::QRangeModelAdapter(Range &&range)

[implicit] QRangeModelAdapter::QRangeModelAdapter(Range &&range, Protocol &&protocol)

构建一个在range 上运行的QRangeModelAdapter 。对于树范围，将使用可选的protocol 进行树遍历。

有关Range 的详细要求，以及range 的值类别如何影响适配器、模型和范围之间的交互，请参阅QRangeModel 构造函数的文档。

另请参阅 QRangeModel 。

template < typename InputIterator, typename Sentinel, typename I > requires if_writable<I> void QRangeModelAdapter::assign(InputIterator first, Sentinel last)

将模型中的内容替换为范围 [first,last) 内的行。

另请参阅 range()、at 以及model()。

template <typename I> requires if_tree<I> && if_writable<I> auto QRangeModelAdapter::at(QSpan<const int> path)

template <typename I> requires if_tree<I> && if_writable<I> auto QRangeModelAdapter::operator[](QSpan<const int> path)

返回一个mutable wrapper ，其中包含对path 指定的树行引用。

要修改树行，请为其赋值。 赋值新的树行会将新树行的父节点设置为旧树行的父节点。但是，旧树行和新树行均不得包含任何子行。要访问该树行，请使用operator*() 解引用包装器，或使用operator->() 访问树行成员。

注意： 对范围的修改 将导致包装器失效。

约束

仅当Range 是树时，才参与重载解析。

template <typename I> requires if_list<I> && if_writable<I> auto QRangeModelAdapter::at(int listRow)

template <typename I> requires if_list<I> && if_writable<I> auto QRangeModelAdapter::operator[](int listRow)

将mutable reference 的值设置为Range 中存储的值。

注意： 对该范围的修改 将导致该引用失效。若要修改该引用，请为其赋值一个新值。除非Range 中存储的值是一个指针，否则无法访问存储值的各个成员。

约束

仅当Range 是可变列表时，才参与重载解析。

template <typename I> requires if_table<I> && if_writable<I> auto QRangeModelAdapter::at(int tableRow)

template <typename I> requires if_table<I> && if_writable<I> auto QRangeModelAdapter::operator[](int tableRow)

返回位于tableRow 处的行对应的reference wrapper ，该数据存储在Range 中。

约束

仅当 `Range ` 是可变表（而非树）时，才参与重载解析。

template <typename I> requires if_tree<I> && if_writable<I> auto QRangeModelAdapter::at(int treeRow)

template <typename I> requires if_tree<I> && if_writable<I> auto QRangeModelAdapter::operator[](int treeRow)

返回位于treeRow 处的行对应的reference wrapper ，该行存储在Range 中。

要修改树行，请为其赋值。 赋值新的树行会将新树行的父行设置为旧树行的父行。但是，旧树行和新树行均不得包含任何子行。要访问该树行，请使用operator*() 对包装器进行解引用，或使用operator->() 访问树行成员。

注意： 对范围的修改 将使包装器失效。

约束

仅当Range 是树时，才参与重载解析。

template <typename I> requires if_tree<I> decltype(auto) QRangeModelAdapter::at(QSpan<const int> path) const

template <typename I> requires if_tree<I> decltype(auto) QRangeModelAdapter::operator[](QSpan<const int> path) const

返回对由path 指定的行（该行存储在Range 中）的常量引用。

约束

仅当Range 为树时，才参与重载解析。

template <typename I> requires if_list<I> auto QRangeModelAdapter::at(int listRow) const

template <typename I> requires if_list<I> auto QRangeModelAdapter::operator[](int listRow) const

返回位于listRow 处的值，并将其作为存储在Range 中的类型返回。

约束

仅当Range 为列表时，才参与重载解析。

template <typename I> requires unless_list<I> decltype(auto) QRangeModelAdapter::at(int tableRow) const

template <typename I> requires unless_list<I> decltype(auto) QRangeModelAdapter::operator[](int tableRow) const

返回指向tableRow 处行（如Range 中所存储）的常量引用。

约束

仅当Range 是表或树时，才参与重载解析。

template <typename I> requires if_tree<I> && if_writable<I> auto QRangeModelAdapter::at(QSpan<const int> path, int column)

返回一个mutable reference ，其值为由path 和column 指定的项所存储的值。如果该项是多角色项，则此返回值将指向整个项。如果Range 中的各行在不同列中存储了不同类型的数据，则返回类型将为QVariant 。

注意： 对该范围的修改 将使该引用失效。若要修改该引用，请为其赋值。除非存储在Range 中的值是一个指针，否则无法访问该存储值的单个成员。

约束

仅当Range 是可变树时，才参与重载解析。

template <typename I> requires unless_list<I> && if_writable<I> auto QRangeModelAdapter::at(int tableRow, int column)

将mutable reference 转换为由tableRow 和column 指定的项所存储的值。如果该项是多角色项，则此引用将指向整个项。

注意： 对该范围的修改 将使该引用失效。若要修改该引用，请为其赋值一个新值。除非Range 中存储的值是一个指针，否则无法访问存储值的各个成员。

约束

仅当 `Range ` 是可变表时，才参与重载解析。

template <typename I> requires if_tree<I> auto QRangeModelAdapter::at(QSpan<const int> path, int column) const

返回由path 和column 指定的项所存储值的副本。如果该项是多角色项，则返回该项的完整副本。如果Range 中的各行在不同列中存储不同类型的数据，则返回类型将为QVariant 。

约束

仅当Range 是一个树时，才参与重载解析。

template <typename I> requires unless_list<I> auto QRangeModelAdapter::at(int tableRow, int column) const

返回由tableRow 和column 指定的项所存储值的副本。如果该项是多角色项，则返回整个项的副本。如果Range 中的各行在不同列中存储不同类型的数据，则返回类型将为QVariant 。

约束

仅当Range 是表或树时，才参与重载解析。

[since 6.12] template <typename I> requires if_writable<I> auto QRangeModelAdapter::at(const QModelIndex &index)

返回一个mutable reference ，其值为存储在index 处的项。如果该项是多角色项，则此返回值将指向整个项。如果Range 中的各行在不同列中存储不同类型的数据，则返回类型将为QVariant 。

注意： 对该范围的修改 将使该引用失效。若要修改该引用，请为其赋值一个新值。除非存储在Range 中的值是一个指针，否则无法访问该存储值的单个成员。

约束

仅当 `Range ` 不是只读时，才参与重载解析。

这是一个重载函数。

该函数于 Qt 6.12 中引入。

[since 6.12] auto QRangeModelAdapter::at(const QModelIndex &index) const

返回存储在index 处的项的值的一份副本。如果该项是多角色项，则返回该项的完整副本。如果Range 中的各行在不同列中存储不同类型的数据，则返回类型将为QVariant 。

这是一个重载函数。

该函数在 Qt 6.12 中引入。

int QRangeModelAdapter::columnCount() const

返回列的数量。如果Range 表示一个列表，则返回值为1；否则，返回值即为每行中的元素个数。

template <typename I> requires if_list<I> QVariant QRangeModelAdapter::data(int listRow) const

template <typename I> requires if_list<I> QVariant QRangeModelAdapter::data(int listRow, int role) const

返回一个QVariant ，其中包含存储在给定role 下的、位于listRow 的项的数据；如果不存在该项，则返回一个无效的QVariant 。如果未指定role ，则返回一个QVariant ，其中包含完整的项。

约束

仅当Range 为列表时，才参与重载解析。

另请参阅 setData() 和at()。

template <typename I> requires if_tree<I> QVariant QRangeModelAdapter::data(QSpan<const int> path, int column) const

template <typename I> requires if_tree<I> QVariant QRangeModelAdapter::data(QSpan<const int> path, int column, int role) const

返回一个QVariant ，其中包含存储在给定role 下的、由path 和column 所指代的项的数据；如果该位置或角色下没有存储的数据，则返回一个无效的QVariant 。如果未指定role ，则返回一个QVariant ，其中包含该项的完整数据。

约束

仅当Range 为树时，才参与重载解析。

另请参阅 setData() 和at()。

template <typename I> requires unless_list<I> QVariant QRangeModelAdapter::data(int tableRow, int column) const

template <typename I> requires unless_list<I> QVariant QRangeModelAdapter::data(int tableRow, int column, int role) const

返回一个QVariant ，其中包含在给定的role 下存储的、由tableRow 和column 所指代的项的数据；如果该位置或角色下没有存储的数据，则返回一个无效的QVariant 。如果未指定role ，则返回一个QVariant ，其中包含该项的完整数据。

约束

仅当Range 是表或树时，才参与重载解析。

另请参阅 setData() 和at()。

[since 6.12] QVariant QRangeModelAdapter::data(const QModelIndex &index) const

[since 6.12] QVariant QRangeModelAdapter::data(const QModelIndex &index, int role) const

返回一个QVariant ，其中包含位于index 处的项目在role 下存储的数据；如果该位置或角色下没有存储数据，则返回一个无效的QVariant 。如果未指定role ，则返回一个QVariant ，其中包含该项目的完整内容。

这些函数在 Qt 6.12 中引入。

另请参阅 setData() 和at()。

[constexpr] template <typename I> requires if_tree<I> bool QRangeModelAdapter::hasChildren(QSpan<const int> row) const

[constexpr] template <typename I> requires if_tree<I> bool QRangeModelAdapter::hasChildren(int row) const

返回row 下是否存在任何行。

约束

仅当 `Range ` 是一个树时，才参与重载解析。

[constexpr, since 6.12] template <typename I> requires if_tree<I> bool QRangeModelAdapter::hasChildren(const QModelIndex &index) const

返回index 下是否存在任何行。

约束

仅当 `Range ` 是一个树时，才参与重载解析。

这是一个重载函数。

该函数在 Qt 6.12 中引入。

template <typename I> requires if_list<I> QModelIndex QRangeModelAdapter::index(int listRow) const

返回listRow 的QModelIndex 。

约束

仅当 `Range ` 是一维列表时，才参与重载解析。

这是一个重载函数。

template <typename I> requires if_tree<I> QModelIndex QRangeModelAdapter::index(QSpan<const int> path, int column) const

返回由path 指定的树中某行中，位于column 处的项的QModelIndex 。

约束

仅当 `Range ` 是树时，才参与重载解析。

这是一个重载函数。

template <typename I> requires unless_list<I> QModelIndex QRangeModelAdapter::index(int tableRow, int column) const

返回位于tableRow 、column 处的项目的QModelIndex 。

约束

仅当Range 是表或树时，才参与重载解析。

这是一个重载函数。

template <typename I> requires if_canInsertColumns<I> bool QRangeModelAdapter::insertColumn(int before)

在所有行中，于由 `before ` 指定的列之前插入一列空列，并返回插入是否成功。如果 `before ` 与 `columnCount()` 的返回值相同，则该列将被追加到每行之后。

约束

仅当Range 包含支持插入元素的行时，才参与重载解析。

这是一个重载函数。

另请参阅 removeColumn()、insertColumns(), 以及insertRow()。

template <typename D, typename I> requires if_canInsertColumns<I> && if_compatible_column_data<D> bool QRangeModelAdapter::insertColumn(int before, D &&data)

将由data 构成的单列插入到所有行中，位置在before 指定的列之前，并返回插入是否成功。如果before 与columnCount()的值相同，则该列将被追加到每一行末尾。

如果 `data ` 是单个值，则所有行中的新条目将根据该单个值构建。

如果data 是容器，则该容器中的元素将按顺序用于构建后续每一行的该列。如果data 中的元素数量少于行数，则函数将循环返回并从第一个元素开始重新处理。

约束条件

仅当Range 的行支持元素插入，且这些元素可由data 中的条目构建时，该函数才参与重载解析。

这是一个重载函数。

另请参阅 removeColumn()、insertColumns() 和insertRow()。

template <typename C, typename I> requires if_canInsertColumns<I> && if_compatible_column_range<C> bool QRangeModelAdapter::insertColumns(int before, C &&data)

将由data 中的元素构成的列插入到所有行中，位置在before 指定的列之前，并返回插入是否成功。如果before 与columnCount()的值相同，则该列将被追加到每一行中。

如果data 中的元素是值，则所有行中的新条目将根据这些值构建。

如果data 中的元素是值，则将使用这些值依次构建后续每一行的新条目。如果data 中的元素数量少于行数，则该函数会循环利用这些元素，并从第一个元素开始重新处理。

约束条件

仅当 `Range ` 包含支持插入元素的行，且这些元素能够根据 `data` 中的条目构建时，该函数才参与重载解析。

另请参阅 removeColumns()、insertColumn() 和insertRows()。

template <typename I> requires if_canInsertRows<I> && if_tree<I> bool QRangeModelAdapter::insertRow(QSpan<const int> before)

在由before 指定的路径下的行之前插入一行空行，并返回插入是否成功。如果before 的值与rowCount()的值相同，则新行将被追加。

约束

仅当Range 是一个支持插入元素的树时，才参与重载解析。

这是一个重载函数。

另请参阅 insertRows()、removeRow() 和insertColumn()。

template <typename I> requires if_canInsertRows<I> bool QRangeModelAdapter::insertRow(int before)

在before 处的行之前插入一行空行，并返回插入是否成功。如果before 的值与rowCount()的值相同，则新行将被追加。

约束

仅当Range 支持元素插入时，才参与重载解析。

这是一个重载函数。

另请参阅 insertRows()、removeRow() 和insertColumn()。

template <typename D, typename I> requires if_canInsertRows<I> && if_compatible_row<D> && if_tree<I> bool QRangeModelAdapter::insertRow(QSpan<const int> before, D &&data)

将由data 构建的单行插入到before 所在行的前面，并返回插入是否成功。如果before 的值与rowCount()的值相同，则新行将被追加。

约束

仅当Range 是一个支持插入元素的树，且能够从data 构建一行时，才参与重载解析。

这是一个重载函数。

另请参阅 insertRows()、removeRow() 和insertColumn()。

template <typename D, typename I> requires if_canInsertRows<I> && if_compatible_row<D> bool QRangeModelAdapter::insertRow(int before, D &&data)

将由data 生成的单行插入到before 所在行之前，并返回插入是否成功。如果before 与rowCount()的值相同，则新行将被追加。

约束

仅当Range 支持元素插入，且可以从data 构建一行时，才参与重载解析。

这是一个重载函数。

另请参阅 insertRows()、removeRow() 和insertColumn()。

template <typename I> requires if_canInsertRows<I> && if_tree<I> bool QRangeModelAdapter::insertRow(int before, const QModelIndex &parent)

在指定parent 中，于before 所在行之前插入一行空行，并返回插入是否成功。如果before 的值与rowCount()的值相同，则新行将被追加。

约束

仅当Range 是一个支持元素插入的树时，才参与重载解析。

这是一个重载函数。

另请参阅 insertRows()、removeRow() 以及insertColumn()。

template <typename D, typename I> requires if_canInsertRows<I> && if_compatible_row<D> && if_tree<I> bool QRangeModelAdapter::insertRow(int before, const QModelIndex &parent, D &&data)

在指定的parent 中，将由data 构建的单行插入到before 所在行的前面，并返回插入是否成功。如果before 与rowCount()的值相同，则新行将被追加。

约束

仅当Range 是一个支持元素插入的树，且能够从data 构建出一行时，才参与重载解析。

这是一个重载函数。

另请参阅 insertRows()、removeRow() 和insertColumn()。

template <typename C, typename I> requires if_canInsertRows<I> && if_compatible_row_range<C> && if_tree<I> bool QRangeModelAdapter::insertRows(QSpan<const int> before, C &&data)

将由data 中的元素构成的行插入到before 所在行之前，并返回插入是否成功。如果before 的值与rowCount()的值相同，则新行将被追加。

约束

仅当Range 是一个支持插入元素的树，且可以从data 中的元素构建行时，该函数才会参与重载解析。

这是一个重载函数。

另请参阅 insertRow()、removeRows() 和insertColumns()。

template <typename C, typename I> requires if_canInsertRows<I> && if_compatible_row_range<C> bool QRangeModelAdapter::insertRows(int before, C &&data)

将由data 中的元素构成的行插入到before 所在行之前，并返回插入是否成功。如果before 与rowCount()的值相同，则新行将被追加。

约束

仅当Range 支持元素插入，且能够根据data 中的元素构建行时，该函数才会参与重载解析。

这是一个重载函数。

另请参阅 insertRow()、removeRows() 和insertColumns()。

template <typename C, typename I> requires if_canInsertRows<I> && if_compatible_row_range<C> && if_tree<I> bool QRangeModelAdapter::insertRows(int before, const QModelIndex &parent, C &&data)

将由data 中的元素构成的行插入到指定parent 中before 行之前，并返回插入是否成功。如果before 的值与rowCount()的值相同，则新行将被追加。

约束

仅当Range 是一个支持插入元素的树，且可以从data 中的元素构建行时，才参与重载解析。

这是一个重载函数。

另请参见 insertRow()、removeRows() 和insertColumns()。

Model *QRangeModelAdapter::model() const

返回由该适配器创建的QRangeModel 实例。

另请参阅 range() 和at()。

template <typename F> requires if_canMoveItems<F> bool QRangeModelAdapter::moveColumn(int from, int to)

将位于from 的列移动到to 的位置，并返回列是否已成功移动。

约束

仅当Range 包含支持元素移动的行时，才参与重载解析。

另请参阅 insertColumn()、removeColumn()、moveColumns() 和moveRow()。

template <typename F> requires if_canMoveItems<F> bool QRangeModelAdapter::moveColumns(int from, int count, int to)

将从from 开始的count 列移动到to 的位置，并返回列是否已成功移动。

约束

仅当Range 包含支持元素移动的行时，才参与重载解析。

另请参阅 insertColumns()、removeColumns()、moveColumn() 以及moveRows()。

template <typename I, typename F> requires if_canMoveItems<F> && if_tree<I> bool QRangeModelAdapter::moveRow(QSpan<const int> source, QSpan<const int> destination)

将位于source 的树枝移动到destination 的位置，并返回树枝是否已成功移动。

约束条件

仅当Range 是支持移动元素的树时，才参与重载解析。

这是一个重载函数。

另请参见 insertRow()、removeRow() 和moveColumn()。

template <typename F> requires if_canMoveItems<F> bool QRangeModelAdapter::moveRow(int source, int destination)

将位于source 的行移动到destination 的位置，并返回该行是否已成功移动。

约束

仅当Range 支持元素移动时，才参与重载解析。

这是一个重载函数。

另请参阅 insertRow()、removeRow() 和moveColumn()。

template <typename I, typename F> requires if_canMoveItems<F> && if_tree<I> bool QRangeModelAdapter::moveRow(const QModelIndex &sourceParent, int sourceRow, const QModelIndex &destinationParent, int destinationChild)

将位于sourceRow 的分支从sourceParent 移动到destinationParent 中的destinationChild 位置，并返回分支是否已成功移动。

约束条件

仅当Range 是一个支持元素移动的树时，才参与重载解析。

这是一个重载函数。

另请参见 insertRow()、removeRow() 和moveColumn()。

template <typename I, typename F> requires if_canMoveItems<F> && if_tree<I> bool QRangeModelAdapter::moveRows(QSpan<const int> source, int count, QSpan<const int> destination)

将count 中从source 开始的树分支移动到destination 的位置，并返回行是否已成功移动。

约束

仅当Range 是一个支持移动元素的树时，才参与重载解析。

这是一个重载函数。

另请参阅 insertRows()、removeRows() 和moveColumns()。

template <typename F> requires if_canMoveItems<F> bool QRangeModelAdapter::moveRows(int source, int count, int destination)

将从source 开始的count 行移动到destination 位置，并返回行是否已成功移动。

约束

仅当Range 支持元素移动时，才参与重载解析。

这是一个重载函数。

另请参阅 insertRows()、removeRows() 和moveColumns()。

template <typename I, typename F> requires if_canMoveItems<F> && if_tree<I> bool QRangeModelAdapter::moveRows(const QModelIndex &sourceParent, int sourceRow, int count, const QModelIndex &destinationParent, int destinationChild)

将从sourceRow 开始的count 分支从sourceParent 移动到destinationParent 中的destinationChild 位置，并返回分支是否已成功移动。

约束条件

仅当Range 是一个支持元素移动的树时，该函数才参与重载解析。

这是一个重载函数。

另请参见 insertRows()、removeRows() 和moveColumns()。

const QRangeModelAdapter<Range, Protocol, Model>::range_type &QRangeModelAdapter::range() const

返回模型适配器所操作的范围的一个 const 引用。

另请参阅 assign()、at() 以及model()。

template <typename I> requires if_canRemoveColumns<I> bool QRangeModelAdapter::removeColumn(int column)

从每一行中移除指定的column ，并返回移除是否成功。

约束

仅当Range 的各行支持元素删除时，才参与重载解析。

另请参阅 insertColumn()、removeColumns() 和removeRow()。

template <typename I> requires if_canRemoveColumns<I> bool QRangeModelAdapter::removeColumns(int column, int count)

从每一行中删除以给定column 开头的count 列，并返回删除是否成功。

约束

仅当Range 的行支持元素删除时，才参与重载解析。

另请参阅 insertColumns()、removeColumn() 和removeRow()。

template <typename I> requires if_canRemoveRows<I> && if_tree<I> bool QRangeModelAdapter::removeRow(QSpan<const int> path)

删除位于指定坐标path 处的行（包括该行的所有子节点），并返回删除是否成功。

约束条件

仅当Range 是一个支持删除元素的树时，才参与重载解析。

这是一个重载函数。

另请参阅 removeRows()、removeColumn() 和insertRow()。

template <typename I> requires if_canRemoveRows<I> bool QRangeModelAdapter::removeRow(int row)

移除指定的row ，并返回移除是否成功。

约束

仅当Range 支持移除元素时，才参与重载解析。

这是一个重载函数。

另请参阅 removeRows()、removeColumn() 和insertRow()。

template <typename I> requires if_canRemoveRows<I> && if_tree<I> bool QRangeModelAdapter::removeRow(int row, const QModelIndex &parent)

从parent 中删除指定的row （包括该行下的所有子节点），并返回删除是否成功。

约束

仅当Range 是一个支持删除元素的树时，才参与重载解析。

这是一个重载函数。

另请参见 removeRows()、removeColumn() 和insertRow()。

template <typename I> requires if_canRemoveRows<I> && if_tree<I> bool QRangeModelAdapter::removeRows(QSpan<const int> path, int count)

删除从path 指定的行开始的count 行，并返回删除是否成功。

约束

仅当 `Range ` 是一个支持删除元素的树时，才参与重载解析。

这是一个重载函数。

另请参见 removeRow()、removeColumns() 和insertRows()。

template <typename I> requires if_canRemoveRows<I> bool QRangeModelAdapter::removeRows(int row, int count)

删除从row 开始的count 行，并返回删除是否成功。

约束

仅当Range 支持删除元素时，才参与重载解析。

这是一个重载函数。

另请参见 removeRow()、removeColumns() 和insertRows()。

template <typename I> requires if_canRemoveRows<I> && if_tree<I> bool QRangeModelAdapter::removeRows(int row, int count, const QModelIndex &parent)

从parent 中删除以指定row 为起点的count 行，并返回删除是否成功。

约束

仅当Range 是一个支持删除元素的树时，才参与重载解析。

这是一个重载函数。

另请参阅 removeRow()、removeColumns() 和insertRows()。

int QRangeModelAdapter::rowCount() const

返回行数。如果Range 表示列表或表，则返回行数。对于树，返回顶级行数。

这是一个重载函数。

template <typename I> requires if_tree<I> int QRangeModelAdapter::rowCount(QSpan<const int> row) const

template <typename I> requires if_tree<I> int QRangeModelAdapter::rowCount(int row) const

返回row 下的行数。

约束

仅当 `Range ` 是一个树时，才参与重载解析。

[since 6.12] template <typename I> requires if_tree<I> int QRangeModelAdapter::rowCount(const QModelIndex &index) const

返回index 下的行数。

约束

仅当 `Range ` 是一个树时，才参与重载解析。

这是一个重载函数。

该函数在 Qt 6.12 中引入。

template <typename I> requires if_list<I> && if_writable<I> bool QRangeModelAdapter::setData(int listRow, const QVariant &value, int role = Qt::EditRole)

将listRow 处项的role 数据设置为value 。

若操作成功，则返回true ；否则返回false 。

约束

仅当Range 是可变列表时，才参与重载解析。

另请参阅 data() 和at()。

template <typename I> requires if_tree<I> && if_writable<I> bool QRangeModelAdapter::setData(QSpan<const int> path, int column, const QVariant &value, int role = Qt::EditRole)

将path 和column 所引用的项的role 数据设置为value 。

若操作成功，则返回true ；否则返回false 。

约束

仅当Range 是可变树时，才参与重载解析。

另请参阅 data() 和at()。

template <typename I> requires unless_list<I> && if_writable<I> bool QRangeModelAdapter::setData(int tableRow, int column, const QVariant &value, int role = Qt::EditRole)

将tableRow 和column 所引用的项的role 数据设置为value 。

若操作成功，则返回true ；否则返回false 。

约束

仅当Range 是可变的且不是列表时，才参与重载解析。

另请参阅 data() 和at()。

[since 6.12] template <typename I> requires if_writable<I> bool QRangeModelAdapter::setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole)

将index 处的项目数据role 设置为value 。

若操作成功，则返回true ；否则返回false 。

约束

仅当Range 不是只读时，才参与重载解析。

这是一个重载函数。

该函数在 Qt 6.12 中引入。

另请参见 data() 和at()。

template <typename NewRange = QRangeModelAdapter<Range, Protocol, Model>::range_type> requires if_assignable_range<NewRange> && unless_adapter<NewRange> QRangeModelAdapter<Range, Protocol, Model> &QRangeModelAdapter::operator=(NewRange &&newRange)

template <typename NewRange = QRangeModelAdapter<Range, Protocol, Model>::range_type> requires if_assignable_range<NewRange> void QRangeModelAdapter::assign(NewRange &&newRange)

将模型的内容替换为newRange 中的行，此过程可能会使用移动语义。

该函数使model()发出modelAboutToBeReset()和modelReset()信号。

约束

仅当Range 是可变的，且newRange 的类型可以赋值给Range （但不能是QRangeModelAdapter ）时，才参与重载解析。

另请参阅 range()、at()、model() 和assign()。

template <typename Row> requires if_assignable_range<std::initializer_list<Row>> QRangeModelAdapter<Range, Protocol, Model> &QRangeModelAdapter::operator=(std::initializer_list<Row> newRange)

template <typename Row> requires if_assignable_range<std::initializer_list<Row>> void QRangeModelAdapter::assign(std::initializer_list<Row> newRange)

用newRange 中的行替换模型的内容。

约束

仅当Range 是可变的，且newRange 可被赋值给Range 时，才参与重载解析。

另请参阅 range()、at 和model()。

相关的非成员

[noexcept] bool operator!=(const QRangeModelAdapter<Range, Protocol, Model> &lhs, const QRangeModelAdapter<Range, Protocol, Model> &rhs)

返回lhs 是否与rhs 不相同。如果两个适配器都持有相同的model 实例，则它们相等。

[noexcept] bool operator==(const QRangeModelAdapter<Range, Protocol, Model> &lhs, const QRangeModelAdapter<Range, Protocol, Model> &rhs)

返回lhs 是否等于rhs 。如果两个适配器都持有相同的model 实例，则它们相等。

© 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.