InputPanel QML Type
提供虚拟键盘用户界面。更多...
| Import Statement: | import QtQuick.VirtualKeyboard |
| Inherits: |
属性
- active : bool
(since QtQuick.VirtualKeyboard 2.0) - externalLanguageSwitchEnabled : bool
(since QtQuick.VirtualKeyboard 2.4)
信号
- externalLanguageSwitch(var localeList, int currentIndex)
(since QtQuick.VirtualKeyboard 2.4)
详细说明
键盘大小会根据可用宽度自动计算；也就是说，键盘会保持当前样式指定的宽高比。因此，应用程序只需设置 InputPanel 的width 和y 坐标，而无需设置height 。
与该模块提供的所有其他 QML 类型一样，在使用 InputPanel 之前，必须将环境变量QT_IM_MODULE 设置为qtvirtualkeyboard 。有关更多信息，请参阅“加载插件”。
注意： 您的应用程序中只能 有一个 InputPanel 实例。该面板不会被模态对话框阻塞，但可能会被z 值更高的项目遮挡。
属性文档
active : bool [since QtQuick.VirtualKeyboard 2.0]
该属性反映输入面板的活动状态。当该属性值为true 时，应向用户显示键盘。
该属性在 QtQuick.VirtualKeyboard 2.0 中引入。
externalLanguageSwitchEnabled : bool [since QtQuick.VirtualKeyboard 2.4]
此属性用于启用外部语言切换机制。当此属性设置为true 时，虚拟键盘将不会显示内置的语言下拉菜单，而是会发出externalLanguageSwitch 信号。应用程序可以处理此信号，并显示自定义的语言选择对话框。
该属性在 QtQuick.VirtualKeyboard 2.4 版本中引入。
信号文档
[since QtQuick.VirtualKeyboard 2.4] externalLanguageSwitch(var localeList, int currentIndex)
当externalLanguageSwitchEnabled 的值为true ，且用户按下语言切换键时，会触发此信号。
该信号用作钩子，用于显示自定义语言对话框，以替代虚拟键盘中的内置语言弹出窗口。
localeList 参数包含可供选择的区域设置名称列表。要获取有关特定语言的更多信息，请使用Qt.locale() 函数。currentIndex 是localeList 中当前区域设置的索引。该项目应作为当前项目在 UI 中突出显示。
要选择新语言，请使用VirtualKeyboardSettings.locale 属性。
以下是一个演示自定义语言对话框实现的示例：
Dialog {
id: languageDialog
title: "Select Input Language"
modality: Qt.ApplicationModal
function show(localeList, currentIndex) {
languageListModel.clear()
for (var i = 0; i < localeList.length; i++) {
languageListModel.append({localeName: localeList[i], displayName: Qt.locale(localeList[i]).nativeLanguageName})
}
languageListView.currentIndex = currentIndex
languageListView.positionViewAtIndex(currentIndex, ListView.Center)
languageDialog.visible = true
}
contentItem: ListView {
id: languageListView
model: ListModel {
id: languageListModel
function selectItem(index) {
VirtualKeyboardSettings.locale = languageListModel.get(index).localeName
languageDialog.visible = false
}
}
delegate: Item {
id: languageListItem
width: languageNameTextMetrics.width * 17
height: languageNameTextMetrics.height + languageListLabel.anchors.topMargin + languageListLabel.anchors.bottomMargin
Text {
id: languageListLabel
anchors.left: parent.left
anchors.top: parent.top
anchors.leftMargin: languageNameTextMetrics.height / 2
anchors.rightMargin: anchors.leftMargin
anchors.topMargin: languageNameTextMetrics.height / 3
anchors.bottomMargin: anchors.topMargin
text: languageNameFormatter.elidedText
color: "#5CAA15"
font {
weight: Font.Normal
pixelSize: 28
}
}
TextMetrics {
id: languageNameTextMetrics
font {
weight: Font.Normal
pixelSize: 28
}
text: "X"
}
TextMetrics {
id: languageNameFormatter
font {
weight: Font.Normal
pixelSize: 28
}
elide: Text.ElideRight
elideWidth: languageListItem.width - languageListLabel.anchors.leftMargin - languageListLabel.anchors.rightMargin
text: displayName
}
MouseArea {
anchors.fill: parent
hoverEnabled: true
onClicked: {
if (index === -1)
return
parent.ListView.view.currentIndex = index
parent.ListView.view.model.selectItem(index)
}
}
states: State {
name: "current"
when: languageListItem.ListView.isCurrentItem
PropertyChanges {
target: languageListLabel
color: "black"
}
}
}
}
}对话框的声明如下：
LanguageDialog {
id: languageDialog
width: 400
height: 400
}在应用程序的 `InputPanel` 中，添加以下代码：
InputPanel {
id: inputPanel
externalLanguageSwitchEnabled: true
onExternalLanguageSwitch: languageDialog.show(localeList, currentIndex)
// ...
}现在，当按下语言切换键时，将显示该自定义对话框。
注意： 相应的处理程序 是 `onExternalLanguageSwitch`。
该信号在 QtQuick.VirtualKeyboard 2.4 版本中引入。
© 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.
