Как настроить текстовые поля

TextField позволяет пользователям вводить и изменять текст. Существует два типа текстовых полей: текстовые поля на основе статуса и текстовые поля на основе значения. Выберите тип контента:

Мы рекомендуем использовать текстовые поля на основе состояний, поскольку они обеспечивают более полный и надежный подход к управлению состоянием TextField. В таблице ниже описаны различия между этими типами текстовых полей и основные преимущества текстовых полей на основе состояний.

Функция

Текстовые поля на основе ценности

Текстовые поля на основе статуса

Льготы, предоставляемые штатом

Управление состоянием

Обновляет состояние текстового поля с помощью обратного вызова onValueChange. Вы несете ответственность за обновление value в своем штате на основе изменений, сообщенных onValueChange.

Явно использует объект TextFieldState для управления состоянием ввода текста (значением, выделением и композицией). Это состояние можно запомнить и поделиться им.
  • Удален обратный вызов onValueChange, который не позволяет вводить асинхронное поведение.
  • Состояние сохраняется при повторной композиции, изменении конфигурации и завершении процесса.

Визуальные преобразования

Использует VisualTransformation для изменения внешнего вида текста. Обычно это позволяет отформатировать входные и выходные данные за один шаг.

Использует InputTransformation для изменения введенных пользователем данных до того, как они будут сохранены в состоянии, и OutputTransformation для форматирования содержимого текстового поля без изменения базовых данных состояния.
  • Вам больше не нужно указывать сопоставление смещения между исходным текстом и преобразованным текстом с помощью OutputTransformation.

Ограничения на количество строк

Принимает значения singleLine: Boolean, maxLines: Int и minLines: Int для управления количеством строк.

Использует lineLimits: TextFieldLineLimits, чтобы задать минимальное и максимальное количество строк, которые может занимать текстовое поле.
  • Устраняет неоднозначность при настройке ограничений на количество строк, предоставляя параметр lineLimits типа TextFieldLineLimits.

Защищенное текстовое поле

Н/Д

SecureTextField – это composable-функция, созданная на основе текстовых полей с сохранением состояния для ввода пароля.
  • Позволяет оптимизировать безопасность на уровне кода и поставляется с готовым интерфейсом с textObfuscationMode.

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

Как реализовать TextField

Существует два уровня реализации TextField:

  1. TextField – это реализация Material Design. Мы рекомендуем использовать этот вариант, так как он соответствует рекомендациям Material Design:
  2. BasicTextField позволяет пользователям редактировать текст с помощью аппаратной или виртуальной клавиатуры, но не предоставляет никаких дополнительных элементов, например подсказок или заполнителей.

TextField(
    state = rememberTextFieldState(initialText = "Hello"),
    label = { Text("Label") }
)

Редактируемое текстовое поле, содержащее слово 

OutlinedTextField(
    state = rememberTextFieldState(),
    label = { Text("Label") }
)

Редактируемое текстовое поле с фиолетовой рамкой и ярлыком.

Стиль TextField

У TextField и BasicTextField много общих параметров для настройки. Полный список для TextField доступен в исходном коде TextField. Ниже приведен неполный список полезных параметров:

  • textStyle
  • lineLimits

TextField(
    state = rememberTextFieldState("Hello\nWorld\nInvisible"),
    lineLimits = TextFieldLineLimits.MultiLine(maxHeightInLines = 2),
    placeholder = { Text("") },
    textStyle = TextStyle(color = Color.Blue, fontWeight = FontWeight.Bold),
    label = { Text("Enter text") },
    modifier = Modifier.padding(20.dp)
)

Многострочное текстовое поле с двумя редактируемыми строками и ярлыком

Если в вашем дизайне используются элементы Material TextField или OutlinedTextField, мы рекомендуем использовать свойство TextField вместо BasicTextField. Однако BasicTextField следует использовать при создании макетов, которым не нужны декоративные элементы из спецификации Material.

Как стилизовать изображения с помощью Brush API

Для более сложного оформления в TextField можно использовать Brush API. В следующем разделе рассказывается, как использовать кисть для добавления цветного градиента к входным данным TextField.

Подробнее о том, как использовать Brush API для стилизации текста…

Как реализовать цветные градиенты с помощью TextStyle

Чтобы при вводе текста в TextField использовался цветной градиент, задайте нужную кисть в качестве TextStyle для TextField. В этом примере мы используем встроенную кисть с linearGradient, чтобы посмотреть на эффект радужного градиента при вводе текста в TextField.

val brush = remember {
    Brush.linearGradient(
        colors = listOf(Color.Red, Color.Yellow, Color.Green, Color.Blue, Color.Magenta)
    )
}
TextField(
    state = rememberTextFieldState(), textStyle = TextStyle(brush = brush)
)

