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 继承自TextInput ，并具备placeholder text 功能，同时增加了装饰效果。

文本框在正常状态下

处于正常状态的文本字段。

处于焦点状态且带有高亮效果的文本框

拥有活动焦点的文本字段。

处于禁用状态的文本框

一个被禁用的文本字段。
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发生了“向后 Tab”操作。此操作的输入可能包括 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 。

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