QML与C++：基于ListView调用外部模型进行增删改查（附自定义组件）

引言

在上一篇中介绍了ListView的数据交互与样式定制后，本文上一点强度，将通过一个联系人管理的案例，详细介绍如何使用QML与C++进行混合开发，充分展示QML的界面设计优势和C++的数据处理能力。该应用基于ListView & Model实现了联系人的增删改查等基本功能，并通过自定义组件提升了用户体验。由于篇幅有限，会省略部分代码，完整代码请看本文最后的下载链接。

下一篇与ListView有关的文章，我将会进一步优化Model的性能。到时候在相关阅读中补上链接。

相关阅读

• 接上篇 —— QML ListView：列表视图的数据交互与样式定制
• 下篇 —— QML与C++：基于ListView调用外部模型进行增删改查（性能优化版）

---

项目结构

以下是本项目的核心结构图：

文件组织

qml_listview_cpp/
├── CMakeLists.txt           # CMake构建配置
├── main.cpp                 # C++主函数
├── datamodel.h              # 数据模型头文件
├── datamodel.cpp            # 数据模型实现
├── Main.qml                 # 主界面QML
├── ContactDialog.qml        # 联系人对话框QML
├── components/              # 自定义组件目录
│   ├── CustomTextField.qml  # 自定义文本输入框
│   ├── CustomButton.qml     # 自定义按钮
│   └── IconButton.qml       # 自定义图标按钮
├── icons/                   # 图标资源目录
│   ├── user.png             # 用户图标
│   ├── add.png              # 添加图标
│   ├── delete.png           # 删除图标
│   ├── edit.png             # 编辑图标
│   ├── find.png             # 搜索图标
│   ├── phone.png            # 电话图标
│   └── clear.png            # 清除图标
└── image.qrc                # Qt资源文件

---

核心技术实现

1. 数据模型设计

本项目采用了QAbstractListModel作为基类创建自定义数据模型，实现了联系人数据的管理。C++的数据模型为QML提供了高效的数据源。

联系人项目类 (datamodel.h)

class ContactItem {
public:ContactItem(const QString &name, const QString &phone): m_name(name), m_phone(phone) {}QString name() const { return m_name; }QString phone() const { return m_phone; }QString firstLetter() const { return m_name.isEmpty() ? "?" : m_name.left(1).toUpper(); }private:QString m_name;QString m_phone;
};

ContactItem类定义了联系人的基本属性：姓名和电话。它还提供了一个便利方法firstLetter()用于获取姓名的首字母，这将用于UI中的头像显示。

数据模型类 (datamodel.h)

class DataModel : public QAbstractListModel
{Q_OBJECTpublic:enum Roles {NameRole = Qt::UserRole + 1,PhoneRole,FirstLetterRole};explicit DataModel(QObject *parent = nullptr);int rowCount(const QModelIndex &parent = QModelIndex()) const override;QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override;QHash<int, QByteArray> roleNames() const override;// 暴露给QML的方法Q_INVOKABLE bool addContact(const QString &name, const QString &phone);Q_INVOKABLE bool removeContact(int index);Q_INVOKABLE bool editContact(int index, const QString &name, const QString &phone);Q_INVOKABLE QVariantList searchContacts(const QString &keyword);Q_INVOKABLE void clearSearch();private:QList<ContactItem> m_items;QList<ContactItem> m_originalItems; // 用于存储搜索前的原始数据
};

DataModel类继承自QAbstractListModel，实现了必要的虚函数：

• rowCount(): 返回模型中的项目数量
• data(): 根据索引和角色返回项目数据
• roleNames(): 定义了模型中可用的角色名称，这些名称将在QML中使用

此外，还通过Q_INVOKABLE宏定义了几个可以从QML中直接调用的方法：

• addContact(): 添加联系人
• removeContact(): 删除联系人
• editContact(): 编辑联系人
• searchContacts(): 搜索联系人
• clearSearch(): 清除搜索，恢复原始列表

数据模型实现 (datamodel.cpp)

数据模型的核心实现如下：

