Back to Qt.io
Contact Us Blog Download Qt
本页内容

KeyboardStyle QML Type

为虚拟键盘提供样式设置界面。更多...

Import Statement: import QtQuick.VirtualKeyboard.Styles
Inherits:

QtObject

属性

详细说明

样式类型提供了InputPanel 用于装饰虚拟键盘的样式定义。

设计尺寸指定了虚拟键盘的宽高比。样式可根据scaleHint 进行缩放，该值由键盘的实际高度和设计高度计算得出。

键盘首先按由keyboardDesignWidth 和keyboardDesignHeight 定义的固定设计尺寸进行布局，然后进行缩放以适应可用宽度。渲染高度由设计宽高比决定：keyboardDesignHeight * width / keyboardDesignWidth 。keyboardHeight 反映了运行时使用的实际缩放高度。

keyboardDesignMaximumHeight 可选地对该高度设置上限。当未设置上限时，按键区域将占据全部可用宽度。当缩放后的高度可能超过最大值时，将保持设计宽高比，并按keyboardDesignMaximumHeight / keyboardDesignHeight 比例缩放整个键盘，从而确保键盘高度永远不会超过最大值。 在这种受限情况下，按键区域的宽度会小于可用宽度并居中显示，两侧留有空白边距；只有键盘背景仍占据全部宽度。scaleHint 是keyboardHeight 与keyboardDesignHeight 的比率，应用于保持所有像素尺寸的比例关系。

请注意，keyboardDesignWidth 和keyboardDesignHeight 是作者单位（内置样式使用2560x800 ，且绝不会按该尺寸渲染），而keyboardDesignMaximumHeight 以逻辑像素为单位，因为它直接与渲染高度（同样以逻辑像素为单位）进行比较。

属性文档

alternateKeysListBackground : Component

替代键列表背景模板。

alternateKeysListBottomMargin : real

“备用键列表”面板的底部边距。

alternateKeysListDelegate : Component

“替代键”列表项的模板。

注意：该 委托用于ListView 中。

该项目具有以下属性：

  • text 键的文本
  • data 键的数据

alternateKeysListHighlight : Component

替代键列表高亮显示的模板。

注意：该 委托使用形式为ListView.highlight 。

alternateKeysListItemHeight : real

“备用键”列表项的高度。

alternateKeysListItemWidth : real

“备用键”列表项的宽度。

alternateKeysListLeftMargin : real

“备用键列表”面板的左边距。

alternateKeysListRightMargin : real

“备用键”列表面板的右边距。

alternateKeysListTopMargin : real

“备用键列表”面板的顶部边距。

backspaceKeyPanel : Component

退格键的模板。

注意：该 委托必须基于KeyPanel 类型。

characterPreviewDelegate : Component

字符预览弹出窗口的模板。

如果委托包含text 属性，则当组件处于活动状态时，该属性将更新为显示文本。

property string text

示例：

characterPreviewDelegate: Item {
    property string text
    id: characterPreview
    Rectangle {
        id: characterPreviewBackground
        anchors.fill: parent
        ...
        Text {
            text: characterPreview.text
            anchors.fill: parent
            ...
        }
    }
}

characterPreviewMargin : real

每个键顶部与characterPreviewDelegate 底部之间的像素数。

enterKeyPanel : Component

回车键的模板。

注意：该 委托必须基于KeyPanel 类型。

fullScreenInputBackground : Component [since QtQuick.VirtualKeyboard.Styles 2.2]

该属性存储了全屏输入背景的委托。

该属性在 QtQuick.VirtualKeyboard.Styles 2.2 版本中引入。

fullScreenInputColor : color [since QtQuick.VirtualKeyboard.Styles 2.2]

此属性用于设置全屏输入框的文字颜色。

默认颜色为黑色。

该属性自 QtQuick.VirtualKeyboard.Styles 2.2 版本起引入。

fullScreenInputContainerBackground : Component [since QtQuick.VirtualKeyboard.Styles 2.2]

该属性存储了全屏输入容器背景的委托。

该属性在 QtQuick.VirtualKeyboard.Styles 2.2 版本中引入。

fullScreenInputCursor : Component [since QtQuick.VirtualKeyboard.Styles 2.2]

该属性存储全屏输入字段中光标的委托。

