Qt自定义快捷键场景下多标识按键的键序列匹配实现问题

核心实现思路 #

问题本质是Qt的QKeySequence默认输出Shift修饰后的可打印字符，和用户按物理键位定义的快捷键规则不一致，只要对用户自定义的快捷键、实际触发的按键序列做统一归一化处理，即可实现匹配。

步骤1：定义键位等价映射表 #

先基于常用键盘布局建立物理键位和Shift修饰后字符的双向映射：

# 美式键盘基础键与Shift组合输出字符的映射，可根据支持的键盘布局扩展
KEY_SHIFT_MAP = {
    '=': '+',
    '-': '_',
    '1': '!',
    '2': '@',
    '3': '#',
    '4': '$',
    '5': '%',
    '6': '^',
    '7': '&',
    '8': '*',
    '9': '(',
    '0': ')',
    '`': '~',
    '[': '{',
    ']': '}',
    '\\': '|',
    ';': ':',
    "'": '"',
    ',': '<',
    '.': '>',
    '/': '?'
}
# 反向映射，用于将触发的Shift修饰字符转回基础键
REVERSE_KEY_SHIFT_MAP = {v: k for k, v in KEY_SHIFT_MAP.items()}

步骤2：实现键序列归一化函数 #

不管是用户输入的自定义快捷键，还是按键事件触发得到的键序列，都统一转换为修饰符+物理基础键的格式：

def normalize_key_sequence(seq_str):
    # 拆分修饰符和主键
    parts = seq_str.lower().split('+')
    modifiers = parts[:-1]
    main_key = parts[-1]
    
    # 如果主键是Shift修饰后的字符，转回基础键
    if main_key in REVERSE_KEY_SHIFT_MAP:
        main_key = REVERSE_KEY_SHIFT_MAP[main_key]
        # 移除多余的shift修饰符（如果是因为字符本身带shift导致的）
        if 'shift' in modifiers:
            modifiers.remove('shift')
    
    return '+'.join(modifiers + [main_key])

步骤3：修改按键事件处理逻辑 #

在原有按键事件处理逻辑中，加入归一化处理后再匹配：

def analyzekeyPressEvent(self, e):
    if e.type() != QEvent.KeyPress:
        return
    key = e.key()

    if key == Qt.Key_unknown:
        return

    # 单独按下修饰键不处理
    if key in (Qt.Key_Control, Qt.Key_Shift, Qt.Key_Alt, Qt.Key_Meta):
        return

    modifiers = e.modifiers()
    # 构造原始键序列
    if modifiers & Qt.ShiftModifier:
        key += Qt.SHIFT
    if modifiers & Qt.ControlModifier:
        key += Qt.CTRL
    if modifiers & Qt.AltModifier:
        key += Qt.ALT
    if modifiers & Qt.MetaModifier:
        key += Qt.META

    raw_seq = QKeySequence(key).toString(QKeySequence.NativeText)
    # 归一化后匹配用户预定义快捷键
    normalized_seq = normalize_key_sequence(raw_seq)
    
    # 直接匹配归一化后的快捷键字典即可
    if normalized_seq in self.user_shortcuts:
        self.user_shortcuts[normalized_seq]()

步骤4：用户自定义快捷键存储处理 #

用户录入自定义快捷键时，也先做归一化再存储，保证两边格式统一：

# 示例：用户录入ctrl++时的处理
user_input_seq = "ctrl++"
normalized = normalize_key_sequence(user_input_seq)
# 存储归一化后的结果：ctrl+=
self.user_shortcuts[normalized] = 放大函数

扩展说明 #

• 如果需要支持多语言键盘布局，可以调用对应平台的键盘布局API获取实时键位映射，替换硬编码的KEY_SHIFT_MAP即可
• 特殊功能键（F1-F12、方向键等）无需处理，直接匹配即可

内容的提问来源于stack exchange，提问作者wasp256