QML-тип TextArea

Отображает несколько строк для редактирования простого текста. Подробнее…

Строка импорта:	`import Sailfish.Silica 1.0`
Наследуется от:	FocusScope

Список всех членов класса, включая унаследованные

Свойства

autoScrollEnabled : bool
background : Component
backgroundStyle : enumeration
color : color
cursorPosition : int
description : string
font.bold : bool
font.capitalization : enumeration
font.family : string
font.italic : bool
font.letterSpacing : real
font.pixelSize : int
font.pointSize : real
font.strikeout : bool
font.underline : bool
font.weight : enumeration
font.wordSpacing : real
horizontalAlignment : enumeration
inputMethodHints : Qt::InputMethodHints
label : string
labelVisible : bool
leftItem : Item
placeholderColor : string
placeholderText : string
readOnly : bool
rightItem : Item
selectedText : string
selectionEnd : int
selectionMode : enumeration
selectionStart : int
softwareInputPanelEnabled : bool
text : string
textLeftMargin : real
textMargin : real
textRightMargin : real
textVerticalCenterOffset : real
verticalAlignment : enumeration
wrapMode : enumeration

Сигналы

onClicked(variant mouse)
onPressAndHold(variant mouse)

Методы

copy()
cut()
deselect()
forceActiveFocus()
paste()
int positionAt(x, y)
rect positionToRectangle(position)
select(start, end)
selectAll()
selectWord()

Подробное описание

Тип TextArea реализует область для редактирования многострочного текста.

Ниже приведён пример текстовой области:

import QtQuick 2.2
import Sailfish.Silica 1.0

TextArea {
    focus: true
    text: "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
        incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
        exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."
}

Высота TextArea обычно увеличивается, когда пользователь вводит больше текста, и когда в качестве родительского используется элемент с прокруткой, если текст сразу не помещается на дисплее устройства.

Отображаемый текст можно отформатировать с помощью свойств font и color, хотя их не нужно настраивать, чтобы следовать стилю платформы. Выравнивание текста контролируется с помощью свойств horizontalAlignment и verticalAlignment, но обычно достаточно позволить тексту иметь естественное выравнивание. Перенос текста управляется свойством wrapMode.

Текстовая метка label отображается под текстовой областью, если значение свойства text не пустое. Обычно используется следующее соглашение по наименованию данных элементов:

TextArea {
    label: "Имя пользователя"
}

В текстовой области изначально может отображаться текст заполнителя, который автоматически пропадёт после начала ввода текста пользователем. Текст заполнителя задаётся с помощью свойства placeholderText:

import QtQuick 2.2
import Sailfish.Silica 1.0

TextArea {
    label: "Имя пользователя"
    placeholderText: "Имя пользователя"
}

По умолчанию значение placeholderText привязано к тексту в свойстве label, поэтому в большинстве случаев достаточно определить label.

См. также TextField.

Описание свойств

autoScrollEnabled : bool

Определяет, будет ли текстовая область при получении фокуса и вводе текста автоматически прокручивать свой родительский элемент Flickable для обеспечения видимости содержимого.

Значение по умолчанию: true.

background : Component

Элемент Component, используемый для отрисовки фона текстовой области.

backgroundStyle : enumeration

Стиль, используемый для фона редактора.

Возможные значения:

TextEditor.UnderlineBackground — текстовый редактор отображается с подчёркиванием.
TextEditor.FilledBackground — текстовый редактор отображается с заполненным фоном.
TextEditor.NoBackground — фон для редактора не отображается.

Значение по умолчанию — фон с подчёркиванием.

color : color

Цвет текста.

cursorPosition : int

Положение курсора в тексте.

Значение может лежать в диапазоне от 0 до числа символов в свойстве text.

description : string

Более длинный текст, отображаемый под label, например, текст подсказки или сообщение об ошибке, которое содержит некоторые дополнительные сведения о том, какой тип ввода ожидается.

Значение по умолчанию: пустая строка.

См. также text, label и placeholderText.

font.bold : bool

При истинном значении текст отрисовывается полужирным.

font.capitalization : enumeration

