Qt / Qml 中捕获(中文)输入法事件(按下提交)

news2024/11/28 16:53:00

【写在前面】

最近工作中遇到一个奇怪的问题：

本来想在 TextEdit ( QTextEdit ) 中捕获一下键盘按键按下的事件。

然而，当输入法为英文时( 正常输入字符 )，可以捕获到按键事件，但当我切换到中文时，弹出输入法选框后，却无法再像英文那样捕获到事件。

经过查阅资料，发现在使用输入法时，不会发出按键事件，而是另外一种不太常见的事件类型：QEvent::InputMethod ，与之关联的事件为：QInputMethodEvent 。

为了正确处理这类事件，我简单封装了一个辅助类，效果相当不错。

【正文开始】

首先，因为要处理特殊事件，必须重新实现 bool QObject::event(QEvent *e)，不过我们并不需要重写 TextEdit ( QTextEdit ) 这些类，只需借助事件过滤器即可：

使用 void QObject::installEventFilter(QObject *filterObj) 函数为指定对象安装事件过滤器。

这里的过滤器称为 InputMethodEventCatch ：

class InputMethodEventCatch : public QObject
{
    Q_OBJECT

    Q_PROPERTY(QObject* target READ target WRITE setTarget NOTIFY targetChanged)

public:
    explicit InputMethodEventCatch(QObject *parent = nullptr);
    ~InputMethodEventCatch();

    QObject *target();
    void setTarget(QObject *target);

    bool eventFilter(QObject *obj, QEvent *event);

signals:
    void targetChanged();
    void inputMethodEventPressed(int code, const QString &key);
    void inputMethodEventCommitted(const QString &commitString);

private:
    QObject *m_target = nullptr;
};

它提供主要两个信号：

void inputMethodEventPressed(int code, const QString &key) 输入法按键按下时发出，code为 Qt::Key Qt 按键枚举，key 则为按键字符(串)。

void inputMethodEventCommitted(const QString &commitString) 输入法编辑完成时发出，代表文本从输入法提交到编辑器，其中 commitString 为提交的文本。

接下来是实现部分：

InputMethodEventCatch::InputMethodEventCatch(QObject *parent)
    : QObject{parent}
{

}

InputMethodEventCatch::~InputMethodEventCatch()
{
    if (m_target) m_target->removeEventFilter(this);
}

QObject *InputMethodEventCatch::target()
{
    return m_target;
}

void InputMethodEventCatch::setTarget(QObject *target)
{
    if (!target) return;

    if (m_target != target) {
        if (m_target) m_target->removeEventFilter(this);
        target->installEventFilter(this);
        m_target = target;
        emit targetChanged();
    }
}

bool InputMethodEventCatch::eventFilter(QObject *obj, QEvent *event)
{
    if (event->type() == QEvent::InputMethod) {
        QInputMethodEvent *input = static_cast<QInputMethodEvent *>(event);
        if (input->preeditString().isEmpty()) {
            emit inputMethodEventCommitted(input->commitString());
        } else {
            QString key;
            for (const auto &attr: input->attributes()) {
                if (attr.type == QInputMethodEvent::AttributeType::Cursor && attr.start > 0) {
                    key = input->preeditString().mid(attr.start - 1, attr.length);
                    break;
                }
            }
            if (key.size() == 1)
                emit inputMethodEventPressed(key2code(*key.begin()), key);
        }
    }
    return QObject::eventFilter(obj, event);
}

关键代码在 eventFilter() 中：

1、如果预编辑字符串为空，则认为编辑完成。

2、如果不为空，那么我们取出光标处的字符，然后使用 key2code() 转换为 Qt::Key。

其中 key2code() 实现如下：

static int key2code(const QChar &key)
{
    switch (key.toLatin1())
    {
    case 'q': case 'Q': return Qt::Key_Q;
    case 'w': case 'W': return Qt::Key_W;
    case 'e': case 'E': return Qt::Key_E;
    case 'r': case 'R': return Qt::Key_R;
    case 't': case 'T': return Qt::Key_T;
    case 'y': case 'Y': return Qt::Key_Y;
    case 'u': case 'U': return Qt::Key_U;
    case 'i': case 'I': return Qt::Key_I;
    case 'o': case 'O': return Qt::Key_O;
    case 'p': case 'P': return Qt::Key_P;
    case 'a': case 'A': return Qt::Key_A;
    case 's': case 'S': return Qt::Key_S;
    case 'd': case 'D': return Qt::Key_D;
    case 'f': case 'F': return Qt::Key_F;
    case 'g': case 'G': return Qt::Key_G;
    case 'h': case 'H': return Qt::Key_H;
    case 'j': case 'J': return Qt::Key_J;
    case 'k': case 'K': return Qt::Key_K;
    case 'l': case 'L': return Qt::Key_L;
    case 'z': case 'Z': return Qt::Key_Z;
    case 'x': case 'X': return Qt::Key_X;
    case 'c': case 'C': return Qt::Key_C;
    case 'v': case 'V': return Qt::Key_V;
    case 'b': case 'B': return Qt::Key_B;
    case 'n': case 'N': return Qt::Key_N;
    case 'm': case 'M': return Qt::Key_M;
    }

    return Qt::Key_unknown;
}

注意：该实现只转换了 26 个字母，其他的根据需要自己加上即可。

【如何使用】

使用起来相当简单：

#include "inputmethodeventcatch.h"

#include <QApplication>
#include <QDebug>
#include <QTextEdit>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    QTextEdit edit;
    InputMethodEventCatch editCatch;
    QObject::connect(&editCatch, &InputMethodEventCatch::inputMethodEventPressed, &editCatch, [](int code, const QString &key){
        qDebug() << "inputMethodEventPressed" << Qt::Key(code) << key;
    });
    QObject::connect(&editCatch, &InputMethodEventCatch::inputMethodEventCommitted, &editCatch, [](const QString &commitString){
        qDebug() << "inputMethodEventCommitted" << commitString;
    });
    editCatch.setTarget(&edit);
    edit.show();

    return app.exec();
}

绑定相关信号并 setTarget() 即可。

效果如下所示：

【结语】

最后，实际上 Qml 中也一样可以使用，只需要将 InputMethodEventCatch 注册进 Qml 中即可，然后类似这样：

TextEdit {
    id: textEdit
}

InputMethodEventCatch {
    target: textEdit
    onInputMethodEventPressed: { }
    onInputMethodEventCommitted: { }
}

源码地址，Github的：GitHub - mengps/QtExamples: 分享各种 Qt 示例,，说不定用得上呢~分享各种 Qt 示例,，说不定用得上呢~. Contribute to mengps/QtExamples development by creating an account on GitHub.https://github.com/mengps/QtExamples