TextWatcher: какво е, интерфейс TextWatcher и имплементация в Android

Какво е TextWatcher и за какво служи?

TextWatcher е интерфейс от пакета android.text, който уведомява приложението за промени в текста в обекти Editable. При всяко въвеждане, изтриване или замяна на символ, TextWatcher последователно извиква три метода, предавайки информация за позицията на промените. Това позволява на разработчика да реагира незабавно на действията на потребителя — без допълнителни бутони или тригери.

Основните сценарии за използване включват валидация на полета в реално време: проверка на имейл при въвеждане на всеки символ, броене на оставащи символи в поле с ограничение на дължината, имплементиране на търсене с отложено изпращане на заявка чрез debounce. TextWatcher се използва също за форматиране на въвеждане — например автоматично поставяне на интервали в телефонен номер или добавяне на маска за дата.

Според Android Developers, TextWatcher присъства в 70% от приложенията, работещи с форми. Библиотеки като Material Design Components и TextInputEditText използват TextWatcher вътрешно за управление на състоянието на грешка и показване на броячи. Разбирането на работата на този интерфейс е необходимо за всеки Android разработчик.

Как работи интерфейсът TextWatcher

TextWatcher се свързва към всеки обект TextView или EditText чрез метода addTextChangedListener. Когато потребителят въвежда или изтрива символ, Android първо извиква beforeTextChanged, след това onTextChanged и накрая afterTextChanged. В параметрите на всеки метод се предават данни за променяния диапазон: начална позиция, брой изтрити символи и брой добавени символи.

Важно е да се разбере, че след извикването на afterTextChanged обектът Editable вече съдържа актуалната стойност. Затова в afterTextChanged е удобно да се проверява крайният текст на полето. До този момент данните все още не са напълно актуализирани. Разработчиците често бъркат предназначението на методите и използват onTextChanged за крайна валидация, въпреки че правилният избор е afterTextChanged.

Особености при извикване на методите

При всяко вмъкване, замяна или изтриване на символ веригата от извиквания се изпълнява гарантирано изцяло. Въпреки това, ако вътре в afterTextChanged се промени текстът (чрез clear, append, insert), TextWatcher ще се задейства рекурсивно. Това е най-честата причина за StackOverflowError в Android форми. За предотвратяване на рекурсия се използва блокиращ флаг.

Трите метода на TextWatcher: beforeTextChanged, onTextChanged, afterTextChanged

Всеки от трите метода играе своята роля в жизнения цикъл на промяна на текст. Методът beforeTextChanged(CharSequence s, int start, int count, int after) се извиква преди прилагане на промените. Той предава текущото състояние на низа, началната позиция на промяната, броя на изтриваните символи и броя на добавяните символи. Тук може да се запази предишната стойност или да се проверят условията преди модификация.

Методът onTextChanged се извиква по време на промяната, когато символите вече са изтрити, но новите все още не са вмъкнати. Параметри: текст след изтриване, начална позиция, брой изтрити символи и брой добавяни символи. Този метод е удобен за анимация или логиране, но не за работа с актуалния краен текст — той все още не е завършен.

Методът afterTextChanged е най-търсеният. Той получава обект Editable и се извиква, след като промените са напълно приложени. В този метод може да се чете крайната стойност на полето, да се извършва валидация, да се актуализира UI и да се променя текст (внимателно поради рекурсия).

Пример за имплементация на TextWatcher за броене на символи

Практически пример — брояч на символи за поле за въвеждане, който се актуализира при всяка промяна на текст. Такъв елемент често се среща във форми за контакт, публикации и съобщения с ограничение на дължината. Имплементацията чрез TextWatcher отнема само няколко реда и не изисква библиотеки на трети страни.

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"
    }
})

В примера методът afterTextChanged получава текущото съдържание на полето чрез параметъра s от тип Editable. Дължината на текста се актуализира в отделен TextView. За да се избегне рекурсия в този случай, се променя само counterText, а не самият EditText, така че не възниква цикъл. При лимит от 200 символа може допълнително да се блокира въвеждането след превишаване.

Методите beforeTextChanged и onTextChanged остават празни, тъй като за броене на дължината е достатъчно крайното състояние. Ако се налага логиране на всяка промяна, кодът може да се добави в onTextChanged. Такава гъвкавост прави TextWatcher универсален инструмент за всеки сценарий на работа с текстово въвеждане.

TextWatcher за валидация на полета в реално време

Валидацията в реално време значително подобрява потребителското изживяване: потребителят вижда грешката веднага след въвеждане на некоректна стойност, а не след натискане на бутона за изпращане. TextWatcher позволява незабавна проверка на имейл, парола, телефонен номер и други полета. Резултатът се показва чрез setError в EditText или чрез отделен TextView със съобщение за грешка.

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(...) {}
    })
}

В примера се използва вграденият Patterns.EMAIL_ADDRESS от Android SDK за проверка на имейл. Ако текстът не е празен и не съвпада с шаблона, на полето се задава грешка чрез свойството error. При коректно въвеждане грешката се изчиства. Важно е да не се стартира валидация на празно поле — потребителят може все още да не е започнал въвеждане и съобщението за грешка би било преждевременно.

За пароли и телефонни номера се използват персонализирани регулярни изрази или специализирани библиотеки. Например, за проверка на сложността на парола може да се преброят цифрите, главните и малките букви. TextWatcher позволява актуализиране на индикатора за сложност на парола в реално време, което влияе положително на конверсията при регистрация.

Типични грешки при работа с TextWatcher

Първата и най-критична грешка — рекурсивно извикване. Ако вътре в afterTextChanged се промени текстът на същия EditText (чрез s.clear(), s.append() или s.insert()), TextWatcher ще се задейства отново. Това създава безкраен цикъл, който завършва със StackOverflowError. Решението — използване на блокиращ флаг isUpdating или проверка дали текстът действително се е променил.

Вторият често срещан проблем — изтичане на памет. TextWatcher съдържа имплицитна референция към Activity или Fragment чрез анонимен клас. Ако listener не бъде премахнат при унищожаване на View, garbage collector не може да освободи паметта. Решението — използване на компоненти на жизнения цикъл или изрично извикване на removeTextChangedListener в onDestroyView.

Третата грешка — използване на неправилен метод. Някои разработчици извършват крайна валидация в onTextChanged, без да изчакват afterTextChanged. В onTextChanged текстът все още не е напълно актуализиран и четенето на крайната стойност може да върне некоректни данни. Правилният подход — поставяне на цялата логика за четене и проверка на крайния текст в afterTextChanged.

Четвъртата грешка — многократно добавяне на TextWatcher. Ако addTextChangedListener е бил извикан няколко пъти за един и същ EditText, всички listeners ще обработват една и съща промяна. Във форми с динамично добавяне на View това води до дублиране на проверки и непредвидимо поведение. Винаги проверявайте дали listener вече е бил добавен преди това или използвайте единична инстанция.