Содержит стили форматирования, применяемые к регистру отображаемого текста. Данное свойство может принимать одно из значений:

Font.MixedCase — регистр текста не изменяется (значение по умолчанию);
Font.AllUppercase — весь текст отображается в верхнем регистре (прописными);
Font.AllLowercase — весь текст отображается в нижнем регистре (строчными);
Font.SmallCaps — текст отображается уменьшенными заглавными буквами (малыми прописными);
Font.Capitalize — первая буква в каждом слове отображается в верхнем регистре (прописными).

font.family : string

Название семейства шрифтов, которое используется для отображения текста.

font.italic : bool

При истинном значении текст отрисовывается курсивом.

font.letterSpacing : real

Межбуквенная разрядка (трекинг) в отображаемом тексте (в пикселях).

Указание положительных значений делает текст более разреженным, указание отрицательных значений уплотняет текст.

font.pixelSize : int

Размер отображаемого текста в пикселях.

font.pointSize : real

Размер отображаемого текста в пунктах.

font.strikeout : bool

При истинном значении текст отрисовывается зачёркнутым.

font.underline : bool

При истинном значении текст отрисовывается подчёркнутым.

font.weight : enumeration

Содержит значение веса, применяемое к отображаемом тексту.

Данное свойство может принимать одно из значений (от самого легкого к самому тяжелому):

Font.Light;
Font.Normal (значение по умолчанию);
Font.DemiBold;
Font.Bold;
Font.Black.

font.wordSpacing : real

Интервал между словами в отображаемом тексте (в пикселях).

Указание положительных значений увеличивает стандартный интервал между словами, указание отрицательных значений уменьшает его.

horizontalAlignment : enumeration

Выравнивание текста по горизонтали и по вертикали в пределах ширины и высоты текстовой области.

По умолчанию выравнивание текста соответствует направлению письма, принятого в языке. Например, если текст читается слева направо, то выравниваться он будет по левому краю.

Свойство horizontalAlignment может принимать следующие значения:

TextEdit.AlignLeft (по умолчанию);
TextEdit.AlignRight;
TextEdit.AlignHCenter;
TextEdit.AlignJustify.

Свойство verticalAlignment может принимать следующие значения:

TextEdit.AlignTop (по умолчанию);
TextEdit.AlignBottom;
TextEdit.AlignVCenter.

Если прикрепляемое свойство LayoutMirroring::enabled используется для зеркального отражения компоновки приложения, то это также влияет на горизонтальное выравнивание текста. При этом значение свойства horizontalAlignment останется неизменным. Узнать используемое на устройстве выравнивание по горизонтали для типа TextArea можно с помощью свойства LayoutMirroring::enabled.

inputMethodHints : Qt::InputMethodHints

Содержит настройки экранной клавиатуры, адаптирующие её под тип вводимых данных. Экранная клавиатура меняет свой вид в зависимости от значения этого свойства. Подсказки можно комбинировать с помощью OR:

TextArea {
    inputMethodHints: Qt.ImhEmailCharactersOnly | Qt.ImhNoPredictiveText
}

Для экранной клавиатуры поддерживаются следующие методы ввода:

Qt.ImhDialableCharactersOnly — телефонные номера;
Qt.ImhDigitsOnly — целые числа;
Qt.ImhEmailCharactersOnly — поле ввода адреса электронной почты;
Qt.ImhFormattedNumbersOnly — дробные числа;
Qt.ImhNoPredictiveText — отключить предиктивный ввод текста;
Qt.ImhUrlCharactersOnly — символы, используемые для ввода URL;
Qt.ImhNoAutoUppercase — отключить автоматическое переключение в верхний регистр окончания ввода предложения.

См. также softwareInputPanelEnabled.

label : string

Текст метки, которая отображается под текстовой областью, если значение свойства text не пустое. Данный элемент полезно использовать для пояснения к информации, вводимой в текстовой области. Обычно используется в сочетании со свойством placeholderText.

Значение по умолчанию: пустая строка.

См. также text, placeholderText, labelVisible, и description.

labelVisible : bool

Определяет, будет ли текстовая метка label отображаться под текстовой областью, если значение свойства text не пустое.

