Back to Qt.io
Contact Us Blog Download Qt

TextArea QML Type

多行文本输入区。更多

Import Statement: import QtQuick.Controls
Inherits:

TextEdit

属性

附属物业

信号

  • 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))

详细说明

TextArea 是一个多行文本编辑器。TextArea 通过placeholder text 功能扩展了TextEdit ，并添加了装饰。

TextArea {
    placeholderText: qsTr("Enter description")
}

TextArea 本身不可滚动。特别是在屏幕尺寸有限的平台上，通常最好是整个应用程序页面都可以滚动。在这种可滚动页面上，不可滚动的 TextArea 可能比嵌套的可滚动控件表现得更好。不过请注意，在这种情况下，TextArea 的背景装饰会与其他可滚动内容一起滚动。

可滚动文本区域

如果您想让 TextArea 可以滚动，例如当它覆盖整个应用程序页面时，可以将它放在ScrollView 中。

ScrollView {
    id: view
    anchors.fill: parent

    TextArea {
        text: "TextArea\n...\n...\n...\n...\n...\n...\n"
    }
}

放置在ScrollView 中的 TextArea 具有以下功能：

  • 自动设置内容大小
  • 确保背景装饰保持原位
  • 夹住内容

制表符焦点

默认情况下，在 TextArea 具有active focus 时按下制表符键，控件本身就会输入一个制表符字符。要使 tab 将活动焦点传递到另一个项目，请使用所附的KeyNavigation 属性：

TextField {
    id: textField
}

TextArea {
    KeyNavigation.priority: KeyNavigation.BeforeItem
    KeyNavigation.tab: textField
}

另请参阅 TextField 、自定义 TextArea 和输入控件。

属性文档

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)]

该属性决定文本区域是否接受悬停事件。默认值为true 。

该属性在 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

该属性用于保存用户输入数值前文本区域显示的简短提示。


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 。


附加属性文档

TextArea.flickable : TextArea

该属性将文本区域附加到Flickable 。

另请参阅 ScrollBar,ScrollIndicator, 和Scrollable TextArea 。


信号文档

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.