3. 信号的定义与声明：signals关键字、信号函数签名规则、信号的重载

好，咱们接着聊信号的定义。说实话，很多初学者一上来就被 signals 这个关键字搞懵了——它到底是啥？是函数？是宏？还是某种黑魔法？

其实没那么玄乎。我个人习惯把 signals 理解成一个“标记区”。你想想看，Qt 的 moc（元对象编译器）在预处理阶段会扫描头文件，一旦看到 signals: 这个访问说明符，就知道：哦，下面这些函数声明，我要特殊处理了。

3.1 signals 关键字的本质

signals 在 Qt 5 中其实是一个宏，展开后就是 protected。没错，你没看错——信号函数默认是 protected 访问级别的。这意味着：

你可以在类内部 emit 信号
但外部对象不能直接调用信号函数（只能通过 connect 连接）

核心要点：信号只有声明，没有实现。实现由 moc 自动生成。

嗯，这里要注意：你千万别手痒去给信号写函数体。我见过有人这么干——在 .cpp 文件里给信号函数写了实现，结果编译报错，还跑来问我是不是 Qt 的 bug。其实是你抢了 moc 的活。

3.2 信号函数签名规则

信号函数的签名，说白了就是它的参数列表。规则其实很简单：

返回类型必须是 void——信号不需要返回值，它是广播机制
参数类型必须是 Qt 元类型系统支持的——比如 int、QString、QColor 等
自定义类型需要注册——用 Q_DECLARE_METATYPE 宏

举个例子，一个典型的信号声明长这样：

// 正确的信号声明
signals:
    void valueChanged(int newValue);
    void textUpdated(const QString &text);
    void errorOccurred(int errorCode, const QString &errorMessage);

我在项目中遇到过一个问题：信号参数用了 const char*，结果跨线程传递时数据全乱了。为什么？因为 const char* 不是 Qt 元类型，moc 不会帮你做深拷贝。后来我全改成 QString 或 QByteArray，问题就解决了。

避坑指南：信号参数尽量避免使用指针类型（尤其是裸指针）。跨线程传递时，指针指向的内存可能已经被释放了。

3.3 信号的重载

信号也是函数，所以它支持重载。这在 Qt 中非常常见，比如 QComboBox 的 currentIndexChanged 信号就有两个版本：

// QComboBox 中的信号重载示例
signals:
    void currentIndexChanged(int index);
    void currentIndexChanged(const QString &text);

重载信号的好处很明显：你可以根据需求选择连接哪个版本。比如有的槽函数只需要索引，有的需要文本内容。

但是——这里有个坑。当你用老式 SIGNAL() 宏连接重载信号时，编译器会报歧义错误：

// 这样写会报错！编译器不知道你要连接哪个版本
connect(comboBox, SIGNAL(currentIndexChanged(int)),
        this, SLOT(onIndexChanged(int)));

// 正确做法：使用函数指针显式指定
connect(comboBox, QOverload<int>::of(&QComboBox::currentIndexChanged),
        this, &MyClass::onIndexChanged);

我曾经在一个老项目里看到满屏的 SIGNAL() 宏，后来升级 Qt 5 时全得改。嗯，那滋味真不好受。所以我现在写新代码，一律用函数指针方式连接信号槽。

3.4 信号重载的最佳实践

我个人建议，信号重载不要超过两个版本。为什么呢？你想想看，如果同一个信号有 5 个重载版本，连接代码会变得非常丑陋：

// 5 个重载版本？别这么干
signals:
    void dataReady();
    void dataReady(int id);
    void dataReady(int id, const QString &name);
    void dataReady(int id, const QString &name, double value);
    void dataReady(const QVariantMap &data);

这种设计，说白了就是偷懒。更好的做法是用一个统一的信号，参数用结构体或 QVariantMap：

// 更优雅的设计
struct DataPayload {
    int id;
    QString name;
    double value;
};

signals:
    void dataReady(const DataPayload &payload);

这样既清晰，又避免了重载带来的连接麻烦。

3.5 知识体系图

下面我用一张 SVG 图来总结信号定义的核心逻辑：

个人小技巧：写信号声明时，我习惯在注释里写明“何时触发”和“参数含义”。比如：

// 当用户完成编辑时触发
// @param newText: 编辑后的文本内容
signals:
    void editingFinished(const QString &newText);

这样半年后回头看代码，不用再猜这个信号是干嘛用的。

好了，关于信号的定义和声明，核心就是这些。记住三点：signals 是标记、签名要遵守规则、重载要谨慎。下一节我们会深入信号的连接机制，看看 connect 背后到底发生了什么。

可可精品资料库