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)

详细说明

该类收集了一组无参数信号，并根据发送信号的对象，使用整数、字符串或控件参数重新发出这些信号。请注意，在大多数情况下，您可以使用 lambda 表达式向槽传递自定义参数。这种方式开销较小，且能简化代码。

该类支持使用 `setMapping()` 将特定的字符串、整数、对象和控件与特定对象进行映射。随后，可以将这些对象的信号连接到 `map()` 槽，该槽将发出一个信号（可能是 `mappedInt()`、`mappedString()` 或 `mappedObject()`），并携带与原始信号发送对象关联的值。 映射关系可稍后通过removeMappings()移除。

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

以下是一个简单自定义控件的定义，它有一个名为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() 信号连接到自定义控件的clicked() 信号。当用户点击按钮时，自定义控件将发出一个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)

基于父类parent 构建一个 QSignalMapper。

[virtual noexcept] QSignalMapper::~QSignalMapper()

销毁QSignalMapper 。

[slot] void QSignalMapper::map()

该插槽会根据向其发送信号的对象来发出信号。

注意：此 槽已被重载。要连接到此槽： 

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        signalMapper, qOverload<>(&QSignalMapper::map));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        signalMapper, [receiver = signalMapper]() { receiver->map(); });
有关更多示例和方法，请参阅“连接到重载的槽”。

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

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

注意：此 插槽已被重载。要连接到此插槽： 

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        signalMapper, qOverload(&QSignalMapper::map));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        signalMapper, [receiver = signalMapper](QObject *sender) { receiver->map(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

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

此函数重载了 `QSignalMapper::mapping()` 方法。

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

该函数重载了QSignalMapper::mapping()。

void QSignalMapper::removeMappings(QObject *sender)

删除sender 的所有映射。

当映射对象被销毁时，此操作会自动执行。

注意：此操作 不会断开任何信号。如果sender 未被销毁，则在需要时必须显式执行此操作。

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

添加一个映射，使得当从“sender ”发出map()信号时，会触发mappedObject （object ）信号。

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

另请参阅 mapping()。

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

添加一个映射，使得当从sender 发出map()信号时，会发出mappedString （text ）信号。

每个发送者至多对应一条文本。

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

添加一个映射，使得当从给定的sender 发出map()信号时，会触发mappedInt （id ）信号。

每个发送者至多有一个整数 ID。

另请参阅 mapping()。

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