QML-тип TextField

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

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

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

Свойства

acceptableInput : bool
autoScrollEnabled : bool
background : Component
backgroundStyle : enumeration
color : color
cursorPosition : int
description : string
echoMode : enumeration
errorHighlight : bool
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
strictValidation : bool
text : string
textLeftMargin : real
textMargin : real
textRightMargin : real
textVerticalCenterOffset : real
validator : Validator
wrapMode : enumeration

Сигналы

onClicked(variant mouse)
onPressAndHold(variant mouse)

Методы

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

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

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

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

import QtQuick 2.2
import Sailfish.Silica 1.0

TextField {
    focus: true
    text: "Одна строка текста"
}

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

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

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

import QtQuick 2.2
import Sailfish.Silica 1.0

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

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

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

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

Текстовое поле может запрещать ввод определенных символов с помощью валидаторов. В примере ниже валидатор RegExpValidator гарантирует, что в поле можно вводить только цифры и определённые цифры. Кроме того, пользователь обязан ввести не менее шести символов. (Хотя поле не стирает свой текст, если вводится меньшее количество символов, оно устанавливает для своего свойства errorHighlight значение true, и это может использоваться, чтобы указать, что поле недействительно.)

В отличие от элемента QML TextInput, Silica TextField по умолчанию позволяет пользователю вводить недопустимые символы в TextField. Однако любое поле TextField, содержащее недопустимый ввод, по-прежнему будет считаться недопустимым и по-прежнему будет выделяться цветом ошибки.

import QtQuick 2.2
import Sailfish.Silica 1.0

TextField {
    placeholderText: "Номер телефона"
    validator: RegExpValidator { regExp: /^[0-9\+\-#\*\ ]{3,}$/ }
    inputMethodHints: Qt.ImhNoPredictiveText
}

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

import Sailfish.Silica 1.0

TextField {
    acceptableInput: text.length > 6
}

Регулярные выражения также могут использоваться для определения шаблонов проверки либо с помощью Qt-компонента RegExpValidator, либо с использованием объекта RegExp.

import Sailfish.Silica 1.0

TextField {
    property var regExp: new RegExp(/^[0-9\+\-#\*\ ]{3,}$/)
    acceptableInput: regExp.test(text)
}

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

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

См. также TextArea.

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

[read-only] acceptableInput : bool

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

import Sailfish.Silica 1.0

TextField {
    acceptableInput: text.length > 6
}

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

См. также validator.

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.

echoMode : enumeration

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

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

errorHighlight : bool

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

По умолчанию используется обратное значение acceptableInput, кроме случаев, когда пользователь ещё не изменил содержимое TextField.

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

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

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, description и labelVisible.

labelVisible : bool

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

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

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

См. также label.

leftItem : Item

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

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

import QtQuick 2.2
import Sailfish.Silica 1.0

TextField {
    label: "Email"
    leftItem: Icon {
        source: "image://theme/icon-m-mail"
    }
}

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

TextField {
    id: clearableField
    rightItem: IconButton {
        onClicked: clearableField.text = ""

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

Если правый элемент не определён, а в errorHighlight установлено истинное значение, свойство будет неявно изменено для отображения иконки ошибки.

selectedText : string

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

selectionEnd : int

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

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

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

selectionMode : enumeration

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

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

selectionStart : int

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

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

softwareInputPanelEnabled : bool

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

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

strictValidation : bool

Переключает поведение проверки Qt по умолчанию. Если установлено значение true, пользователи не могут вводить символы, которые валидатор считает недопустимыми. Если установлено значение false, TextField покажет ошибку, но позволит пользователю вводить недопустимые символы. Строгая проверка часто бывает слишком строгой, блокируя составление текста, предсказание текста и вставку из буфера обмена, даже если один символ неверен.

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

text : string

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

textLeftMargin : real

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

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

textMargin : real

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

Его можно изменить с помощью textLeftMargin и textRightMargin.

textRightMargin : real

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

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

[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.6
import Sailfish.Silica 1.0

TextField {
    placeholderText: "Одна цифра"
    validator: IntValidator { bottom: 0; top: 9 }
}

См. также acceptableInput и strictValidation.

wrapMode : enumeration

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

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

Значение по умолчанию ⁠— TextInput.NoWrap.

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

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().