TextWatcher: qué es, interfaz TextWatcher e implementación en Android

¿Qué es TextWatcher y para qué sirve?

TextWatcher es una interfaz del paquete android.text que notifica a la aplicación sobre cambios de texto en objetos Editable. Con cada entrada, eliminación o reemplazo de caracteres, TextWatcher llama secuencialmente a tres métodos, transmitiendo información sobre la posición de los cambios. Esto permite al desarrollador reaccionar a las acciones del usuario al instante, sin botones adicionales ni disparadores.

Los principales casos de uso incluyen validación de campos en tiempo real: verificar el correo electrónico mientras se escribe cada carácter, contar los caracteres restantes en un campo con límite de longitud, implementar búsqueda con solicitud diferida mediante debounce. TextWatcher también se utiliza para formatear la entrada, por ejemplo, inserción automática de espacios en un número de teléfono o añadir una máscara para una fecha.

Según Android Developers, TextWatcher está presente en el 70% de las aplicaciones que trabajan con formularios. Bibliotecas como Material Design Components y TextInputEditText usan TextWatcher internamente para gestionar estados de error y mostrar contadores. Comprender el funcionamiento de esta interfaz es esencial para todo desarrollador Android.

Cómo funciona la interfaz TextWatcher

TextWatcher se conecta a cualquier objeto TextView o EditText mediante el método addTextChangedListener. Cuando el usuario escribe o elimina un carácter, Android llama primero a beforeTextChanged, luego a onTextChanged y finalmente a afterTextChanged. Los parámetros de cada método contienen datos sobre el rango modificado: posición inicial, número de caracteres eliminados y número de caracteres añadidos.

Es importante entender que después de llamar a afterTextChanged, el objeto Editable ya contiene el valor actual. Por lo tanto, es conveniente verificar el texto final del campo en afterTextChanged. Antes de ese momento, los datos aún no están completamente actualizados. Los desarrolladores a menudo confunden el propósito de los métodos y usan onTextChanged para la validación final, aunque la elección correcta es afterTextChanged.

Particularidades de la llamada a los métodos

Con cada inserción, reemplazo o eliminación de caracteres, la cadena de llamadas se ejecuta completamente de forma garantizada. Sin embargo, si se cambia el texto dentro de afterTextChanged (mediante clear, append, insert), TextWatcher se activará recursivamente. Esta es la causa más común de StackOverflowError en formularios Android. Para evitar la recursión se utiliza un flag de bloqueo.

Tres métodos de TextWatcher: beforeTextChanged, onTextChanged, afterTextChanged

Cada uno de los tres métodos desempeña su papel en el ciclo de vida del cambio de texto. El método beforeTextChanged(CharSequence s, int start, int count, int after) se llama antes de aplicar los cambios. Transmite el estado actual de la cadena, la posición de inicio del cambio, el número de caracteres que se eliminan y el número que se añaden. Aquí se puede guardar el valor anterior o verificar condiciones antes de la modificación.

El método onTextChanged se llama durante el cambio, cuando los caracteres ya se han eliminado pero los nuevos aún no se han insertado. Parámetros: el texto después de la eliminación, posición inicial, número de caracteres eliminados y número de caracteres añadidos. Este método es conveniente para animación o registro, pero no para trabajar con el texto final real, ya que aún no está ensamblado.

El método afterTextChanged es el más demandado. Recibe un objeto Editable y se llama después de que los cambios se hayan aplicado completamente. En este método se puede leer el valor final del campo, realizar validación, actualizar la UI y modificar el texto (con precaución debido a la recursión).

Ejemplo de implementación de TextWatcher para conteo de caracteres

Un ejemplo práctico es un contador de caracteres para un campo de entrada que se actualiza con cada cambio de texto. Este elemento se encuentra a menudo en formularios de comentarios, publicaciones y mensajes con límite de longitud. La implementación mediante TextWatcher requiere pocas líneas y no necesita bibliotecas de terceros.

val editText = findViewById<EditText>(R.id.edit_text)
val counterText = findViewById<TextView>(R.id.counter)

