QInputMethodEvent Class
QInputMethodEvent 类为输入法事件提供了参数。更多内容...
| 头文件： | #include <QInputMethodEvent> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake： | QT += gui |
| 继承自： | QEvent |
- 所有成员列表（包括继承的成员）
- QInputMethodEvent 属于事件类。
公共类型
| class | Attribute |
| enum | AttributeType { TextFormat, Cursor, Language, Ruby, Selection, MimeData } |
公共函数
| QInputMethodEvent() | |
| QInputMethodEvent(const QString &preeditText, const QList<QInputMethodEvent::Attribute> &attributes) | |
| const QList<QInputMethodEvent::Attribute> & | attributes() const |
| const QString & | commitString() const |
| const QString & | preeditString() const |
| int | replacementLength() const |
| int | replacementStart() const |
| void | setCommitString(const QString &commitString, int replaceFrom = 0, int replaceLength = 0) |
受保护函数
| QInputMethodEvent(QInputMethodEvent &&) | |
| QInputMethodEvent & | operator=(QInputMethodEvent &&) |
| QInputMethodEvent & | operator=(const QInputMethodEvent &other) |
详细说明
当使用输入法向小部件输入文本时，输入法事件会被发送至该小部件。输入法被广泛用于输入非拉丁字母语言的文本。
请注意，在创建自定义文本编辑控件时，必须显式设置Qt::WA_InputMethodEnabled 窗口属性（使用QWidget::setAttribute()函数），才能接收输入法事件。
这些事件对于希望正确处理具有复杂字符输入语言的键盘输入控件开发者而言尤为重要。此类语言的文本输入通常分为三个步骤：
- 开始输入
当用户按下键盘上的第一个键时，会创建一个输入上下文。该输入上下文将包含所输入字符组成的字符串。
- 编辑
每按下一个新键，输入法都会尝试为迄今为止输入的文本生成一个匹配的字符串，称为预编辑字符串。在输入上下文处于活动状态时，用户只能在属于该输入上下文的字符串内部移动光标。
- 完成
在某个时刻，用户将激活一个用户界面组件（可能通过按特定键），在该组件中，用户可以从多个与当前已输入文本匹配的字符串中进行选择。用户既可以确认选择，也可以取消输入；无论哪种情况，输入上下文都将被关闭。
QInputMethodEvent 模拟了这三个阶段，并传递正确呈现中间结果所需的信息。一个 QInputMethodEvent 具有两个主要参数：preeditString() 和commitString()。preeditString() 参数返回当前活动的预编辑字符串。commitString() 参数返回应添加到编辑器控件文本中（或替换其中部分内容）的文本。该文本通常是输入操作的结果，必须直接插入到控件文本中，位于预编辑字符串之前。
如果commitString() 需要替换编辑器中部分文本，则replacementLength() 将包含待替换的字符数。replacementStart() 包含相对于预编辑字符串开头的替换起始位置。
有若干属性用于控制预编辑字符串的外观（预编辑字符串之外的文本外观仅由控件本身控制）。AttributeType 枚举描述了可设置的各种属性。
实现QWidget::inputMethodEvent() 或QGraphicsItem::inputMethodEvent() 的类，至少应理解并遵守TextFormat 和Cursor 属性。
由于输入法需要能够从控件或图形项中查询某些属性，因此子类还必须分别实现QWidget::inputMethodQuery() 和QGraphicsItem::inputMethodQuery() 方法。
在接收到输入法事件时，文本控件必须执行以下步骤：
- 如果控件有已选文本，则应将其删除。
- 从replacementStart()处开始，删除长度为replacementLength()的文本，并用commitString()替换它。如果replacementLength()为0，则replacementStart()将返回commitString()的插入位置。
进行替换时，会忽略预编辑字符串所在的区域，因此从 -1 开始、长度为 2 的替换操作将删除预编辑字符串前面的最后一个字符以及后面的第一个字符，并将提交字符串插入到预编辑字符串的正前方。
如果控件实现了撤销/重做功能，则该操作会被添加到撤销堆栈中。
- 如果当前没有预编辑字符串，则将 `preeditString()` 插入到当前光标位置；否则，用从该事件接收到的字符串替换之前的 `preeditString `。
如果控件实现了撤销/重做功能，preeditString() 不应以任何方式影响撤销/重做堆栈。
控件应检查要应用于预编辑字符串的属性列表。它必须至少理解TextFormat 和Cursor属性，并按规定进行渲染。
另请参阅 QInputMethod 。
成员类型文档
enum QInputMethodEvent::AttributeType
| 常数 | 值 | 描述 |
|---|---|---|
QInputMethodEvent::TextFormat | 0 | 用于表示由 start 和 length 指定的预编辑字符串部分的QTextCharFormat 。value 包含一个类型为QTextFormat 的QVariant ，用于指定该预编辑字符串部分的渲染方式。预编辑字符串的每个部分至多应有一个格式。如果为字符串中的任何字符指定了多个格式，则行为未定义。 符合规范的实现至少必须支持该格式中的 backgroundColor、textColor 和 fontUnderline 属性。 |
QInputMethodEvent::Cursor | 1 | 若已设置，则应在预编辑字符串的start位置显示光标。length变量决定光标是否可见。若length为0，则光标不可见。若value为类型为QColor 的QVariant ，则使用该颜色渲染光标；否则，将使用周围文本的颜色。 每个事件最多应包含一个 Cursor 属性。若指定了多个，则行为未定义。 |
QInputMethodEvent::Language | 2 | 该变体包含一个QLocale 对象，用于指定预编辑字符串中某一部分的语言。预编辑字符串的每一部分最多应设置一种语言。若为字符串中的任何字符指定了多种语言，则行为未定义。 |
QInputMethodEvent::Ruby | 3 | 预编辑字符串某部分的注音文本。预编辑字符串的每个部分最多应设置一个注音文本。如果为字符串中的任何字符指定了多个注音文本，则行为未定义。 |
QInputMethodEvent::Selection | 4 | 如果设置了此属性，编辑光标应移动到编辑器文本内容中的指定位置。与Cursor 不同，此属性不作用于预编辑文本，而是作用于周围的文本。光标将在提交字符串提交后移动，而预编辑字符串将位于新的编辑位置。 起始位置指定新位置，长度变量可用于设置从该点开始的选区。该值未被使用。 |
QInputMethodEvent::MimeData | 5 | 若已设置，该变体将包含一个表示已提交文本的QMimeData 对象。commitString() 方法仍提供已提交文本的纯文本表示形式。 |
另请参阅 Attribute 。
成员函数文档
QInputMethodEvent::QInputMethodEvent()
创建一个类型为QEvent::InputMethod 的事件。attributes()、preeditString()、commitString()、replacementStart()和replacementLength()被初始化为默认值。
另请参阅 setCommitString()。
QInputMethodEvent::QInputMethodEvent(const QString &preeditText, const QList<QInputMethodEvent::Attribute> &attributes)
创建一个类型为QEvent::InputMethod 的事件。预编辑文本设置为preeditText ，属性设置为attributes 。
commitString()、replacementStart() 和replacementLength() 的值可通过setCommitString() 进行设置。
另请参阅 preeditString() 和attributes()。
[protected delete] QInputMethodEvent::QInputMethodEvent(QInputMethodEvent &&)
通过移动构造一个QInputMethodEvent 实例。该函数已被删除。
const QList<QInputMethodEvent::Attribute> &QInputMethodEvent::attributes() const
返回传递给QInputMethodEvent 构造函数的属性列表。这些属性控制预编辑字符串的外观（预编辑字符串以外的文本外观仅由小部件控制）。
另请参阅 preeditString() 和Attribute 。
const QString &QInputMethodEvent::commitString() const
返回应添加到（或替换编辑器控件文本中部分内容）的文本。该文本通常是输入操作的结果，必须插入到控件文本中，且位于预编辑字符串之前。
另请参阅 setCommitString()、preeditString()、replacementStart() 和replacementLength()。
const QString &QInputMethodEvent::preeditString() const
返回编辑前的文本，即用户开始编辑之前的文本。
另请参阅 commitString() 和attributes()。
int QInputMethodEvent::replacementLength() const
返回预编辑字符串中待替换的字符数。
另请参阅 replacementStart() 和setCommitString()。
int QInputMethodEvent::replacementStart() const
返回相对于预编辑字符串开头的位置，该位置处将进行字符替换。
另请参阅 replacementLength() 和setCommitString()。
void QInputMethodEvent::setCommitString(const QString &commitString, int replaceFrom = 0, int replaceLength = 0)
将提交字符串设置为commitString 。
提交字符串是指应添加到编辑器控件文本中（或替换其中部分内容）的文本。它通常是输入操作的结果，必须直接插入到控件文本中，位于预编辑字符串之前。
如果提交字符串需要替换编辑器中文本的部分内容，则 `replaceLength ` 指定要替换的字符数。`replaceFrom ` 指定相对于预编辑字符串开头的替换起始位置。
另请参阅 commitString()、replacementStart() 和replacementLength()。
[protected delete] QInputMethodEvent &QInputMethodEvent::operator=(QInputMethodEvent &&)
将other 按移动赋值方式赋值给此QInputMethodEvent 实例。该函数已被删除。
[noexcept protected default] QInputMethodEvent &QInputMethodEvent::operator=(const QInputMethodEvent &other)
将other 复制并赋值给此QInputMethodEvent 实例。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