Текст, который вводится в текстовое поле, с эффектом радужного градиента.
Рисунок 1. Радужный градиентный эффект для контента TextField.

Как управлять состоянием текстового поля

TextField использует специальный класс для хранения состояния, который называется TextFieldState и предназначен для контента и выбора. TextFieldState можно разместить в любом месте вашей архитектуры. TextFieldState предоставляет два основных свойства:

  • initialText – содержимое TextField.
  • initialSelection – указывает, где находится курсор или выделенный фрагмент.

TextFieldState отличается от других подходов, например обратного вызова onValueChange, тем, что TextFieldState полностью инкапсулирует весь поток входных данных. Это включает использование правильных структур данных, встроенных фильтров и форматов, а также синхронизацию всех изменений, поступающих из разных источников.

Вы можете использовать TextFieldState(), чтобы поднять состояние в TextField. Для этого рекомендуем использовать функцию rememberTextFieldState(). rememberTextFieldState() создает экземпляр TextFieldState в вашей composable-функции, обеспечивает сохранение объекта состояния и предоставляет встроенные функции сохранения и восстановления:

val usernameState = rememberTextFieldState()
TextField(
    state = usernameState,
    lineLimits = TextFieldLineLimits.SingleLine,
    placeholder = { Text("Enter Username") }
)

rememberTextFieldState может иметь пустой параметр или начальное значение, переданное для представления значения текста при инициализации. Если при последующей рекомпозиции передается другое значение, состояние не обновляется. Чтобы изменить состояние после инициализации, вызовите методы редактирования в TextFieldState.

TextField(
    state = rememberTextFieldState(initialText = "Username"),
    lineLimits = TextFieldLineLimits.SingleLine,
)

Поле TextField с текстом "Имя пользователя" внутри.
Рисунок 2. TextField с текстом "Имя пользователя".

Как изменить текст с помощью TextFieldBuffer

Объект TextFieldBuffer представляет собой редактируемый текстовый блок, похожий по функции на объект StringBuilder. Он содержит как текстовый контент, так и информацию о выделенном фрагменте.

Область видимости TextFieldBuffer часто используется в функциях, таких как TextFieldState.edit, InputTransformation.transformInput или OutputTransformation.transformOutput. В этих функциях можно читать или обновлять TextFieldBuffer. После этого изменения либо сохраняются в TextFieldState, либо передаются в конвейер отрисовки в случае с OutputTransformation.

Вы можете использовать стандартные функции редактирования, такие как append, insert, replace или delete, чтобы изменить содержимое буфера. Чтобы изменить состояние выбора, задайте переменную selection: TextRange или используйте вспомогательные функции, например placeCursorAtEnd или selectAll. Выделенный фрагмент обозначается символом TextRange, где начальный индекс включен, а конечный – нет. Символ TextRange с одинаковыми начальным и конечным значениями, например (3, 3), обозначает положение курсора без выделенных символов.

val phoneNumberState = rememberTextFieldState("1234567890")

TextField(
    state = phoneNumberState,
    keyboardOptions = KeyboardOptions(
        keyboardType = KeyboardType.Phone
    ),
    inputTransformation = InputTransformation.maxLength(10).then {
        if (!asCharSequence().isDigitsOnly()) {
            revertAllChanges()
        }
    },
    outputTransformation = OutputTransformation {
        if (length > 0) insert(0, "(")
        if (length > 4) insert(4, ")")
        if (length > 8) insert(8, "-")
    }
)

Как изменить текст в приложении "TextFieldState"

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

  • edit: позволяет редактировать содержимое состояния и предоставляет TextFieldBuffer функций, чтобы вы могли использовать такие методы, как insert, replace, append и т. д.

    // Initial textFieldState text passed in is "I love Android"
// textFieldState.text : I love Android
// textFieldState.selection: TextRange(14, 14)
textFieldState.edit { insert(14, "!") }
// textFieldState.text : I love Android!
// textFieldState.selection: TextRange(15, 15)
textFieldState.edit { replace(7, 14, "Compose") }
// textFieldState.text : I love Compose!
// textFieldState.selection: TextRange(15, 15)
textFieldState.edit { append("!!!") }
// textFieldState.text : I love Compose!!!!
// textFieldState.selection: TextRange(18, 18)
textFieldState.edit { selectAll() }
// textFieldState.text : I love Compose!!!!
// textFieldState.selection: TextRange(0, 18)

  • setTextAndPlaceCursorAtEnd: очищает текущий текст, заменяет его указанным текстом и устанавливает курсор в конце.

    textFieldState.setTextAndPlaceCursorAtEnd("I really love Android")