DataModel::DataModel(QObject *parent): QAbstractListModel(parent)
{// 添加一些示例联系人数据m_items.append(ContactItem("张三", "13800138000"));m_items.append(ContactItem("李四", "13900139000"));m_items.append(ContactItem("王五", "13700137000"));// 保存原始数据m_originalItems = m_items;
}QVariant DataModel::data(const QModelIndex &index, int role) const
{if (!index.isValid())return QVariant();if (index.row() >= m_items.count())return QVariant();const ContactItem &item = m_items.at(index.row());switch (role) {case NameRole:return item.name();case PhoneRole:return item.phone();case FirstLetterRole:return item.firstLetter();default:return QVariant();}
}// 搜索联系人实现
QVariantList DataModel::searchContacts(const QString &keyword)
{if (keyword.isEmpty()) {beginResetModel();m_items = m_originalItems;endResetModel();return QVariantList();}QVariantList results;beginResetModel();m_items.clear();for (const ContactItem &item : m_originalItems) {if (item.name().contains(keyword, Qt::CaseInsensitive) ||item.phone().contains(keyword, Qt::CaseInsensitive)) {m_items.append(item);}}endResetModel();return results;
}

2. 主程序入口点 (main.cpp)

主函数设置了QML引擎并将C++数据模型暴露给QML：

#include <QGuiApplication>
#include <QQmlApplicationEngine>
#include <QQmlContext>
#include "datamodel.h"int main(int argc, char *argv[])
{QGuiApplication app(argc, argv);QQmlApplicationEngine engine;QObject::connect(&engine,&QQmlApplicationEngine::objectCreationFailed,&app,[]() { QCoreApplication::exit(-1); },Qt::QueuedConnection);// 创建数据模型实例DataModel *model = new DataModel(&engine);// 将模型暴露给QMLengine.rootContext()->setContextProperty("dataModel", model);engine.loadFromModule("qml_listview_cpp", "Main");return app.exec();
}

通过setContextProperty方法，将C++数据模型注册为QML上下文属性，这样在QML代码中就可以直接访问dataModel对象了。

3. 主界面设计 (Main.qml)

主界面采用了QML编写，实现了联系人的列表显示和搜索功能：

import QtQuick
import QtQuick.Window
import QtQuick.Controls
import QtQuick.Layouts
import "./components"  // 导入自定义组件Window {width: 640height: 480visible: truetitle: "联系人列表"// ... 省略部分代码 ...ColumnLayout {anchors.fill: parentanchors.margins: 10spacing: 10// 顶部工具栏Rectangle {Layout.fillWidth: trueheight: 50color: "#f0f0f0"radius: 5RowLayout {anchors.fill: parentanchors.margins: 5spacing: 10CustomTextField {id: searchFieldLayout.fillWidth: trueplaceholderText: "搜索联系人..."leftIcon: "qrc:/icons/find.png"onTextChanged: dataModel.searchContacts(text)onRightIconClicked: {text = ""dataModel.clearSearch()}}IconButton {text: "添加联系人"iconSource: "qrc:/icons/add.png"showBackground: truebackgroundColor: "#BBDEFB"onClicked: addContactDialog.open()}}}// 联系人列表ListView {Layout.fillWidth: trueLayout.fillHeight: truemodel: dataModelspacing: 10clip: truedelegate: Rectangle {width: ListView.view.widthheight: 80color: "#f0f0f0"radius: 5// ... 省略部分代码 ...RowLayout {anchors.fill: parentanchors.margins: 10spacing: 15// 首字母头像Rectangle {width: 60height: 60radius: width / 2color: {const colors = ["#FF6B6B", "#4ECDC4", "#45B7D1", "#96CEB4", "#FFEEAD", "#D4A5A5", "#9B59B6"]return colors[firstLetter.charCodeAt(0) % colors.length]}Text {anchors.centerIn: parenttext: firstLettercolor: "white"font.pixelSize: 24font.bold: true}}// 联系人信息ColumnLayout {Layout.fillWidth: truespacing: 5Text {text: namefont.bold: truefont.pixelSize: 16Layout.fillWidth: true}Text {text: phonecolor: "#666666"font.pixelSize: 14Layout.fillWidth: true}}// 操作按钮RowLayout {spacing: 10// 编辑按钮IconButton {iconSource: "qrc:/icons/edit.png"onClicked: {currentEditIndex = indexeditContactDialog.currentName = nameeditContactDialog.currentPhone = phoneeditContactDialog.open()}}// 删除按钮IconButton {iconSource: "qrc:/icons/delete.png"onClicked: dataModel.removeContact(index)}}}}}}
}

