Configura campos de texto

TextField permite a los usuarios ingresar y modificar texto. Existen dos tipos de campos de texto que puedes usar: campos de texto basados en el estado y campos de texto basados en el valor. Selecciona el tipo para el que deseas mostrar contenido:

Te recomendamos que uses campos de texto basados en estados, ya que proporcionan un enfoque más completo y confiable para administrar el estado de un TextField. En la siguiente tabla, se describen las diferencias entre estos tipos de campos de texto y se incluyen las ventajas clave que ofrecen los campos de texto basados en el estado:

En esta página, se describe cómo puedes implementar TextField, aplicar estilo a la entrada de TextField y configurar otras opciones de TextField, como las opciones del teclado y la transformación visual de la entrada del usuario.

Elige la implementación de TextField

Existen dos niveles de implementación de TextField:

1. TextField es la implementación de Material Design. Te recomendamos que elijas esta implementación, ya que sigue los lineamientos de Material Design:
   • El estilo predeterminado está relleno.
   • OutlinedTextField es la versión de estilo de contorno.
2. BasicTextField permite a los usuarios editar texto con el teclado en pantalla o físico, pero no proporciona decoraciones como sugerencias o marcadores de posición.

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

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

Estilo TextField

TextField y BasicTextField comparten muchos parámetros comunes de personalización. La lista completa para TextField está disponible en el código fuente de TextField. Esta es una lista no exhaustiva de algunos de los parámetros útiles:

• 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)
)
StateBasedText.kt

Recomendamos usar TextField en lugar de BasicTextField cuando el diseño llame a un TextField o OutlinedTextField de Material. Sin embargo, BasicTextField debe usarse cuando se crean diseños que no necesitan las decoraciones de la especificación de Material.

Cómo configurar límites de líneas

Los elementos TextField componibles admiten el desplazamiento a lo largo de un solo eje. El comportamiento de desplazamiento se determina con el parámetro lineLimits. Los TextField configurados para un desplazamiento de una sola línea se desplazan horizontalmente, mientras que los TextField de varias líneas se desplazan verticalmente.

Usa TextFieldLineLimits para elegir la configuración de línea adecuada para tu TextField:

TextField(
    state = rememberTextFieldState(),
    lineLimits = TextFieldLineLimits.SingleLine
)
StateBasedText.kt

La configuración de SingleLine tiene las siguientes características:

• El texto nunca se ajusta y no permite líneas nuevas.
• TextField siempre tiene una altura fija.
• Si el texto se desborda, se desplaza horizontalmente.

TextField(
    state = rememberTextFieldState("Hello\nWorld\nHello\nWorld"),
    lineLimits = TextFieldLineLimits.MultiLine(1, 4)
)
StateBasedText.kt

La configuración de MultiLine tiene las siguientes características:

• Acepta dos parámetros: minHeightInLines y maxHeightInLines.
• El campo de texto tiene al menos minHeightInLines de alto.
• Si el texto se desborda, se ajustará.
• Si el texto requiere más líneas, el campo crece hasta alcanzar una altura de maxHeightInLines y se desplaza verticalmente.

Cómo aplicar estilo a la entrada con la API de Brush

Puedes usar la API de pincel para aplicar un diseño más avanzado en tu TextField. En la siguiente sección, se describe cómo puedes usar un pincel para agregar un gradiente de color a la entrada de TextField.

Para obtener más información sobre cómo usar la API de Brush para aplicar estilo al texto, consulta Habilita el diseño avanzado con la API de Brush.

Implementa gradientes de color con TextStyle

Para implementar un gradiente de color a medida que escribes dentro de un TextField, configura el pincel que elijas como un TextStyle para tu TextField. En este ejemplo, usamos un pincel integrado con un linearGradient para ver el efecto de degradado de arcoíris a medida que se escribe texto en el 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)
)
StateBasedText.kt

Administra el estado del campo de texto