该委托应根据为全屏输入字段定义的parent.blinkStatus 属性来切换光标的可见性。例如：

fullScreenInputCursor: Rectangle {
    width: 1
    color: "#000"
    visible: parent.blinkStatus
}

该属性在 QtQuick.VirtualKeyboard.Styles 2.2 版本中引入。

fullScreenInputFont : font [since QtQuick.VirtualKeyboard.Styles 2.2]

该属性存储全屏输入字段的font 。

该属性是在 QtQuick.VirtualKeyboard.Styles 2.2 版本中引入的。

fullScreenInputMargins : real [since QtQuick.VirtualKeyboard.Styles 2.2]

该属性控制全屏输入字段周围的边距。

默认值为0 。

该属性首次出现在 QtQuick.VirtualKeyboard.Styles 2.2 版本中。

fullScreenInputPadding : real [since QtQuick.VirtualKeyboard.Styles 2.2]

该属性用于控制全屏输入内容周围的内边距。

默认值为0 。

该属性在 QtQuick.VirtualKeyboard.Styles 2.2 中引入。

fullScreenInputPasswordCharacter : string [since QtQuick.VirtualKeyboard.Styles 2.2]

该属性用于存储全屏输入字段的密码掩码字符。

该属性在 QtQuick.VirtualKeyboard.Styles 2.2 版本中引入。

fullScreenInputSelectedTextColor : color [since QtQuick.VirtualKeyboard.Styles 2.2]

此属性用于设置全屏输入字段中选中文字的颜色。

默认颜色设置为fullScreenInputColor 。

该属性在 QtQuick.VirtualKeyboard.Styles 2.2 中引入。

fullScreenInputSelectionColor : color [since QtQuick.VirtualKeyboard.Styles 2.2]

此属性用于设置全屏输入框的选中颜色。

默认颜色为半透明的黑色。

该属性在 QtQuick.VirtualKeyboard.Styles 2.2 中引入。

functionPopupListBackground : Component [since 6.2]

函数弹出列表背景的模板。

该属性在 Qt 6.2 中引入。

functionPopupListDelegate : Component [since 6.2]

函数列表项的模板。

注意：该 委托用于ListView 中。

该项目具有以下属性：

  • keyboardFunction - 当前项的键盘功能。

该属性于 Qt 6.2 中引入。

functionPopupListHighlight : Component [since 6.2]

函数弹出列表高亮效果的模板。

注意：该 委托的定义为ListView.highlight 。

该属性在 Qt 6.2 中引入。

handwritingKeyPanel : Component

手写模式键的模板。

注意：该 委托必须基于KeyPanel 类型。

hideKeyPanel : Component

隐藏键的模板。

注意：该 委托必须基于KeyPanel 类型。

keyPanel : Component

常规键的模板。

注意：委托 必须基于KeyPanel 类型。

示例：

keyPanel: KeyPanel {
    Rectangle {
        anchors.fill: parent
        ...
        Text {
            anchors.fill: parent
            text: control.displayText
            ...
        }
    }
}

keyboardBackground : Component

键盘背景模板。

示例：

keyboardBackground: Rectangle {
    color: "black"
}

keyboardDesignHeight : real

键盘的设计高度，单位为作者单位。

该属性与keyboardDesignWidth 共同定义键盘布局的设计宽高比。渲染高度为keyboardDesignHeight * width / keyboardDesignWidth ，除非该值超过keyboardDesignMaximumHeight ；若超过该值，则保持设计宽高比不变，并按keyboardDesignMaximumHeight / keyboardDesignHeight 的比例缩放整个键盘。该值也是scaleHint 所使用的参考高度。

keyboardDesignMaximumHeight : real [since 6.11]

键盘的最大设计高度，单位为逻辑像素。

当设置为大于0 的值时，它会限制将keyboardDesignHeight 按可用宽度进行缩放后产生的渲染高度。如果缩放后的高度超过此最大值，则键盘将按keyboardDesignMaximumHeight渲染；此时会保留设计宽高比，并改用keyboardDesignMaximumHeight / keyboardDesignHeight 对整个键盘进行缩放，因此键盘的高度绝不会超过最大值。 当该值设置为0 或更小（默认值）时，表示没有最大高度限制，因此高度将遵循keyboardDesignHeight ，并根据宽度进行缩放。

