TextField

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

Добавление виджета

Соберём пример: значение поля выводится в диалоговом окне.

Порядок действий:

1. Добавьте виджет TextField и дайте ему имя в панели свойств.
2. Добавьте кнопку и по нажатию добавьте действие Alert Dialog. В поле Message выберите From Variable > Widget State > [имя поля].

Настройка

Ширина

По умолчанию поле занимает всю доступную ширину. При необходимости её ограничивают под макет.

Многострочный ввод

По умолчанию поле однострочное: длинный текст уезжает за край, и его приходится прокручивать по горизонтали. Свойства Max Lines и Min Lines это меняют.

1. Чтобы поле росло, пока хватает места у родителя, очистите Max Lines и поставьте Min Lines = 1.
2. Чтобы поле росло до нескольких строк, а дальше прокручивалось по вертикали, задайте Max Lines нужное число (3, 5) и Min Lines = 1.

Начальное значение

Поле может открываться с заранее подставленным текстом — фиксированным или взятым из переменной.

Свойство Initial Value находится в разделе TextField Properties; значение вводится вручную либо берётся через Set from Variable.

Подпись

Подпись объясняет, что нужно ввести. Пока поле пустое и не в фокусе, Label Text занимает его целиком; как только пользователь коснулся поля, подпись уменьшается и появляется подсказка.

Задаётся в Properties Panel > Label Properties > Label Text.

У многострочного поля подпись стоит по центру. Свойство Align Label With Hint придвигает её к подсказке.

Подсказка

Подсказка внутри поля показывает, чего от пользователя ждут: «Enter Your Email Here» не оставляет вопросов.

Задаётся в Properties Panel > Hint Properties > Hint Text.

Оформление поля

За внешний вид отвечают свойства раздела Input Decoration Properties.

Цвет фона

Откройте Properties Panel > Input Decoration Properties, включите Filled и задайте Fill Color.

Рамка

1. Выделите TextField и откройте Properties Panel > Input Decoration Properties > Input Border Type.
   1. Outline — рамка вокруг всего поля.
   2. Underline — только линия снизу.
   3. None — без рамки.
2. Цвет рамки задаётся отдельно для разных состояний: Border Color, Focused Border Color и Error Border Color.
3. Толщина — свойство Border Width.
4. Скругление — свойство Border Radius. Введённое значение по умолчанию применяется ко всем углам (TL, TR, BL, BR); значок замка позволяет задать каждый угол отдельно, значок обновления сбрасывает значения.

Внутренние отступы

Content Padding задаёт расстояние между текстом и рамкой поля.

Уменьшение высоты

Свойство Dense делает поле максимально компактным по высоте.

Оформление сообщения об ошибке

Включите Custom Error Style в разделе Input Decoration Properties и задайте оформление текста.

Иконка в поле

Иконку можно поставить в начале или в конце поля — свойства Leading и Trailing Icon. Нажмите кнопку None, найдите нужную иконку и выберите её.

Размер и цвет иконки настраиваются отдельно.

Поле пароля

Откройте Properties Panel > Additional Properties и включите Password Field.

Введённый текст будет скрыт точками, а иконка Toggle Hide Password покажет его при необходимости; её размер и цвет настраиваются.

Очистка поля

Иконка очистки внутри поля стирает введённое одним нажатием.

Откройте Properties Panel > Additional Properties и включите Show Clear Field Icon; цвет и размер иконки настраиваются.

Действие Clear Text Fields/Pin Codes

Действие очищает одно или несколько полей TextField и PinCode — удобно, когда форму нужно сбросить целиком.

1. Выделите виджет — кнопку или иконку-кнопку.
2. В панели свойств выберите Actions и нажмите + Add Action.
3. Найдите действие Clear Text Fields/Pin Codes (раздел Widget/UI Interactions).
4. Отметьте виджеты TextField и PinCode, которые нужно очистить.

Автофокус

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

Откройте Properties Panel > Additional Properties и включите Autofocus.

Выделение текста

Переключатель Enable Interactive Selection отвечает за системные возможности работы с текстом: выделение долгим нажатием, меню копирования и вставки, маркеры выделения.

По умолчанию он включён. Выключают его там, где содержимое лучше не давать копировать.

Автодополнение

Автодополнение подсказывает варианты, содержащие введённый текст, — так заполняют названия стран, городов, товаров.

Откройте Properties Panel > Additional Properties и включите Autocomplete.

Дальше настройте раздел Autocomplete Properties:

1. В Autocomplete Options нажмите Add Option и введите варианты для подсказок.
2. Или нажмите Set from Variable, чтобы взять список из данных: переменной App State, ответа API, коллекции Firestore.