TextField usa una clase de contenedor de estados dedicada llamada TextFieldState para su contenido y selección actual. TextFieldState está diseñado para alojarse dondequiera que se ajuste a tu arquitectura. TextFieldState proporciona 2 propiedades principales:

• initialText: Contenido del TextField.
• initialSelection: Indica dónde se encuentra actualmente el cursor o la selección.

Lo que diferencia a TextFieldState de otros enfoques, como la devolución de llamada onValueChange, es que TextFieldState encapsula por completo todo el flujo de entrada. Esto incluye el uso de las estructuras de datos de respaldo correctas, la inserción de filtros y formateadores, y la sincronización de todas las ediciones provenientes de diferentes fuentes.

Puedes usar TextFieldState() para elevar el estado en TextField. Para ello, te recomendamos que uses la función rememberTextFieldState(). rememberTextFieldState() crea la instancia de TextFieldState en tu elemento componible, garantiza que se recuerde el objeto de estado y proporciona funcionalidad integrada para guardar y restablecer:

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

rememberTextFieldState puede tener un parámetro en blanco o un valor inicial que se pasa para representar el valor del texto en la inicialización. Si se pasa un valor diferente en una recomposición posterior, no se actualizará el valor del estado. Para actualizar el estado después de que se inicializa, llama a los métodos de edición en TextFieldState.

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

Modifica texto con TextFieldBuffer

Un TextFieldBuffer funciona como un contenedor de texto editable, similar en función a un StringBuilder. Contiene el contenido de texto y la información sobre la selección actual.

A menudo, encuentras TextFieldBuffer como un alcance del receptor en funciones como TextFieldState.edit, InputTransformation.transformInput o OutputTransformation.transformOutput. En estas funciones, puedes leer o actualizar el TextFieldBuffer según sea necesario. Luego, estos cambios se confirman en TextFieldState o se pasan a la canalización de renderización en el caso de OutputTransformation.

Puedes usar funciones de edición estándar, como append, insert, replace o delete, para modificar el contenido del búfer. Para cambiar el estado de selección, establece directamente su variable selection: TextRange o usa funciones de utilidad como placeCursorAtEnd o selectAll. La selección en sí se representa con un TextRange, en el que el índice de inicio es inclusivo y el índice de finalización es exclusivo. Un TextRange con valores de inicio y finalización idénticos, como (3, 3), indica una posición del cursor sin caracteres seleccionados actualmente.

val phoneNumberState = rememberTextFieldState()

LaunchedEffect(phoneNumberState) {
    phoneNumberState.edit { // TextFieldBuffer scope
        append("123456789")
    }
}

TextField(
    state = phoneNumberState,
    inputTransformation = InputTransformation { // TextFieldBuffer scope
        if (asCharSequence().isDigitsOnly()) {
            revertAllChanges()
        }
    },
    outputTransformation = OutputTransformation {
        if (length > 0) insert(0, "(")
        if (length > 4) insert(4, ")")
        if (length > 8) insert(8, "-")
    }
)
StateBasedText.kt

Cómo editar texto en TextFieldState

Existen varios métodos que te permiten editar el estado directamente a través de tu variable de estado:

• edit: Te permite editar el contenido del estado y te proporciona funciones de TextFieldBuffer para que puedas usar métodos como insert, replace, append y muchos más.

  val usernameState = rememberTextFieldState("I love Android")
  // textFieldState.text : I love Android
  // textFieldState.selection: TextRange(14, 14)
  usernameState.edit { insert(14, "!") }
  // textFieldState.text : I love Android!
  // textFieldState.selection: TextRange(15, 15)
  usernameState.edit { replace(7, 14, "Compose") }
  // textFieldState.text : I love Compose!
  // textFieldState.selection: TextRange(15, 15)
  usernameState.edit { append("!!!") }
  // textFieldState.text : I love Compose!!!!
  // textFieldState.selection: TextRange(18, 18)
  usernameState.edit { selectAll() }
  // textFieldState.text : I love Compose!!!!
  // textFieldState.selection: TextRange(0, 18)
  StateBasedText.kt