与keyboardDesignWidth 和keyboardDesignHeight 不同，该值以逻辑像素为单位，因为它会直接与渲染高度进行比较。

该属性于 Qt 6.11 中引入。

keyboardDesignWidth : real

键盘的设计宽度，单位为创作单位。

该值与keyboardDesignHeight 共同定义了键盘布局的设计宽高比。样式将按此尺寸进行设计，随后按实际宽度进行缩放；渲染高度由keyboardDesignHeight * width / keyboardDesignWidth 决定。

keyboardHeight : real

键盘的当前高度，单位为逻辑像素。

这是键盘渲染时的实际缩放高度。该值由键盘实现代码设定（与键区容器的高度绑定），反映了将keyboardDesignWidth 、keyboardDesignHeight 以及（若已设置）keyboardDesignMaximumHeight 应用于可用宽度后所产生的布局。请将其与keyboardDesignHeight 结合使用，以获取scaleHint 。

keyboardRelativeBottomMargin : real

最底层按键与键盘容器底边之间的距离，以键盘高度的百分比表示（0.0 -1.0 ）。

keyboardRelativeLeftMargin : real

最左侧按键与键盘左边缘之间的距离，以键盘宽度的百分比表示（0.0 -1.0 ）。

keyboardRelativeRightMargin : real

最右侧按键与键盘右边缘之间的距离，以键盘宽度的百分比表示（0.0 -1.0 ）。

该值与键盘宽度成正比。

keyboardRelativeTopMargin : real

最上方的按键与键盘顶边之间的距离，以键盘高度的百分比表示（0.0 -1.0 ）。

languageKeyPanel : Component

语言键的模板。

注意：该 委托必须基于KeyPanel 类型。

languageListAdd : Transition [since QtQuick.VirtualKeyboard.Styles 2.1]

该属性用于指定要应用于添加到语言列表视图中的项目的过渡效果。

该属性首次出现在 QtQuick.VirtualKeyboard.Styles 2.1 版本中。

languageListBackground : Component [since QtQuick.VirtualKeyboard.Styles 2.1]

语言列表背景模板。

该属性在 QtQuick.VirtualKeyboard.Styles 2.1 版本中引入。

languageListDelegate : Component [since QtQuick.VirtualKeyboard.Styles 2.1]

语言列表项的模板。

注意：该 委托用于ListView 中。

注意：该 委托必须基于SelectionListItem 类型。

该项目具有以下属性：

  • displayName 语言的显示名称。

该属性在 QtQuick.VirtualKeyboard.Styles 2.1 中引入。

languageListHighlight : Component [since QtQuick.VirtualKeyboard.Styles 2.1]

语言列表高亮样式模板。

注意：该 委托的用法为ListView.highlight 。

该属性在 QtQuick.VirtualKeyboard.Styles 2.1 中引入。

languageListRemove : Transition [since QtQuick.VirtualKeyboard.Styles 2.1]

该属性用于指定从语言列表视图中移除项目时应应用的过渡效果。

该属性在 QtQuick.VirtualKeyboard.Styles 2.1 版本中引入。

languagePopupListEnabled : bool [since QtQuick.VirtualKeyboard.Styles 2.1]

此属性用于确定点击语言键时是否显示下拉列表。如果此属性设置为false ，则点击语言键将依次循环显示所有可用语言。

默认值为false 。

该属性在 QtQuick.VirtualKeyboard.Styles 2.1 版本中引入。

modeKeyPanel : Component

通用模式键的模板。

该模板用于可视化显示该按键的状态，其状态可为“开”或“关”。当按键标签无论状态如何均保持不变时，应使用此模板。

当前状态可通过control.mode 属性获取。

注意：委托 必须基于KeyPanel 类型。

导航高亮项的模板。

该控件用于方向键导航模式，用于在键盘上突出显示导航焦点。

该控件通常是一个带有高对比度边框的透明矩形。

该属性在 QtQuick.VirtualKeyboard.Styles 1.1 中引入。

popupListAdd : Transition [since QtQuick.VirtualKeyboard.Styles 2.1]

该属性用于指定对添加到弹出式列表视图中的项目应用的过渡效果。

