QML-тип TextField

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

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

Свойства

Сигналы

Методы

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

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

Ниже приведен пример текстового поля:

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 TextField {
     focus: true
     text: "A single line of text"
 }

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

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 TextField {
     width: 480
     height: 300
     placeholderText: "Enter text here!"
 }

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

 TextField {
     placeholderText: "Введите имя пользователя"
     label: "Имя пользователя"
 }

Тип TextField позволяет отображать только простой текст. Для отображения форматированного текста следует использовать тип TextArea.

Проверка вводимого текста

A text field may disallow the entry of particular characters through the use of validators. В примере ниже валидатор RegExpValidator гарантирует, что в поле можно вводить только цифры и определенные цифры. Кроме того, пользователь обязан ввести не менее шести символов. (While the field does not erase its text if a smaller number of characters are entered, it will set its errorHighlight property to true, and this may be used to indicate that the field is not valid.)

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 TextField {
     width: 480
     placeholderText: "Enter phone number"
     validator: RegExpValidator { regExp: /^[0-9\+\-\#\*\ ]{6,}$/ }
     color: errorHighlight? "red" : Theme.primaryColor
     inputMethodHints: Qt.ImhNoPredictiveText
 }

Установив свойство echoMode в значение TextInput.Password, можно адаптировать внешний вид поля для ввода пароля, когда введенные символы заменяются звездочками.

См. также TextArea.

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

[read-only] acceptableInput : bool

Определяет, принимает ли валидатор validator текущее значение свойства text.

Если валидатор в свойстве validator не задан, то всегда возвращает true.

См. также validator.

autoScrollEnabled : bool

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

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

background : Component

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

color : color

Цвет текста.

cursorPosition : int

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

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

echoMode : enumeration

Определяет внешний вид вводимого текста. Данное свойство может принимать одно из значений:

  • TextInput.Normal — введенный текст отображается как есть (значение по умолчанию);
  • TextInput.Password — вместо введенного текста отображаются звездочки;
  • TextInput.PasswordEchoOnEdit — когда текстовое поле в фокусе, введенный текст отображается как есть; во всех остальных случаях вместо введенного текста отображаются звездочки;
  • TextInput.NoEcho — введенный текст не отображается.

errorHighlight : bool

Истинно, если текстовое поле содержит недопустимое значение. С помощью данного свойства можно задавать соответствующее визуальное оформление текстового поля.

По умолчанию равно инвертированному значению свойства acceptableInput.

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

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

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

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

  • TextInput.AlignLeft — выравнивание по левому краю (по умолчанию);
  • TextInput.AlignRight — выравнивание по правому краю;
  • TextInput.AlignHCenter — выравнивание по центру;
  • TextInput.AlignJustify — выравнивание по ширине.

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

inputMethodHints : Qt::InputMethodHints

Содержит настройки экранной клавиатуры, адаптирующие ее под тип вводимых данных. Экранная клавиатура меняет свой вид в зависимости от значения этого свойства. The hints may be OR'ed together:

 TextField {
     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.

labelVisible : bool

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

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

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

См. также label.

placeholderColor : string

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

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

См. также placeholderText.

placeholderText : string

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

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

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

readOnly : bool

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

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

selectedText : string

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

selectionEnd : int

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

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

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

selectionMode : enumeration

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

  • TextInput.SelectCharacters — выделение осуществляется по отдельным символам (значение по умолчанию);
  • TextInput.SelectWords — выделение осуществляется по словам.

selectionStart : int

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

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

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

softwareInputPanelEnabled : bool

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

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

text : string

Отображаемый текст.

textLeftMargin : real

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

По умолчанию равно значению свойства textMargin.

textMargin : real

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

This can be overridden by textLeftMargin and textRightMargin.

textRightMargin : real

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

По умолчанию равно значению свойства textMargin.

[read-only] textVerticalCenterOffset : real

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

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 Page {
     TextField {
         id: textField
     }

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

validator : Validator

Валидатор — объект, который выполняет проверку введенного текста. По умолчанию в текстовом поле нет валидатора.

Валидатор используется для фильтрации введенного текста и для предотвращения ввода нежелательных символов в тексте. В примере ниже валидатор IntValidator гарантирует, что пользователь сможет ввести в текстовом поле только цифры в диапазоне от 1 до 10:

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 TextField {
     width: 480
     placeholderText: "Enter phone number"
     validator: IntValidator { bottom: 1; top: 10 }
 }

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

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(int position)

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

select(int start,  int end)

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

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

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

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

selectAll()

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

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

selectWord()

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

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