Установка значения в false скроет метку и освободит зарезервированное под неё пространство.

Значение по умолчанию: true.

См. также label.

leftItem : Item

Следует использовать leftItem, чтобы вставить элемент в левую часть отображаемого текста. Наиболее распространённый вариант использования — добавить иконку, которая помогает пользователю идентифицировать поле.

Следует обратить внимание, что левый элемент центрируется по вертикали до области, равной области однострочного текста, тогда как правый элемент центрируется по вертикали относительно первой строки видимого текста.

import QtQuick 2.2
import Sailfish.Silica 1.0

TextArea {
    label: "Заметка"
    leftItem: Icon {
        source: "image://theme/icon-m-note"
    }
}

placeholderColor : string

Цвет замещающего текста, задаваемого в свойстве placeholderText.

По умолчанию значение цвета равно Theme.secondaryHighlightColor, когда текстовая область находится в фокусе, и Theme.secondaryColor — в остальных случаях.

См. также placeholderText.

placeholderText : string

Замещающий текст, отображаемый при пустом значении свойства text. Данный элемент полезно использовать для обозначения информации, которую следует ввести в текстовой области. Обычно используется в сочетании со свойством label.

По умолчанию текстовое значение подсказки привязано к текстовому значению label.

См. также text, placeholderColor, label и description.

readOnly : bool

Определяет, можно ли изменять содержимое текстовой области.

При истинном значении пользователь не может редактировать текст.

rightItem : Item

Следует использовать rightItem, чтобы вставить элемент справа от отображаемого текста. Наиболее распространённый вариант использования — ввести действие, например, очистить текст, в виде кнопки со значком рядом с текстовой областью.

Следует обратить внимание, что правый элемент центрируется по вертикали относительно первой строки видимого текста, тогда как левый элемент центрируется по вертикали относительно области, равной области однострочного текста.

import QtQuick 2.2
import Sailfish.Silica 1.0

TextArea {
    id: clearableArea
    rightItem: IconButton {
        onClicked: clearableArea.text = ""

        width: icon.width
        height: icon.height
        icon.source: "image://theme/icon-m-input-clear"
        opacity: clearableArea.text.length > 0 ? 1.0 : 0.0
        Behavior on opacity { FadeAnimation {} }
    }
}

selectedText : string

Выделенный в данный момент текст.

selectionEnd : int

Позиция конца выделенного текста.

Это свойство только для чтения. Пользователь может изменять выделение путём двойного касания текста и перемещения маркеров выделения текста. Выделение можно задать программно с помощью методов select(), selectAll() или selectWord().

См. также select() и selectedText.

selectionMode : enumeration

Определяет режим выделения текста путём перетаскивания с помощью соответствующих маркеров. Данное свойство может принимать одно из значений:

TextEdit.SelectCharacters ⁠— выделение посимвольно. (значение по умолчанию);
TextEdit.SelectWords ⁠— выделение по словам.

selectionStart : int

Позиция начала выделенного текста.

См. также select() и selectedText.

softwareInputPanelEnabled : bool

Определяет, будет ли отображаться виртуальная клавиатура при получении фокуса текстовым полем.

Значение по умолчанию: true.

text : string

Отображаемый текст. В отличие от текстовых редакторов Qt, включает текст перед редактированием.

textLeftMargin : real

Отступ от левой границы отображаемого текста до границ текстовой области.

По умолчанию свойство привязано к textMargin, но также принимает во внимание ширину leftItem, если она определена. Левый элемент должен иметь ненулевую непрозрачность, чтобы он учитывался по умолчанию.

textMargin : real

Отступ от левой и правой границ отображаемого текста до границ текстовой области.

textRightMargin : real

Отступ от правой границы отображаемого текста до границ текстовой области.

По умолчанию свойство привязано к textMargin, но также принимает во внимание ширину rightItem, если она определена. Правый элемент должен иметь ненулевую непрозрачность, чтобы он учитывался по умолчанию.

[read-only] textVerticalCenterOffset : real

