本章重要 API 函数#

💡 Tips：键盘事件只发给当前拥有焦点的控件——这是新手第一道坎。本工程构造函数里 setFocusPolicy(Qt::StrongFocus); setFocus(); 就是为了让 Widget 拿到焦点、从而能收到 keyPressEvent。key() 与 text() 用途不同：key() 区分”哪个物理键”（方向键、F1 等无字符键只能用 key()），text() 拿到”按出的字符”（处理字母/数字输入时用）。方向键的 text() 为空字符串，务必用 key() 判断。

本章目录#

点击条目可跳转到对应小节。

学习前后依赖#

💡 Tips：必须先懂”事件要先到达焦点控件”——否则 keyPressEvent 写了却从不触发，会让人怀疑人生。本篇是 16 篇鼠标事件的”兄弟篇”，两者都是重写输入事件函数；区别仅在于键盘事件多了一层”焦点”门槛。

1. 概述#

键盘是除鼠标外最主要的文本与命令输入设备。Qt 把键盘交互拆成 keyPressEvent（按下）与 keyReleaseEvent（松开）两个虚函数。本工程 qt17_tst_keyboard 的核心演示是：用方向键移动窗口里的一个 QPushButton——按 ←/→/↑/↓ 让按钮在窗口内平移 10 像素。同时工程里还放了一个 QTimer，每秒刷新按钮上显示的当前时间（mm,ss），用来对比”信号槽定时器”与”事件定时器 timerEvent”两种机制。

💡 Tips：记住一句话——键盘事件必须先过”焦点”这一关：只有拿到焦点的控件才会收到 keyPressEvent。本工程 setFocus() 让 Widget 主动抢到焦点，这是键盘演示能跑起来的前提。另外本项目实际只重写了 keyPressEvent，并未实现 keyReleaseEvent——后者在源码中不存在，本篇会在第 2、4 节作为扩展对比说明，避免你误以为工程里有。

2. 核心概念 / 原理#

键盘事件对象 QKeyEvent 携带两类关键信息：物理键位 key() 与 输入字符 text()。

• key() 返回 Qt::Key 枚举（如 Qt::Key_Left、Qt::Key_A）。它描述的是”哪个键被按”，不受 Shift、CapsLock、输入法影响。判断是否方向键、功能键、控制键必须用 key()。
• text() 返回该按键产生的 Unicode 字符（受 Shift/输入法影响）。a 与 A 的 key() 都是 Key_A，但 text() 分别是 "a" 和 "A"。处理可打印字符输入时用 text()。

焦点机制：Qt 的事件循环中，键盘事件被派发给当前焦点控件（focus widget）。控件能否获得焦点由 focusPolicy 决定：Qt::NoFocus（永不）、Qt::TabFocus（Tab 切到）、Qt::ClickFocus（点击获得）、Qt::StrongFocus（Tab+点击+代码 setFocus() 均可）。本工程用 StrongFocus 并主动 setFocus()。

1
// widget.cpp 构造函数关键两行
2
setFocusPolicy(Qt::StrongFocus);   // 允许本控件获得键盘焦点
3
setFocus();                        // 主动夺取焦点，确保能收 keyPressEvent

💡 Tips：原理上最易误解的是”keyPressEvent 写了却不触发”——根因几乎都是焦点不在本控件上（没 setFocus、或被别的控件抢走，比如窗口里有个 QLineEdit 聚焦时键盘事件就归它了）。其次要分清 key() 与 text()：方向键没有字符，text() 为空，只能用 key() 判方向；而你想做”输入字母过滤”时该用 text() 拿真实字符。

3. 键盘事件的分发与焦点链路#

下面用流程图展示键盘消息如何从系统到达 keyPressEvent，并强调焦点这一关卡：

💡 Tips：流程里最关键的关卡是 D（焦点判定）。若焦点不在 Widget（比如点了一下别的可聚焦控件，或被系统切走），keyPressEvent 根本不会到达本工程的函数，而是被真正的焦点控件消费。这也是为什么构造函数必须 setFocus()——主动把焦点钉在 Widget 上。本工程只实现了 KeyPress 分支（F→H→I），KeyRelease 分支（G）在源码中未重写，交给基类默认处理。

4. 核心代码解析#

1
Widget::Widget(QWidget *parent) : QWidget(parent) {
2
    setGeometry(100,100,400,400);
3
    setFocusPolicy(Qt::StrongFocus);
4
    setFocus();                       // 关键：夺取键盘焦点
5
    btn_move = new QPushButton(this);
6
    btn_move->resize(80,80);
7
    btn_move->setText("Move Button");
8
    QTimer *timer = new QTimer(this);
9
    timer->start(1000);               // 每 1 秒触发一次 timeout
10
    connect(timer, &QTimer::timeout, [=](){
11
        QTime abc = QTime::currentTime();
12
        btn_move->setText(abc.toString("mm,ss"));   // 按钮上显示时分秒
13
    });
14
}