主界面的核心部分是一个ListView，它使用C++提供的dataModel作为数据源。每个联系人项目都显示为一个带有圆形首字母头像、姓名、电话号码以及编辑和删除按钮的矩形卡片。

主界面效果图：

---

4. 联系人对话框 (ContactDialog.qml)

为了添加和编辑联系人，项目实现了一个模态对话框：

import QtQuick
import QtQuick.Controls
import QtQuick.Layouts
import "./components"Dialog {id: rootwidth: 400modal: true// 属性property bool isEdit: false  // 用于区分是编辑还是添加模式property string currentName: ""property string currentPhone: ""// 标题根据模式动态设置title: isEdit ? "修改联系人" : "添加新联系人"closePolicy: Dialog.NoAutoClose// 信号signal contactConfirmed(string name, string phone)// ... 省略部分代码 ...contentItem: ColumnLayout {spacing: 20anchors.margins: 10CustomTextField {id: nameFieldLayout.fillWidth: trueplaceholderText: "姓名"leftIcon: "qrc:/icons/user.png"}CustomTextField {id: phoneFieldLayout.fillWidth: trueplaceholderText: "电话"leftIcon: "qrc:/icons/phone.png"validator: RegularExpressionValidator {regularExpression: /^[0-9\+\-\s]*$/}}// 按钮区域RowLayout {Layout.alignment: Qt.AlignRight | Qt.AlignBottomspacing: 10CustomButton {id: confirmButtontext: isEdit ? qsTr("保存") : qsTr("确定")enabled: nameField.text.length > 0 && phoneField.text.length > 0onClicked: root.accept()}CustomButton {id: cancelButtontext: qsTr("取消")bgColor: "#f5f5f5"textColor: "#333333"onClicked: root.reject()}}}
} 

这个对话框可以在两种模式下工作：添加新联系人和编辑现有联系人。它包含两个自定义文本输入字段用于输入姓名和电话号码，以及确认和取消按钮。

对话框效果图：

5. 自定义组件

为了提升UI的美观度和复用性，项目定义了几个自定义组件：

CustomTextField.qml

此处代码省略…

这个自定义文本输入框增强了标准的TextField，添加了左侧图标、右侧图标或清除按钮等功能。如果所示：

---

CustomButton.qml

此处代码省略…

自定义按钮组件提供了更灵活的外观定制，包括背景色、文本色以及悬停效果。

主要在对话窗中使用了CustomButton：

---

IconButton.qml

此处代码省略…

图标按钮组件实现了一个可以显示图标和文本的自定义按钮，提供了丰富的自定义选项，如图标大小、边框、背景色等。

在列表中使用了IconButton：

在添加联系人按钮上使用了IconButton：

只需要设置背景色和文字即可实现不同的样式效果。

---

运行效果

查找联系人：

修改联系人：

新增/删除联系人：

---

总结

本文介绍了一个基于Qt/QML与C++混合开发的联系人管理应用。通过这个示例，我们展示了：

1. QML与C++协同工作的模式：QML负责直观高效的UI设计，C++处理数据逻辑和模型。
2. 自定义QML组件的实现：通过组件化设计提高代码复用性和可维护性。
3. QAbstractListModel的使用：通过继承QAbstractListModel创建自定义数据模型。
4. 信号与槽机制：利用Qt的信号与槽机制实现UI与数据模型的解耦。

下载链接

您可以通过以下链接获取完整的源代码：GitCode -> QML -> ListView & Model