• setTextAndPlaceCursorAtEnd: Borra el texto actual, lo reemplaza por el texto proporcionado y coloca el cursor al final.

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

• clearText: Borra todo el texto.

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

Para ver otras funciones de TextFieldState, consulta la referencia de TextFieldState.

Modifica la entrada del usuario

En las siguientes secciones, se describe cómo modificar la entrada del usuario. La transformación de entrada te permite filtrar la entrada de TextField mientras el usuario escribe, mientras que la transformación de salida formatea la entrada del usuario antes de que se muestre en la pantalla.

Filtra la entrada del usuario con transformaciones de entrada

Una transformación de entrada te permite filtrar la entrada del usuario. Por ejemplo, si tu TextField acepta un número de teléfono estadounidense, solo querrás aceptar 10 dígitos. Los resultados de InputTransformation se guardan en TextFieldState.

Hay filtros integrados para casos de uso comunes de InputTransformation. Para limitar la longitud, llama a InputTransformation.maxLength():

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

Transformaciones de entrada personalizadas

InputTransformation es una interfaz de una sola función. Cuando implementes tu InputTransformation personalizado, deberás anular TextFieldBuffer.transformInput:

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

Para un número de teléfono, agrega una transformación de entrada personalizada que solo permita ingresar dígitos en TextField:

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

Encadena transformaciones de entrada

Para agregar varios filtros a tu entrada de texto, encadena InputTransformations con la función de extensión then. Los filtros se ejecutan de forma secuencial. Como práctica recomendada, aplica primero los filtros más selectivos para evitar transformaciones innecesarias en los datos que, en última instancia, se filtrarían.

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

Después de agregar transformaciones de entrada, la entrada TextField acepta un máximo de 10 dígitos.

Formatea la entrada antes de que se muestre

OutputTransformations te permiten formatear la entrada del usuario antes de que se renderice en la pantalla. A diferencia de InputTransformation, el formato que se aplica a través de OutputTransformation no se guarda en TextFieldState. Basándonos en el ejemplo anterior del número de teléfono, debes agregar paréntesis y guiones en los lugares correspondientes:

Esta es la forma actualizada de controlar los VisualTransformation en los TextField basados en valores, con una diferencia clave: no tienes que calcular sus asignaciones de desplazamiento.

OutputTransformation es una interfaz de método único abstracto. Para implementar un OutputTransformation personalizado, debes anular el método transformOutput:

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

Para darle formato a un número de teléfono, agrega un paréntesis de apertura en el índice 0, un paréntesis de cierre en el índice 4 y un guion en el índice 8 a tu OutputTransformation:

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

A continuación, agrega tu OutputTransformation a TextField:

TextField(
    state = rememberTextFieldState(),
    outputTransformation = PhoneNumberOutputTransformation()
)
StateBasedText.kt

Cómo funcionan las transformaciones en conjunto

En el siguiente diagrama, se muestra el flujo desde la entrada de texto hasta la transformación y la salida:

1. Se reciben datos de la fuente de entrada.
2. La entrada se filtra a través de un InputTransformation, que se guarda en TextFieldState.
3. La entrada se pasa a través de un OutputTransformation para el formato.
4. La entrada se presenta en TextField.

Cómo configurar las opciones del teclado

TextField te permite establecer opciones de configuración del teclado, como el diseño, o bien habilitar la autocorrección si es compatible con el teclado. Es posible que algunas opciones no estén garantizadas si el teclado en pantalla no cumple con las opciones que se proporcionan aquí. Esta es la lista de las opciones de teclado compatibles:

• capitalization
• autoCorrect
• keyboardType
• imeAction

La clase KeyboardOptions ahora incluye un nuevo parámetro booleano, showKeyboardOnFocus, que se usa específicamente para los componentes TextField que están integrados con TextFieldState. Esta opción rige el comportamiento del teclado en pantalla cuando TextField adquiere el enfoque por medios distintos a la interacción directa del usuario (por ejemplo, de forma programática).

Cuando KeyboardOptions.showKeyboardOnFocus se establece como verdadero, el teclado en pantalla no aparece automáticamente si TextField obtiene el enfoque de forma indirecta. En esos casos, el usuario debe presionar de forma explícita el TextField para que aparezca el teclado.

Define la lógica de interacción del teclado

El botón de acción del teclado de software de Android permite respuestas interactivas dentro de tu aplicación. Para obtener más información sobre cómo configurar el botón de acción, consulta la sección Cómo configurar opciones del teclado.

Para definir lo que ocurre cuando un usuario presiona este botón de acción, usa el parámetro onKeyboardAction. Este parámetro acepta una interfaz funcional opcional llamada KeyboardActionHandler. La interfaz KeyboardActionHandler contiene un solo método, onKeyboardAction(performDefaultAction: () -> Unit). Si proporcionas una implementación para este método onKeyboardAction, puedes introducir lógica personalizada que se ejecute cuando un usuario presione el botón de acción del teclado.

Varios tipos de acciones de teclado estándar incluyen comportamientos predeterminados integrados. Por ejemplo, si seleccionas ImeAction.Next o ImeAction.Previous como el tipo de acción, de forma predeterminada, el enfoque se desplazará al campo de entrada siguiente o anterior, respectivamente. Del mismo modo, un botón de acción configurado como ImeAction.Done suele descartar el teclado de software. Estas funciones predeterminadas se ejecutan automáticamente y no requieren que proporciones un KeyboardActionHandler.

También puedes implementar un comportamiento personalizado además de estas acciones predeterminadas. Cuando proporcionas tu KeyboardActionHandler, su método onKeyboardAction recibe una función performDefaultAction. Puedes llamar a esta función performDefaultAction() en cualquier punto de tu lógica personalizada para activar también el comportamiento predeterminado estándar asociado con la acción actual del IME.

TextField(
    state = textFieldViewModel.usernameState,
    keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next),
    onKeyboardAction = { performDefaultAction ->
        textFieldViewModel.validateUsername()
        performDefaultAction()
    }
)
StateBasedText.kt

En este fragmento, se ilustra un caso de uso común en una pantalla de registro que incluye un campo de nombre de usuario. En este campo, se selecciona ImeAction.Next para su botón de acción del teclado. Esta elección permite una navegación rápida y fluida al campo de contraseña siguiente.

Además de esta navegación estándar, se requiere iniciar un proceso de validación en segundo plano para el nombre de usuario a medida que el usuario ingresa su contraseña. Para garantizar que se conserve el comportamiento predeterminado de cambio de enfoque inherente a ImeAction.Next junto con esta lógica de validación personalizada, se invoca la función performDefaultAction(). Llamar a performDefaultAction() activa de forma implícita el sistema subyacente de administración del enfoque para mover el enfoque al siguiente elemento de la IU adecuado, lo que preserva el flujo de navegación esperado.

Crea un campo de contraseña seguro

SecureTextField es un elemento componible creado sobre campos de texto basados en el estado para escribir un campo de contraseña. Te recomendamos que uses SecureTextField para crear campos de texto de contraseña, ya que oculta la entrada de caracteres de forma predeterminada y deshabilita las acciones de cortar y copiar.

SecureTextField tiene un textObfuscationMode, que controla cómo el usuario ve la entrada de caracteres. textObfuscationMode tiene las siguientes opciones:

• Hidden: Oculta toda la entrada. Es el comportamiento predeterminado en plataformas de computadoras.

  

• Visible: Muestra todas las entradas.

  

• RevealLastTyped: Oculta todas las entradas, excepto el último carácter. Comportamiento predeterminado en dispositivos móviles.

  

Recursos adicionales

• Cómo aplicar formato automático a un número de teléfono en un campo de texto
• Cómo mostrar u ocultar la contraseña según un botón de activación del usuario
• Cómo validar la entrada a medida que el usuario escribe