TextInputLayout: چیست، Material Design و پیکربندی در Android

TextInputLayout در Android چیست

TextInputLayout — یک ViewGroup از بسته com.google.android.material.textfield است که LinearLayout را گسترش می‌دهد و درون خود EditText را نگه می‌دارد. این کامپوننت بخشی از کتابخانه Material Components برای Android از نسخه 1.0.0 به بعد است. وظیفه اصلی TextInputLayout ارائه پیاده‌سازی آماده Material Design Text Fields با حداقل تلاش از طرف توسعه‌دهنده است.

برخلاف EditText استاندارد، TextInputLayout انیمیشن برچسب شناور را مدیریت می‌کند که از طریق ویژگی android:hint EditText داخلی تنظیم می‌شود. وقتی فیلد خالی است، برچسب درون فیلد به صورت راهنمای معمولی نمایش داده می‌شود. به محض اینکه کاربر شروع به تایپ می‌کند، برچسب با انیمیشن به قسمت بالای فیلد منتقل می‌شود و اندازه آن کاهش می‌یابد. طبق Material Design Guidelines (2025)، چنین انیمیشنی درک فرم را بهبود می‌بخشد، زیرا کاربر حتی پس از وارد کردن داده‌ها نیز نام فیلد را می‌بیند.

از نظر معماری، TextInputLayout الگوی دکوراتور را پیاده‌سازی می‌کند: رویدادهای EditText را رهگیری می‌کند، نمایش عناصر اضافی (برچسب، خطا، آیکون‌ها، شمارنده) را مدیریت می‌کند و انیمیشن آنها را هماهنگ می‌کند. EditText داخلی از طریق متد getEditText() قابل دسترسی است و می‌تواند با ویژگی‌های استاندارد شامل inputType، maxLines و hint پیکربندی شود.

<!-- Basic TextInputLayout markup -->
@+id/tilEmail
android:layout_width="match_parent"
android:layout_height="wrap_content">

    @+id/etEmail
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:hint="Email"
    android:inputType="textEmailAddress" />

</com.google.android.material.textfield.TextInputLayout>

Floating label و پیکربندی آن

Floating label (برچسب شناور) — قابلیت کلیدی TextInputLayout است. وقتی فیلد خالی است، متن android:hint درون EditText به صورت راهنمای معمولی نمایش داده می‌شود. هنگام دریافت فوکوس یا هنگام تایپ متن، برچسب به قسمت بالای TextInputLayout منتقل می‌شود، اندازه فونت را کاهش می‌دهد و رنگ را تغییر می‌دهد. این رفتار مشکل ناپدید شدن راهنما پس از شروع تایپ را حل می‌کند.

پیکربندی floating label از طریق ویژگی‌های TextInputLayout انجام می‌شود: app:hintEnabled مشخص می‌کند که برچسب شناور فعال است یا خیر (پیش‌فرض true)، app:hintAnimationEnabled انیمیشن انتقال را فعال یا غیرفعال می‌کند، app:expandedHintEnabled نمایش برچسب را حتی وقتی فیلد خالی و بدون فوکوس است مجاز می‌کند. رنگ برچسب در حالت‌های مختلف از طریق سبک‌های colorPrimary و colorControlHighlight مدیریت می‌شود.

طبق Google Material Components Team (2025)، floating label به ویژه در فرم‌های با تعداد زیاد فیلد مفید است، جایی که کاربر ممکن است نام فیلد را پس از شروع تایپ فراموش کند. برخلاف android:hint ساده که هنگام تایپ ناپدید می‌شود، floating label همیشه قابل مشاهده باقی می‌ماند و زمینه را برای هر فیلد فراهم می‌کند.

نمایش خطاها در TextInputLayout

TextInputLayout یک سیستم نمایش خطای داخلی ارائه می‌دهد که از نظر بصری با فیلد ورودی ادغام شده است. هنگام تنظیم خطا از طریق متد error، کامپوننت فیلد را برجسته می‌کند (رنگ خط یا حاشیه به قرمز تغییر می‌کند) و متن خطا را در زیر فیلد نمایش می‌دهد. این کار نیاز به یک TextView جداگانه برای پیام‌های خطا را برطرف می‌کند.

مدیریت نمایش خطاها از طریق متدهای setError(CharSequence) و setErrorEnabled(boolean) انجام می‌شود. هنگام فراخوانی setError با متن، خطا بلافاصله نمایش داده می‌شود؛ هنگام فراخوانی setError(null) — پنهان می‌شود. TextInputLayout همچنین از آیکون خطای سفارشی از طریق ویژگی app:errorIconDrawable و مدیریت رنگ خطا از طریق app:errorTextColor پشتیبانی می‌کند.

طبق Material Design Guidelines (2025)، پیام‌های خطا باید مشخص و مفید باشند: به جای «ورودی نامعتبر» بنویسید «ایمیل باید شامل @ باشد». نمایش خطا باید پس از اتمام ورود (پس از از دست دادن فوکوس یا پس از ارسال فرم) انجام شود، نه در زمان واقعی — این کار استرس کاربر را هنگام پر کردن فرم کاهش می‌دهد.

// تنظیم خطای برنامه‌نویسی
textInputLayout.error = "Password min 8 chars"

// مخفی‌سازی خطا
textInputLayout.error = null