3. Вид списка подсказок настраивают свойства Height, Elevation, Background Color и Highlight Color (подсветка текущего варианта).
4. За текст в списке отвечают Option Text Style и Substring Style — последний подсвечивает совпавшую часть.

Подсказки автозаполнения

Свойство Auto Fill Hint подключает системное автозаполнение: операционная система предложит имя пользователя, пароль или номер карты — в зависимости от назначения поля.

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

1. Откройте Properties Panel > Additional Properties и включите Auto Fill Hint.
2. Задайте Auto Fill Hint Options — тип данных, о котором идёт речь.

Обновление страницы при вводе

На странице поиска результат должен обновляться по мере набора запроса — за это отвечает отдельное свойство.

Пример: значение поля выводится в виджете Text в реальном времени.

1. Выделите TextField, откройте Properties Panel > Additional Properties и включите Update Page On Change.
2. Задайте Update Delay (ms) — паузу после того, как пользователь перестал печатать. Значение 2000 мс означает обновление через две секунды; для примера поставим 0.
3. Выделите виджет Text и выберите Properties Panel > Set from Variable > Widget State > [имя поля]. Здесь же можно задать значение по умолчанию — то, что видно до первого ввода.

Поле только для чтения

Свойство Read Only запрещает менять содержимое поля — например, пока экран не переведён в режим редактирования.

Цвет курсора

В длинной форме цвет курсора подсказывает, куда попадёт следующий символ.

Свойство Cursor Color находится в разделе Additional Properties.

Тип клавиатуры

Под конкретный ввод — телефон, адрес почты, ссылку — удобнее показать подходящую клавиатуру.

Выделите TextField, откройте Properties Panel > Additional Properties и задайте Keyboard Type.

Маска ввода

Маска задаёт форму ввода: например, дату в виде MM/DD/YYYY, где допустимы только цифры и не больше восьми знаков.

Выделите TextField, откройте Properties Panel > Additional Properties и выберите Mask.

Если нужного формата в списке нет, выберите Custom и опишите Custom Mask: знак «#» означает цифру, «A» — букву. Примеры:

Фильтр символов

Фильтр ограничивает, какие символы вообще можно ввести. Скажем, табельный номер состоит только из букв и цифр — остальное поле просто не примет.

Выделите TextField, откройте Properties Panel > Additional Properties и задайте Filter.

Проверка значения

Значение поля проверяется, если обернуть его в виджет Form и задать правила.

Регистр

Свойство Capitalization определяет, как приводится регистр при вводе:

• None — символы остаются как набраны.
• Words — с заглавной каждое слово.
• Sentences — с заглавной начало каждого предложения.
• Characters — все символы заглавными.

Задаётся в Properties Panel > Additional Properties > Capitalization.

Кнопка на клавиатуре

Подпись на клавише подсказывает, что произойдёт дальше. В строке поиска уместна кнопка «Search», которая запускает поиск, а не переносит строку.

Доступные значения:

• Done — закрыть клавиатуру.
• Next — перейти к следующему полю.
• Previous — вернуться к предыдущему.
• Send — отправить.
• Search — искать.
• Go — перейти.

Задаётся в Properties Panel > Additional Properties > Submit Type.

Ограничение длины

Ограничение длины уместно там, где текст не должен разрастаться, — в комментариях и коротких сообщениях.

Откройте Properties Panel > Additional Properties, задайте Max Length и выберите Max Length Enforcement:

• Not Enforced — лишние символы вводятся, но появляется предупреждение.
• Enforced — всё сверх лимита отсекается.

Скрытие клавиатуры по нажатию

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

Выделите страницу и включите в панели свойств Hide Keyboard on Tap.

Событие смены фокуса

Иногда важно знать, работает ли пользователь с полем: по этому признаку включают и выключают части интерфейса или запускают анимацию.

Разберём пример: видимость виджета Text зависит от того, в фокусе ли поле.

Порядок действий:

1. У виджета Text задайте условную видимость по состоянию фокуса поля: меню Set from Variable > Widget Focus State > [имя поля].
2. У виджета TextField в колбэке On Focus Change добавьте действие, обновляющее страницу, — например, изменение переменной App State.

Триггеры поля

У виджета TextField три колбэка:

1. On Submit — пользователь закончил ввод, нажав кнопку «готово» на клавиатуре.
2. On Change — введён или удалён символ.
3. On Focus Change — поле получило или потеряло фокус.

On Submit

On Change

On Focus Change

Как добавить действие:

1. Выделите виджет TextField в дереве виджетов или на холсте.
2. В панели свойств выберите Actions и нажмите + Add Action.
3. Выберите Type of Action: On Submit, On Change или On Focus Change.
4. Добавьте нужные действия.

---

Видео

Если удобнее посмотреть: