macOS下如何拦截监听音量、屏幕亮度等Fn扩展功能键

问题背景 #

我在macOS上使用CGEventTapCreate开发远程桌面工具，需要捕获所有按键操作，包括Fn组合的扩展功能键（音量调节、亮度控制等）。当前遇到的问题是无法准确区分这些Fn键的按下/释放状态——按下时能收到事件，但释放时没有对应的响应。

现有代码 #

CGEventMask eventMask = CGEventMaskBit(NX_APPDEFINED) | \
                        CGEventMaskBit(NX_KITDEFINED) | \
                        CGEventMaskBit(NX_SYSDEFINED) | \
                        CGEventMaskBit(kCGEventKeyDown) | \
                        CGEventMaskBit(kCGEventKeyUp) | \
                        CGEventMaskBit(kCGEventFlagsChanged);

CFMachPortRef eventTap = CGEventTapCreate(kCGSessionEventTap, kCGHeadInsertEventTap, kCGEventTapOptionDefault, eventMask,
    [](CGEventTapProxy proxy, CGEventType type, CGEventRef pEventRef, void *refcon) -> CGEventRef {
        CGKeyCode keyCode = (CGKeyCode)CGEventGetIntegerValueField(pEventRef, kCGKeyboardEventKeycode);
        CGEventFlags flags = CGEventGetFlags(pEventRef);
        int64_t SourceStateID = CGEventGetIntegerValueField(pEventRef, kCGEventSourceStateID);
        int64_t Autorepeat = CGEventGetIntegerValueField(pEventRef, kCGKeyboardEventAutorepeat);
        int64_t KeyboardType = CGEventGetIntegerValueField(pEventRef, kCGKeyboardEventKeyboardType);
        int64_t UserData = CGEventGetIntegerValueField(pEventRef, kCGEventSourceUserData);
        int64_t SourceUnixProcessID = CGEventGetIntegerValueField(pEventRef, kCGEventSourceUnixProcessID);
        int64_t TargetUnixProcessID = CGEventGetIntegerValueField(pEventRef, kCGEventTargetUnixProcessID);

        qInfo() << "CGEvent type=" << type \
                << "flags=" << QString::number(flags, 16) \
                << "keyCode=" << QString::number(keyCode, 16) \
                << "Autorepeat=" << Autorepeat \
                << "KeyboardType=" << KeyboardType \
                << "UserData=" << UserData \
                << "SourceUnixProcessID=" << SourceUnixProcessID \
                << "TargetUnixProcessID=" << TargetUnixProcessID \
                << "SourceStateID=" << SourceStateID;

        return NULL;
    }, nullptr);

测试情况 #

单独按下Fn组合的F1、F2、F7~F12这八个按键，得到的测试结果如下：

问题原因 #

Fn扩展功能键默认会被macOS封装为NX_SYSDEFINED类型事件，而非普通的kCGEventKeyDown/kCGEventKeyUp事件。这类事件的按下/释放状态不会通过事件类型直接区分，而是隐藏在kCGEventSystemDefinedEventData字段中。

解决方案 #

修改事件回调逻辑，针对NX_SYSDEFINED事件解析其内部的HID报告数据，提取按键状态和对应键码：

CGEventMask eventMask = CGEventMaskBit(NX_APPDEFINED) | \
                        CGEventMaskBit(NX_KITDEFINED) | \
                        CGEventMaskBit(NX_SYSDEFINED) | \
                        CGEventMaskBit(kCGEventKeyDown) | \
                        CGEventMaskBit(kCGEventKeyUp) | \
                        CGEventMaskBit(kCGEventFlagsChanged);

CFMachPortRef eventTap = CGEventTapCreate(kCGSessionEventTap, kCGHeadInsertEventTap, kCGEventTapOptionDefault, eventMask,
    [](CGEventTapProxy proxy, CGEventType type, CGEventRef pEventRef, void *refcon) -> CGEventRef {
        // 处理普通按键的按下/释放事件
        if (type == kCGEventKeyDown || type == kCGEventKeyUp) {
            CGKeyCode keyCode = (CGKeyCode)CGEventGetIntegerValueField(pEventRef, kCGKeyboardEventKeycode);
            qInfo() << (type == kCGEventKeyDown ? "按键按下" : "按键释放") 
                    << "| 键码: 0x" << QString::number(keyCode, 16);
        }
        // 处理Fn扩展功能键的系统定义事件
        else if (type == NX_SYSDEFINED) {
            uint32_t sysEventData = CGEventGetIntegerValueField(pEventRef, kCGEventSystemDefinedEventData);
            // 解析数据：高16位为键码，低16位为状态（非0=按下，0=释放）
            CGKeyCode keyCode = (sysEventData >> 16) & 0xFFFF;
            bool isPressed = (sysEventData & 0xFFFF) != 0;

            qInfo() << (isPressed ? "Fn键按下" : "Fn键释放") 
                    << "| 键码: 0x" << QString::number(keyCode, 16);
        }

        // 如果需要让系统继续处理该事件，返回原事件；否则返回NULL
        return pEventRef;
    }, nullptr);

注意事项 #

1. 权限要求：使用CGEventTap需要开启系统辅助功能权限，前往「系统偏好设置 > 安全性与隐私 > 隐私 > 辅助功能」添加你的应用。
2. 键码差异：不同Mac机型的Fn扩展键对应的CGKeyCode可能略有不同，建议实际测试确认（比如音量增大通常是0x48，音量减小0x49，静音0x4A，亮度增大0x46，亮度减小0x47）。
3. 事件传递：如果不需要拦截事件，回调返回pEventRef让系统继续处理；如果要阻止系统响应（比如远程桌面时本地不调节音量），返回NULL。

内容的提问来源于stack exchange，提问作者gao.xiangyang