// بررسی و تنظیم خطای اعتبارسنجی
if (email.isNullOrBlank()) {
    tilEmail.error = "Email is required"
} else {
    tilEmail.error = null
}

آیکون‌ها و اقدامات TextInputLayout

TextInputLayout از نمایش آیکون‌ها هم در ابتدای فیلد (start icon) و هم در انتهای فیلد (end icon) پشتیبانی می‌کند. آیکون‌ها می‌توانند عملکردهای مختلفی داشته باشند: تغییر وضعیت نمایش رمز عبور، پاک کردن فیلد، اقدام سفارشی. هر نوع آیکون توسط یک ویژگی جداگانه مدیریت می‌شود و می‌تواند از طریق ویژگی app:startIconDrawable یا app:endIconDrawable با آیکون سفارشی جایگزین شود.

End icon mode از طریق ویژگی app:endIconMode تنظیم می‌شود که می‌تواند مقادیر زیر را بگیرد: password_toggle — تغییر وضعیت نمایش رمز عبور، clear_text — پاک کردن فیلد، dropdown_menu — فلش برای منوی کشویی، custom — آیکون سفارشی. برای password_toggle، TextInputLayout به طور خودکار inputType را بین textPassword و textVisiblePassword تغییر می‌دهد و همچنین آیکون چشم را انیمیشن می‌کند.

• password_toggle — آیکون چشم برای نمایش/پنهان کردن رمز عبور، انیمیشن داخلی.
• clear_text — علامت ضربدر برای پاک کردن فیلد، هنگام وجود متن ظاهر می‌شود.
• dropdown_menu — فلش برای Exposed Dropdown Menu (Material Design 3).
• custom — هر آیکون سفارشی با مدیریت از طریق setEndIconOnClickListener.

<!-- TextInputLayout with password toggle icon -->
@+id/tilPassword
android:layout_width="match_parent"
app:endIconMode="password_toggle"
app:passwordToggleTint="@color/primary">

    @+id/etPassword
    android:inputType="textPassword" />

</com.google.android.material.textfield.TextInputLayout>

سبک‌های TextInputLayout: FilledBox و OutlinedBox

Material Components برای Android دو سبک اصلی برای TextInputLayout ارائه می‌دهد: FilledBox (پر شده) و OutlinedBox (با حاشیه). سبک FilledBox دارای پس‌زمینه رنگی و خطی در زیر فیلد است که در هنگام فوکوس تغییر رنگ می‌دهد. سبک OutlinedBox دارای پس‌زمینه شفاف و حاشیه در اطراف کل فیلد است که مرزهای واضح‌تری ایجاد می‌کند و برای فرم‌های با تعداد زیاد فیلد مناسب‌تر است.

انتخاب سبک به طراحی برنامه بستگی دارد: FilledBox برای فرم‌های پرکاربرد توصیه می‌شود، زیرا توجه کمتری به فیلدهای جداگانه جلب می‌کند. OutlinedBox برای فرم‌های کوتاه (ورود، ثبت‌نام) ترجیح داده می‌شود، جایی که هر فیلد باید به وضوح مشخص شود. سبک از طریق ویژگی style در XML یا از طریق تم برنامه تنظیم می‌شود.

Material Design 3 (M3) سبک‌های به‌روزشده‌ای برای TextInputLayout با تایپوگرافی بهبودیافته، توکن‌های رنگی جدید و پشتیبانی از رنگ‌های پویای Material You معرفی کرد. در M3، OutlinedBox به سبک پیش‌فرض توصیه‌شده تبدیل شد و FilledBox فاصله‌ها و شعاع گردشدگی را برای مطابقت با مشخصات جدید تطبیق داد.

نمونه کدهای TextInputLayout

نمونه کامل پیاده‌سازی فرم ثبت‌نام با TextInputLayout شامل اعتبارسنجی ایمیل و رمز عبور، نمایش خطاها و آیکون نمایش رمز عبور. با فشار دادن دکمه ثبت‌نام، همه فیلدها بررسی می‌شوند و پیام‌های خطای مربوطه نمایش داده می‌شوند.

نشانه‌گذاری XML فرم ثبت‌نام

@+id/tilName
app:boxBackgroundMode="outlined">
    @+id/etName
    android:hint="Name" />
</...TextInputLayout>

@+id/tilRegEmail
app:boxBackgroundMode="outlined">
    @+id/etRegEmail
    android:hint="Email"
    android:inputType="textEmailAddress" />
</...TextInputLayout>

@+id/tilRegPassword
app:boxBackgroundMode="outlined"
app:endIconMode="password_toggle">
    @+id/etRegPassword
    android:hint="Password"
    android:inputType="textPassword" />
</...TextInputLayout>

اعتبارسنجی فرم در Kotlin

private fun validateForm(): Boolean {
    var isValid = true

    if (etName.text.isNullOrBlank()) {
        tilName.error = "Enter your name"
        isValid = false
    } else {
        tilName.error = null
    }

    val email = etRegEmail.text.toString()
    if (!Patterns.EMAIL_ADDRESS.matcher(email).matches()) {
        tilRegEmail.error = "Invalid email format"
        isValid = false
    } else {
        tilRegEmail.error = null
    }

    val password = etRegPassword.text.toString()
    if (password.length < 8) {
        tilRegPassword.error = "Password min 8 chars"
        isValid = false
    } else {
        tilRegPassword.error = null
    }

    return isValid
}