Back to Qt.io
Contact Us Blog Download Qt

QSignalMapper Class

QSignalMapper 类可捆绑来自可识别发送方的信号。更多

头文件： #include <QSignalMapper>
CMake： find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake： QT += core
继承： QObject

公共函数

QSignalMapper(QObject *parent = nullptr)
virtual ~QSignalMapper()
QObject *mapping(int id) const
QObject *mapping(QObject *object) const
QObject *mapping(const QString &id) const
void removeMappings(QObject *sender)
void setMapping(QObject *sender, QObject *object)
void setMapping(QObject *sender, const QString &text)
void setMapping(QObject *sender, int id)

公共插槽

void map()
void map(QObject *sender)

信号

void mappedInt(int i)
void mappedObject(QObject *object)
void mappedString(const QString &text)

详细说明

该类收集一组无参数信号，并在发送信号的对象中加入整数、字符串或 widget 参数后重新发送。请注意，在大多数情况下，您可以使用 lambdas 向槽传递自定义参数。这不仅成本较低，还能简化代码。

该类支持使用setMapping() 将特定字符串、整数、对象和部件与特定对象进行映射。然后，对象的信号可以连接到map() 槽，该槽将发出一个信号（可以是mappedInt(),mappedString() 和mappedObject() ），其值与原始信号对象相关联。以后可以使用removeMappings() 删除映射。

示例假设我们要创建一个包含一组按钮（如工具调色板）的自定义 widget。一种方法是将每个按钮的clicked() 信号连接到各自的自定义插槽；但在本例中，我们希望将所有按钮连接到一个插槽，并根据被点击的按钮对插槽进行参数化。

下面是一个简单自定义 widget 的定义，该 widget 只有一个信号clicked() ，该信号将与被点击按钮的文本一起发出：

class ButtonWidget : public QWidget
{
    Q_OBJECT

public:
    ButtonWidget(const QStringList &texts, QWidget *parent = nullptr);

signals:
    void clicked(const QString &text);

private:
    QSignalMapper *signalMapper;
};

我们需要实现的唯一函数就是构造函数：

ButtonWidget::ButtonWidget(const QStringList &texts, QWidget *parent)
    : QWidget(parent)
{
    signalMapper = new QSignalMapper(this);

    QGridLayout *gridLayout = new QGridLayout(this);
    for (int i = 0; i < texts.size(); ++i) {
        QPushButton *button = new QPushButton(texts[i]);
        connect(button, &QPushButton::clicked, signalMapper, qOverload<>(&QSignalMapper::map));
        signalMapper->setMapping(button, texts[i]);
        gridLayout->addWidget(button, i / 3, i % 3);
    }

    connect(signalMapper, &QSignalMapper::mappedString,
            this, &ButtonWidget::clicked);
}

一个文本列表被传递给构造函数。我们将构建一个信号映射器，并为列表中的每个文本创建一个QPushButton 。我们将每个按钮的clicked() 信号连接到信号映射器的map() 槽，并在信号映射器中创建从每个按钮到按钮文本的映射。最后，我们将信号映射器的mappedString() 信号连接到自定义 widget 的clicked() 信号。当用户点击按钮时，自定义 widget 将发出一个clicked() 信号，其参数就是用户点击的按钮文本。

在 lambda 函数可以用作插槽之前，这个类的作用非常大。通过连接 lambda 函数，上面的示例可以在没有 QSignalMapper 的情况下更简单地重写。

ButtonWidget::ButtonWidget(const QStringList &texts, QWidget *parent)
    : QWidget(parent)
{
    QGridLayout *gridLayout = new QGridLayout(this);
    for (int i = 0; i < texts.size(); ++i) {
        QString text = texts[i];
        QPushButton *button = new QPushButton(text);
        connect(button, &QPushButton::clicked, [this, text] { clicked(text); });
        gridLayout->addWidget(button, i / 3, i % 3);
    }
}

另请参见 QObject,QButtonGroup, 和QActionGroup 。

成员函数文档

[explicit] QSignalMapper::QSignalMapper(QObject *parent = nullptr)

构造一个 QSignalMapper，其父级parent 。

[virtual noexcept] QSignalMapper::~QSignalMapper()

摧毁QSignalMapper.

[slot] void QSignalMapper::map()

该槽根据向其发送信号的对象来发射信号。

[slot] void QSignalMapper::map(QObject *sender)

该插槽根据sender 对象发射信号。

[signal] void QSignalMapper::mappedInt(int i)

当一个设置了整数映射的对象发出map() 信号时，就会发出该信号。对象的映射整数在i 中传递。

另请参见 setMapping()。

[signal] void QSignalMapper::mappedObject(QObject *object)

当设置了对象映射的对象发出map() 信号时，就会发出该信号。映射提供的对象在object 中传递。

另请参见 setMapping()。

[signal] void QSignalMapper::mappedString(const QString &text)

当设置了字符串映射的对象发出map() 信号时，就会发出该信号。对象的映射字符串在text 中传递。

另请参见 setMapping()。

QObject *QSignalMapper::mapping(int id) const

返回与id 相关联的发件人QObject 。

另请参阅 setMapping() 。

QObject *QSignalMapper::mapping(QObject *object) const

此函数重载 mapping()。

返回与object 关联的发送方QObject 。

QObject *QSignalMapper::mapping(const QString &id) const

该函数重载了 mapping()。

void QSignalMapper::removeMappings(QObject *sender)

删除sender 的所有映射。

当映射对象被销毁时会自动删除。

注意： 这不会断开任何信号。如果sender 没有销毁，则需要根据需要明确执行此操作。

void QSignalMapper::setMapping(QObject *sender, QObject *object)

添加一个映射，这样当map() 从sender 发送信号时，就会发出mappedObject(object ) 信号。

每个发送方最多只能有一个对象。

另请参阅 mapping() 。

void QSignalMapper::setMapping(QObject *sender, const QString &text)

添加映射，这样当map() 从sender 发送信号时，就会发出mappedString(text ) 信号。

每个发送方最多只能有一个文本。

void QSignalMapper::setMapping(QObject *sender, int id)

添加一个映射，这样当map() 从给定的sender 发送信号时，就会发出mappedInt(id) 信号。

每个发送方最多只能有一个整数 ID。

另请参阅 mapping() 。

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