1
void Widget::keyPressEvent(QKeyEvent *event) {
2
    QPoint pt = btn_move->pos();
3
    int step = 10;
4
    switch (event->key()) {           // 用 key() 判方向键
5
    case Qt::Key_Left:  pt.rx() -= step; break;
6
    case Qt::Key_Right: pt.rx() += step; break;
7
    case Qt::Key_Up:    pt.ry() -= step; break;
8
    case Qt::Key_Down:  pt.ry() += step; break;
9
    default:
10
        QWidget::keyPressEvent(event); // 其它键交给基类
11
    }
12
    btn_move->move(pt);
13
    event->accept();                   // 标记事件已处理
14
}

1
void Widget::keyReleaseEvent(QKeyEvent *event) override {
2
    // 例如：松开方向键后做收尾处理
3
    QWidget::keyReleaseEvent(event);
4
}

5. 运行效果 / 验证#

运行 400×400 窗口，中央有一个 “Move Button” 按钮，其文字每秒刷新为当前 mm,ss 时间。验证：

1. 窗口获得焦点后，按 ←/→/↑/↓ → 按钮按对应方向平移 10 像素；连续按多次持续移动。
2. 按其它键（如字母、空格）→ 按钮不动，事件交由基类（如焦点在按钮上时可触发按钮默认行为）。
3. 按钮文字持续以 mm,ss 跳动，证明 QTimer 每秒刷新生效。

💡 Tips：验证时容易误判”成功”的假象——若方向键完全没反应，九成是焦点不在窗口（例如你先点了一下按钮，焦点跑到按钮上，方向键事件就被按钮吃掉了）。解决：点窗口空白区让 Widget 重新获得焦点，或确保程序启动时的 setFocus() 生效。若按钮文字不刷新，检查 QTimer::start(1000) 是否执行、connect 是否写成新式函数指针。

容易踩坑（注意点）#

• 坑 1：keyPressEvent 写了却不触发 → 焦点不在本控件。规避：setFocusPolicy(StrongFocus) + setFocus()；避免窗口里有其它可聚焦控件抢焦点。
• 坑 2：用 text() 判断方向键 → 方向键 text() 为空，判断永远失败。规避：方向键/功能键一律用 event->key()。
• 坑 3：用 key() 做字母大小写判断 → Key_A 不论 Shift 都是同一枚举，key() 区分不了 a/A。规避：需要真实字符用 event->text()。
• 坑 4：timerEvent 不触发却以为是键盘问题 → 本工程用 QTimer 而非 startTimer()，timerEvent 是死代码。规避：要么用 startTimer(ms) 触发 timerEvent，要么像工程那样用 QTimer 信号槽（二者选一，别混）。
• 坑 5：默认分支忘记 QWidget::keyPressEvent(event) → 其它键的默认行为（如 Tab 切换焦点）失效。规避：非自己处理的键要转发基类。
• 坑 6：event->accept() 用错位置 → 若只想接受方向键，应放在 case 内而非全局；本工程全局 accept 对所有方向键合理，但 default 已交基类处理，注意语义。
• 坑 7：头文件声明 id1/id2 但从未 startTimer → 变量无用、可能误导读者。规避：演示 timerEvent 就调 startTimer 并保存返回的 id 赋给 id1/id2；否则删掉避免混淆。

学习要点总结#

Q&A（常见问题）#

Q1：为什么我重写了 keyPressEvent 却一次都没被调用？ A1：几乎都是焦点问题。键盘事件只发给焦点控件。请确认：(1) 工程里调用了 setFocusPolicy(Qt::StrongFocus) 和 setFocus()；(2) 运行时没点过其它可聚焦控件把焦点抢走；(3) 窗口本身 isActiveWindow() 为真（未被遮挡到后台）。本工程在构造函数末尾 setFocus() 正是为了确保启动即获焦点。

Q2：key() 和 text() 到底该用哪个？ A2：规则很简单——判”哪个键”用 key()，取”什么字符”用 text()。方向键、功能键（F1、Shift、Ctrl）、控制键没有可打印字符，text() 为空，只能用 key()。而当你要过滤/收集用户真实输入的字母数字时（如屏蔽某些字符、做输入掩码），用 text() 才能拿到 Shift/CapsLock/输入法作用后的真实字符。

Q3：Qt5 和 Qt6 在键盘事件上有差异吗？ A3：keyPressEvent/QKeyEvent 的接口基本一致。Qt6 仍是 key() 返回 Qt::Key、text() 返回 QString。需要注意的跨版本点主要在坐标/枚举细节，键盘事件本身改动很小。本工程 Qt6 用法在 Qt5 同样适用。差异较大的是部分废弃枚举值（如 Qt::Key_ 个别常量），但方向键 Key_Left/Right/Up/Down 一直稳定。

Q4：本工程的 timerEvent 和 id1/id2 有什么用？为什么没触发？ A4：这是源码里的一段”遗留/未完成”代码——头文件声明了 int id1; int id2; 并实现了 timerEvent()（按 timerId() 分别处理），但构造函数里用的是 QTimer（信号槽方式），没有调用 startTimer()，所以 id1/id2 一直是 0、timerEvent 永不被调用。若想真正演示 timerEvent，应在构造里 id1 = startTimer(1000); 并据此在 timerEvent 里 killTimer(id1)。当前工程按钮上的时间刷新完全来自 QTimer，与 timerEvent 无关。

Tips（全局速记）#