Смещение по вертикали от верхней границы текстовой области до центра первой строки текста в текстовой области. Данное свойство можно использовать для выравнивания других элементов, например, значков относительно области редактирования:

import QtQuick 2.2
import Sailfish.Silica 1.0

Page {
    TextArea {
        id: textArea
    }

    Image {
        anchors {
            left: textArea.right
            verticalCenter: textArea.top
            verticalCenterOffset: textArea.textVerticalCenterOffset
        }
    }
}

verticalAlignment : enumeration

Выравнивание текста по горизонтали и по вертикали в пределах ширины и высоты текстовой области.

Свойство horizontalAlignment может принимать следующие значения:

TextEdit.AlignLeft (по умолчанию);
TextEdit.AlignRight;
TextEdit.AlignHCenter;
TextEdit.AlignJustify.

Свойство verticalAlignment может принимать следующие значения:

TextEdit.AlignTop (по умолчанию);
TextEdit.AlignBottom;
TextEdit.AlignVCenter.

Если прикрепляемое свойство LayoutMirroring::enabled используется для зеркального отражения компоновки приложения, то это также влияет на горизонтальное выравнивание текста. При этом значение свойства horizontalAlignment останется неизменным. Узнать используемое на устройстве выравнивание по горизонтали для типа TextArea можно с помощью свойства LayoutMirroring::enabled.

wrapMode : enumeration

Режим переноса текста при заполнении им ширины текстовой области. Текст будет переноситься только если для текстовой области явно задана ширина.

TextEdit.NoWrap — перенос текста не выполняется. Если в тексте недостаточно переносов строк для отображения текста, то значение унаследованного свойства implicitWidth будет больше заданной ширины текстовой области;
TextEdit.WordWrap — перенос выполняется только по границам слов. Если длина слова достаточно большая, то значение унаследованного свойства implicitWidth будет больше заданной ширины текстовой области;
TextEdit.WrapAnywhere — перенос выполняется в любом месте строки, даже если это происходит где-либо в пределах границ слова.
TextEdit.Wrap — по возможности, перенос выполняется по границам слова; если это невозможно, то перенос выполняется в подходящем месте строки, даже если это происходит где-либо в пределах границ слова..

Значение по умолчанию ⁠— TextEdit.Wrap.

Описание сигналов

onClicked(variant mouse)

Обработчик данного сигнала вызывается при касании (щелчке) текстовой области. Под щелчком в данном случае подразумевается нажатие и последующее отпускание текстовой области. Параметр mouse содержит в себе информацию о щелчке.

onPressAndHold(variant mouse)

Обработчик данного сигнала вызывается при нажатии и удерживании текстовой области. Параметр mouse содержит в себе информацию о нажатии.

Описание методов

copy()

Копирует выделенный текст в буфер обмена.

См. также select() и paste().

cut()

Удаляет выделенный текст и помещает его в буфер обмена.

См. также select() и paste().

deselect()

Снимает выделение с текста. Сам текст при этом не изменяется.

См. также select().

forceActiveFocus()

Принудительно устанавливает фокус на текстовой области.

При истинном значении унаследованного свойства Item::activeFocus элемент принимает ввод с виртуальной клавиатуры.

paste()

Если в текстовой области имеется выделенный текст, то он заменяется содержимым буфер обмена; в остальных случаях метод вставляет содержимое буфера обмена в текст в позицию курсора cursorPosition.

int positionAt(x, y)

Возвращает позицию символа, ближайшую к точке с координатами (x, y).

rect positionToRectangle(position)

Возвращает координаты и размеры прямоугольника курсора, расположенного в тексте в позиции position.

select(start, end)

Выделяет текст от начального положения курсора start до конечного положения курсора end.

Если заданные начало и конец выделения находятся вне диапазона допустимых значений, то выделение не изменяется.

После вызова метода select(), значение свойства selectionStart станет меньше, а значение свойства selectionEnd станет большим (вне зависимости от порядка передачи аргументов в данный метод).

См. также selectionStart, selectionEnd и selectedText.

selectAll()

Выделяет весь текст.

См. также select().

selectWord()

Выделяет слово, ближайшее к положению курсора cursorPosition.

См. также select().