editText.addTextChangedListener(object : TextWatcher {
    override fun beforeTextChanged(
        s: CharSequence?, start: Int,
        count: Int, after: Int
    ) {}

    override fun onTextChanged(
        s: CharSequence?, start: Int,
        before: Int, count: Int
    ) {}

    override fun afterTextChanged(s: Editable?) {
        val len = s?.length ?: 0
        counterText.text = "$len / 200"
    }
})

En el ejemplo, el método afterTextChanged recibe el contenido actual del campo a través del parámetro s de tipo Editable. La longitud del texto se actualiza en un TextView separado. En este caso, solo se modifica counterText, no el EditText en sí, por lo que no se produce ningún bucle. Para un límite de 200 caracteres, se puede bloquear la entrada adicional después de superarlo.

Los métodos beforeTextChanged y onTextChanged permanecen vacíos, ya que el estado final es suficiente para contar la longitud. Si se necesita registrar cada cambio, se puede añadir código en onTextChanged. Esta flexibilidad hace de TextWatcher una herramienta universal para cualquier escenario de entrada de texto.

TextWatcher para validación de campos en tiempo real

La validación en tiempo real mejora significativamente la UX: el usuario ve un error inmediatamente después de introducir un valor incorrecto, en lugar de después de pulsar el botón de envío. TextWatcher permite la comprobación instantánea de correo electrónico, contraseña, número de teléfono y otros campos. El resultado se muestra mediante setError en el EditText o a través de un TextView separado con un mensaje de error.

fun validateEmail(emailEditText: EditText) {
    emailEditText.addTextChangedListener(object : TextWatcher {
        override fun afterTextChanged(s: Editable?) {
            val email = s?.toString () ?: ""
            if (email.isNotBlank() &&
                !Patterns.EMAIL_ADDRESS.matcher(email).matches()) {
                emailEditText.error = "Invalid email address"
            } else {
                emailEditText.error = null
            }
        }

        override fun beforeTextChanged(...) {}
        override fun onTextChanged(...) {}
    })
}

El ejemplo utiliza el Patterns.EMAIL_ADDRESS integrado del SDK de Android para verificar el correo electrónico. Si el texto no está vacío y no coincide con el patrón, se establece un error en el campo mediante la propiedad error. Cuando la entrada es correcta, el error se limpia. Es importante no ejecutar la validación en un campo vacío; el usuario puede no haber empezado a escribir todavía y un mensaje de error sería prematuro.

Para contraseñas y números de teléfono se utilizan expresiones regulares personalizadas o bibliotecas especializadas. Por ejemplo, para verificar la complejidad de una contraseña, se puede contar el número de dígitos, letras mayúsculas y minúsculas. TextWatcher permite actualizar el indicador de fortaleza de la contraseña en tiempo real, lo que afecta positivamente la conversión de registro.

Errores típicos al trabajar con TextWatcher

El primer error y el más crítico es la llamada recursiva. Si se cambia el texto del mismo EditText dentro de afterTextChanged (mediante s.clear(), s.append() o s.insert()), TextWatcher se activará de nuevo. Esto crea un bucle infinito que termina en StackOverflowError. La solución es usar un flag de bloqueo isUpdating o comprobar si el texto realmente ha cambiado.

El segundo problema común es la fuga de memoria. TextWatcher mantiene una referencia implícita a la Activity o Fragment a través de una clase anónima. Si el listener no se elimina al destruir la Vista, el recolector de basura no puede liberar la memoria. La solución es usar componentes de ciclo de vida o llamar explícitamente a removeTextChangedListener en onDestroyView.

El tercer error es usar el método incorrecto. Algunos desarrolladores realizan la validación final en onTextChanged, sin esperar a afterTextChanged. En onTextChanged, el texto aún no está completamente actualizado y la lectura del valor final puede devolver datos incorrectos. El enfoque correcto es que toda la lógica de lectura y verificación del texto final debe estar en afterTextChanged.

El cuarto error es la adición múltiple de TextWatcher. Si se llama a addTextChangedListener varias veces para el mismo EditText, todos los listeners procesarán el mismo cambio. En formularios con adición dinámica de Vistas, esto provoca comprobaciones duplicadas y comportamiento impredecible. Verifique siempre si el listener ya se ha añadido, o utilice una única instancia.