// textFieldState.text : I really love Android
// textFieldState.selection : TextRange(21, 21)

  • clearText – очищает весь текст.

    textFieldState.clearText()
// textFieldState.text :
// textFieldState.selection : TextRange(0, 0)

Информацию о других функциях TextFieldState можно найти в справочнике по TextFieldState.

Изменение введенных пользователем данных

В следующих разделах описано, как изменить ввод данных пользователем. Преобразование ввода позволяет фильтровать ввод TextField во время набора текста, а преобразование вывода форматирует ввод данных пользователем перед тем, как он будет показан на экране.

Фильтрация ввода данных пользователем с помощью преобразований входных данных

Преобразование входных данных позволяет фильтровать информацию, которую вводит пользователь. Например, если функция TextField принимает номер телефона США, вы хотите, чтобы она принимала только 10 цифр. Результаты InputTransformation сохраняются в файле TextFieldState.

Встроенные фильтры предназначены для распространенных вариантов использования InputTransformation. Чтобы ограничить длину, позвоните по номеру InputTransformation.maxLength():

TextField(
    state = rememberTextFieldState(),
    lineLimits = TextFieldLineLimits.SingleLine,
    inputTransformation = InputTransformation.maxLength(10)
)

Пользовательские преобразования входных данных

InputTransformation – это интерфейс с одной функцией. При реализации собственного InputTransformation необходимо переопределить TextFieldBuffer.transformInput:

class CustomInputTransformation : InputTransformation {
    override fun TextFieldBuffer.transformInput() {
    }
}

Для номера телефона добавьте пользовательское преобразование входных данных, которое разрешает вводить в поле TextField только цифры:

class DigitOnlyInputTransformation : InputTransformation {
    override fun TextFieldBuffer.transformInput() {
        if (!asCharSequence().isDigitsOnly()) {
            revertAllChanges()
        }
    }
}

Цепочки преобразований входных данных

Чтобы добавить к тексту несколько фильтров, InputTransformationиспользуйте функцию расширения then. Фильтры выполняются последовательно. Рекомендуем сначала применять наиболее селективные фильтры, чтобы избежать ненужных преобразований данных, которые в конечном итоге будут отфильтрованы.

TextField(
    state = rememberTextFieldState(),
    inputTransformation = InputTransformation.maxLength(6)
        .then(CustomInputTransformation()),
)

После добавления преобразований входных данных поле TextField принимает не более 10 цифр.

Как форматировать введенные данные перед показом

OutputTransformation позволяет форматировать ввод данных пользователем до того, как он будет отображен на экране. В отличие от InputTransformation, форматирование, выполненное с помощью OutputTransformation, не сохраняется в TextFieldState. В примере с номером телефона, приведенном выше, нужно добавить скобки и дефисы в нужных местах:

Номер телефона в США, правильно отформатированный с помощью скобок, дефисов и соответствующих индексов.
Рисунок 3. Номер телефона в США с правильным форматированием и соответствующими индексами.

Это обновленный способ обработки VisualTransformation в TextField, основанных на значениях. Главное отличие в том, что вам не нужно вычислять смещения.

OutputTransformation – это интерфейс с одним абстрактным методом. Чтобы реализовать собственный тег OutputTransformation, вам нужно переопределить метод transformOutput:

class CustomOutputTransformation : OutputTransformation {
    override fun TextFieldBuffer.transformOutput() {
    }
}

Чтобы отформатировать номер телефона, добавьте открывающую скобку в индекс 0, закрывающую скобку в индекс 4 и дефис в индекс 8 к OutputTransformation:

class PhoneNumberOutputTransformation : OutputTransformation {
    override fun TextFieldBuffer.transformOutput() {
        if (length > 0) insert(0, "(")
        if (length > 4) insert(4, ")")
        if (length > 8) insert(8, "-")
    }
}

Затем добавьте OutputTransformation в TextField:

TextField(
    state = rememberTextFieldState(),
    outputTransformation = PhoneNumberOutputTransformation()
)

Как работают преобразования

На приведенной ниже схеме показан процесс преобразования текста в выходные данные.

Визуализация того, как введенный текст преобразуется в выходной.
Рисунок 4. Схема, на которой показано, как введенный текст преобразуется в выходной текст.
  1. Входные данные получены из источника сигнала.
  2. Входные данные фильтруются с помощью InputTransformation, который сохраняется в TextFieldState.
  3. Входные данные передаются через OutputTransformation для форматирования.
  4. Входные данные представлены в TextField.

Как настроить параметры клавиатуры

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

  • capitalization
  • autoCorrect
  • keyboardType
  • imeAction

Дополнительные ресурсы