该属性在 QtQuick.VirtualKeyboard.Styles 2.1 中引入。

popupListBackground : Component [since QtQuick.VirtualKeyboard.Styles 2.1]

弹出列表背景的模板。

该属性在 QtQuick.VirtualKeyboard.Styles 2.1 版本中引入。

popupListDelegate : Component [since QtQuick.VirtualKeyboard.Styles 2.1]

弹出列表项的模板。

注意：该 委托用于ListView 中。

注意：该 委托必须基于SelectionListItem 类型。

该项目具有以下属性：

  • display 当前项的显示文本。
  • wordCompletionLength 从显示文本末尾开始计算的单词补全长度。
  • dictionary 该单词的词典类型，参见QVirtualKeyboardSelectionListModel::DictionaryType 。
  • canRemoveSuggestion 一个布尔值，用于指示该单词是否可以从词典中移除。

该属性在 QtQuick.VirtualKeyboard.Styles 2.1 中引入。

popupListHighlight : Component [since QtQuick.VirtualKeyboard.Styles 2.1]

弹出列表高亮效果的模板。

注意：该 委托的用法为ListView.highlight 。

该属性在 QtQuick.VirtualKeyboard.Styles 2.1 中引入。

popupListRemove : Transition [since QtQuick.VirtualKeyboard.Styles 2.1]

该属性用于指定从弹出式列表视图中移除的项目应应用的过渡效果。

该属性首次引入于 QtQuick.VirtualKeyboard.Styles 2.1 版本。

scaleHint : real [read-only]

键盘样式缩放提示。该值由keyboardHeight 除以keyboardDesignHeight 得出。所有像素尺寸必须与该值成比例。

selectionHandle : Component [since QtQuick.VirtualKeyboard.Styles 2.1]

该控件用于指示文本选区的边界，并允许交互式地移动选区的起始点或结束点。同一控件同时用于选区的起始点和结束点。

目前，选择控点仅支持基于应用程序的集成方式。

该属性首次引入于 QtQuick.VirtualKeyboard.Styles 2.1 版本。

selectionListAdd : Transition [since QtQuick.VirtualKeyboard.Styles 1.3]

该属性用于指定对添加到选择列表视图中的项目应应用的过渡效果。

该属性首次引入于 QtQuick.VirtualKeyboard.Styles 1.3 版本。

selectionListBackground : Component

选拔名单背景模板。

selectionListDelegate : Component

选择列表项的模板。

注意：该 委托用于ListView 中。

注意：该 委托必须基于SelectionListItem 类型。

该项目具有以下属性：

  • display 当前项的显示文本。
  • wordCompletionLength 从显示文本末尾开始计算的单词补全长度。
  • dictionary 该单词的词典类型，参见QVirtualKeyboardSelectionListModel::DictionaryType 。
  • canRemoveSuggestion 一个布尔值，用于指示该单词是否可以从词典中删除。

selectionListHeight : real

选择列表的高度。

selectionListHighlight : Component

选择列表高亮显示的模板。

注意：该 委托的定义为ListView.highlight 。

selectionListRemove : Transition [since QtQuick.VirtualKeyboard.Styles 1.3]

该属性用于指定从选择列表视图中移除的项目应应用的过渡效果。

该属性于 QtQuick.VirtualKeyboard.Styles 1.3 版本中引入。

shiftKeyPanel : Component

Shift 键的模板。

注意：该 委托必须基于KeyPanel 类型。

spaceKeyPanel : Component

空格键的模板。

注意：该 委托必须基于KeyPanel 类型。

symbolKeyPanel : Component

符号模式键的模板。

注意：该 委托必须基于KeyPanel 类型。

traceCanvasDelegate : Component [since QtQuick.VirtualKeyboard.Styles 2.1]

用于渲染 Trace 对象的模板。

注意：该 委托必须基于TraceCanvas 类型。

该属性自 QtQuick.VirtualKeyboard.Styles 2.1 起引入。

traceInputKeyPanelDelegate : Component [since QtQuick.VirtualKeyboard.Styles 2.1]

跟踪输入键的模板。

注意： 委托必须基于TraceInputKeyPanel 类型。

该属性在 QtQuick.VirtualKeyboard.Styles 2.1 中引入。

© 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.