TextField QML Type
单行文本输入框。更多
| Import Statement: | import QtQuick.Controls |
| Inherits: |
属性
- background : Item
- bottomInset : real
(since QtQuick.Controls 2.5 (Qt 5.12)) - focusReason : enumeration
- hoverEnabled : bool
(since QtQuick.Controls 2.1 (Qt 5.8)) - hovered : bool
(since QtQuick.Controls 2.1 (Qt 5.8)) - implicitBackgroundHeight : real
(since QtQuick.Controls 2.5 (Qt 5.12)) - implicitBackgroundWidth : real
(since QtQuick.Controls 2.5 (Qt 5.12)) - leftInset : real
(since QtQuick.Controls 2.5 (Qt 5.12)) - placeholderText : string
- placeholderTextColor : color
(since QtQuick.Controls 2.5 (Qt 5.12)) - rightInset : real
(since QtQuick.Controls 2.5 (Qt 5.12)) - topInset : real
(since QtQuick.Controls 2.5 (Qt 5.12))
信号
- pressAndHold(MouseEvent event)
- pressed(MouseEvent event)
(since QtQuick.Controls 2.1 (Qt 5.8)) - released(MouseEvent event)
(since QtQuick.Controls 2.1 (Qt 5.8))
详细说明
TextField 是一个单行文本编辑器。TextField 通过placeholder text 功能扩展了TextInput ，并添加了装饰。
| 正常状态下的文本字段。 |
| 具有活动焦点的文本字段。 |
| 禁用的文本字段。 |
TextField { placeholderText: qsTr("Enter name") }
另请参阅 TextArea 、自定义 TextField 和输入控件。
属性文档
background : Item
该属性用于保存背景项。
注意： 如果背景项没有指定明确的尺寸，它将自动跟随控件的尺寸。在大多数情况下，无需为背景项指定宽度或高度。
注： 大多数控件使用背景项的隐式尺寸来计算控件本身的隐式尺寸。如果您使用自定义项替换背景项，也应考虑为其提供合理的隐式尺寸（除非像Image 这样的项有自己的隐式尺寸）。
另请参阅 自定义 TextField。
bottomInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]
该属性用于保存背景的底部嵌入。
该属性在 QtQuick.Controls 2.5 (Qt 5.12) 中引入。
另请参阅 Control Layout 和topInset 。
focusReason : enumeration
此属性包含上次焦点改变的原因。
注意： 该属性并不表示项目是否active focus ，而是表示项目获得或失去焦点的原因。
| 常数 | 说明 |
|---|---|
Qt.MouseFocusReason | 发生了鼠标操作。 |
Qt.TabFocusReason | 按了 Tab 键。 |
Qt.BacktabFocusReason | 出现 Backtab。输入可能包括 Shift 或 Control 键，如 Shift+Tab。 |
Qt.ActiveWindowFocusReason | 窗口系统使该窗口处于活动或非活动状态。 |
Qt.PopupFocusReason | 应用程序打开/关闭了一个弹出窗口，该窗口抓住/释放了键盘焦点。 |
Qt.ShortcutFocusReason | 用户键入标签的好友快捷键 |
Qt.MenuBarFocusReason | 菜单栏占用焦点。 |
Qt.OtherFocusReason | 其他原因，通常与应用程序有关。 |
hoverEnabled : bool [since QtQuick.Controls 2.1 (Qt 5.8)]
该属性决定文本字段是否接受悬停事件。默认值为false 。
该属性在 QtQuick.Controls 2.1 (Qt 5.8) 中引入。
另请参阅 hovered 。
hovered : bool [read-only, since QtQuick.Controls 2.1 (Qt 5.8)]
该属性表示文本字段是否悬停。
该属性在 QtQuick.Controls 2.1 (Qt 5.8) 中引入。
另请参阅 hoverEnabled 。
implicitBackgroundHeight : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]
该属性包含隐式背景高度。
其值等于background ? background.implicitHeight : 0 。
该属性在 QtQuick.Controls 2.5 (Qt 5.12) 中引入。
另请参阅 implicitBackgroundWidth 。
implicitBackgroundWidth : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]
该属性用于保存隐式背景宽度。
其值等于background ? background.implicitWidth : 0 。
该属性在 QtQuick.Controls 2.5 (Qt 5.12) 中引入。
另请参阅 implicitBackgroundHeight 。
leftInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]
该属性用于保存背景的左侧嵌入。
该属性在 QtQuick.Controls 2.5 (Qt 5.12) 中引入。
另请参阅 Control Layout 和rightInset 。
placeholderText : string
该属性用于保存用户输入文本前显示在TextField 中的提示。
placeholderTextColor : color [since QtQuick.Controls 2.5 (Qt 5.12)]
该属性用于保存placeholderText 的颜色。
该属性在 QtQuick.Controls 2.5 (Qt 5.12) 中引入。
另请参阅 placeholderText 。
rightInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]
该属性用于保存背景的右侧嵌入。
该属性在 QtQuick.Controls 2.5 (Qt 5.12) 中引入。
另请参阅 Control Layout 和leftInset 。
topInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]
该属性用于保存背景的顶部嵌入。
该属性在 QtQuick.Controls 2.5 (Qt 5.12) 中引入。
另请参阅 Control Layout 和bottomInset 。
信号文档
pressAndHold(MouseEvent event)
该信号在长按时发出（延迟时间取决于平台插件）。event 参数提供了按压信息，包括按压的 x 坐标和 y 坐标，以及按压了哪个按钮。
注： 相应的处理程序是onPressAndHold 。
[since QtQuick.Controls 2.1 (Qt 5.8)] pressed(MouseEvent event)
当用户按下文本字段时会发出该信号。event 参数提供了有关按压的信息，包括按压的 x 坐标和 y 坐标，以及按压的按钮。
注： 相应的处理程序是onPressed 。
该信号在 QtQuick.Controls 2.1 (Qt 5.8) 中引入。
另请参阅 released 和pressAndHold 。
[since QtQuick.Controls 2.1 (Qt 5.8)] released(MouseEvent event)
用户释放文本字段时会发出该信号。event 参数提供了有关释放的信息，包括按下时的 x 坐标和 y 坐标，以及按下了哪个按钮。
注： 相应的处理程序是onReleased 。
该信号在 QtQuick.Controls 2.1 (Qt 5.8) 中引入。
另请参阅 pressed 和pressAndHold 。
© 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.
