Back to Qt.io
Contact Us Blog Download Qt

TextField QML Type

单行文本输入框。更多

Import Statement: import QtQuick.Controls
Inherits:

TextInput

属性

信号

  • 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 这样的项有自己的隐式尺寸）。

另请参阅 自定义文本字段。


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其他原因，通常与应用程序有关。

注意： 首选QtQuick.Controls::Control::focusReason 。


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 。

另请参阅 pressed 和released 。


[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 。


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