Ask the assistant

0/400

Your question is processed by an AI service and kept to improve answers. Do not enter personal data.

TextField

This page has not been translated into English yet. The Russian original is below.

Простое текстовое поле ввода без привязки к форме. Когда нужны проверка значений и отправка формы — берите TextFormField ; для поиска, чата и любого поля, значение которого живёт в переменной, TextField проще.

Тип: multi-child (дети — только элементы-вставки декорации, см. ниже)

TextField
  #decoration labelText:"Почта" hintText:"you@example.com"

Параметры

Параметр	Тип	Default	Описание
`value`	переменная	—	Двусторонняя привязка: `value:$query` — ввод пишет в переменную, изменение переменной переписывает текст
`initialValue`	string	—	Начальный текст без привязки
`onChanged`	callback	—	Вызывается при каждом изменении, получает текст
`onSubmitted`	callback	—	Вызывается, когда ввод закончен (Enter, кнопка клавиатуры)
`obscureText`	bool	false	Скрывать ввод (пароль)
`obscuringCharacter`	string	•	Символ маскировки
`maxLines`	int	1	Максимум строк; больше 1 — многострочное поле
`minLines`	int	—	Сколько строк видно сразу
`expands`	bool	false	Растянуть поле на всё место родителя
`maxLength`	int	—	Максимум символов
`readOnly`	bool	false	Только чтение
`enabled`	bool	—	`false` — поле отключено
`autofocus`	bool	false	Фокус сразу при показе
`autocorrect`	bool	true	Исправление опечаток
`enableSuggestions`	bool	true	Подсказки ввода
`textAlign`	string	start	Выравнивание текста
`textCapitalization`	string	none	`none` , `words` , `sentences` , `characters`
`textInputAction`	string	—	Какая клавиша вместо Enter на телефоне: `next` , `done` , `go` , `send` , `search`
`cursorColor`	color	—	Цвет курсора
`submitOnEnter`	bool	false	Многострочное поле отправляет по Enter, а Shift+Enter переносит строку (только приложение)
`canRequestFocus`	bool	true	Может ли поле получить фокус

Подсказка в пустом поле и подпись задаются в #decoration ( hintText: , labelText: ), а не параметром самого поля.

Вложенные структуры

`#decoration`

Оформление поля: подсказка, подпись, подсказка под полем, ошибка, иконки, рамка. Формат тот же, что у TextFormField .

TextField
  #decoration labelText:"Имя" hintText:"Как вас зовут"
    #enabledBorder outline
      #borderRadius circular 8
      #borderSide color:#585593 width:1
    #focusedBorder outline
      #borderRadius circular 8
      #borderSide color:#6C63FF width:2

`#style`

Стиль вводимого текста — размер, цвет, начертание (как у Text ).

TextField
  #style fontSize:18 color:#FFFFFF
  #decoration hintText:"Введите текст"

`#keyboardType`

Какую клавиатуру показывать: text , multiline , number , phone , datetime , emailAddress , url , visiblePassword , name , streetAddress , webSearch .

TextField
  #keyboardType emailAddress
  #decoration labelText:"Почта"

Примеры

Поле поиска с очисткой

value:$query держит поле и переменную в согласии в обе стороны, поэтому кнопка может очистить текст, просто записав пустую строку:

@query:""
Row spacing:8
  Expanded
    TextField value:$query
      #decoration hintText:"Поиск…"
  Button onPressed:{query = ""}
    Icon close

Реакция на каждое изменение

@echo:""
Column spacing:8
  TextField onChanged:(v){echo = v}
    #decoration labelText:"Имя"
  Text $"Вы ввели: ${echo}"

Вход: логин и пароль

На телефоне без textInputAction в логине нечем перейти к паролю:

@email:""
@password:""
Column spacing:12
  TextField value:$email textInputAction:next
    #keyboardType emailAddress
    #decoration labelText:"Почта"
  TextField value:$password obscureText:true textInputAction:done
    #decoration labelText:"Пароль"

Многострочный комментарий

@comment:""
TextField value:$comment maxLines:6 minLines:3
  #decoration labelText:"Комментарий" hintText:"Введите текст…"

Различия между приложением и сайтом

На сайте поле — обычный <input> (при maxLines больше 1 — <textarea> ).

Работают: value:$переменная , initialValue , #decoration (подсказка, подпись, рамка), onChanged , onSubmitted (по Enter), obscureText , maxLines / minLines , maxLength , readOnly , enabled , autofocus , textCapitalization , textInputAction , #keyboardType , #autofillHints , #style , textAlign , cursorColor .
Не работают на сайте: submitOnEnter , #keys , а также id , token , tokenStart , focused (механика поля-композитора с подсказками). Многострочное поле на сайте не отправляется по Enter.
Подпись labelText поднимается над полем при вводе, как в приложении.

Bad practices

Подсказка параметром поля

// BAD — hintText не параметр TextField: подсказка не появится
TextField hintText:"Введите имя"

// GOOD — подсказка в #decoration
TextField
  #decoration hintText:"Введите имя"

Best practices

Значение — в переменную, а не в обработчик. value:$query короче и надёжнее, чем onChanged:(v){query = v} : он ещё и очищает поле, когда меняется переменная.
Две и больше полей подряд — всегда с textInputAction ( next , последнему — done ).
Правила проверки значения (обязательное, e-mail, минимальная длина) — не у TextField , а у TextFormField в #validators .