InputFilter چیست، رابط InputFilter و فیلتر کردن در اندروید
InputFilter یک رابط Android SDK است که به شما امکان میدهد متن ورودی را پیش از نمایش در EditText رهگیری و تغییر دهید. توسعهدهنده قوانین فیلتر کردن را مشخص میکند: کاراکترهای مجاز، حداکثر طول، قالب ورودی. بر اساس Android Developers, 2026، InputFilter برای محدود کردن ورود حروف، ارقام، کاراکترهای خاص و قالببندی خودکار متن استفاده میشود. برخلاف TextWatcher، فیلتر پیش از تغییر متن اعمال میشود که از ورود نادرست در سطح منبع جلوگیری میکند.
نکات کلیدی
- InputFilter — رابط اندروید برای محدود کردن و قالببندی ورودی در EditText و TextView.
- متد filter پیش از تغییر متن فراخوانی میشود و CharSequence فیلتر شده یا null را در صورت مجاز بودن تغییر برمیگرداند.
- InputFilter.LengthFilter — پیادهسازی استاندارد برای محدود کردن حداکثر طول متن.
- فیلترهای سفارشی به شما امکان میدهند کاراکترهای خاص را ممنوع کنید، ماسک ورودی اعمال کنید یا حروف را به حروف بزرگ/کوچک تبدیل کنید.
- زنجیره فیلترها — میتوان چندین InputFilter را همزمان روی یک EditText اعمال کرد و آنها به صورت ترتیبی اجرا میشوند.
InputFilter چیست و چرا به آن نیاز داریم؟
InputFilter یک رابط تابعی از بسته android.text است که تنها متد filter(CharSequence source, int start, int end, Spanned dest, int dstart, int dend) را تعریف میکند. هر بار که کاربر بخواهد متنی را در EditText وارد، جایگذاری یا جایگزین کند، این متد به صورت خودکار فراخوانی میشود. مقدار برگشتی تعیین میکند که آیا تغییر پذیرفته، رد یا اصلاح میشود.
هدف اصلی InputFilter جلوگیری از ورود نادرست پیش از رسیدن متن به فیلد است. به عنوان مثال، در فیلد ورود ارقام شماره تلفن فیلتر میتواند ورود حروف و کاراکترهای خاص را ممنوع کند. در فیلد رمز عبور — حداقل طول را محدود کند. در فیلد کد تأیید — فقط ارقام مجاز باشد. برخلاف اعتبارسنجی از طریق TextWatcher، فیلتر اجازه نمیدهد کاراکترهای اشتباه حتی روی صفحه نمایش داده شوند.
بر اساس Android Developers، InputFilter در همه کامپوننتهای Material Design برای TextInputEditText استفاده میشود. کتابخانههایی مانند PhoneNumberFormattingTextWatcher TextWatcher و InputFilter را برای قالببندی کامل ترکیب میکنند. توصیه میشود InputFilter را به عنوان اولین سد دفاعی در برابر ورود نادرست استفاده کنید و TextWatcher را برای منطق تکمیلی پس از ورود به کار ببرید.
InputFilter چگونه کار میکند
متد filter شش پارامتر دریافت میکند: source — متن ورودی، start و end — مرزهای قطعه ورودی، dest — محتوای فعلی فیلد، dstart و dend — موقعیتی که متن در آن جایگذاری میشود. اگر متد null برگرداند، تغییر بدون هیچ تغییری پذیرفته میشود. اگر رشته خالی "" برگرداند، تغییر مسدود میشود. اگر یک CharSequence جدید برگرداند، متن اصلی با مقدار برگشتی جایگزین میشود.
به عنوان مثال، اگر کاربر بخواهد حرف "a" را در فیلدی جای دهد که فقط ارقام در آن مجاز است، فیلتر "" را برمیگرداند و کاراکتر ظاهر نمیشود. اگر "123" جایگذاری شود، فیلتر میتواند "1-2-3" را با افزودن جداکنندهها برگرداند. این مکانیزم امکان قالببندی خودکار شماره تلفن، تاریخ و سایر دادههای ساختاریافته را بدون مشارکت TextWatcher فراهم میکند.
مهم: InputFilter منبع داده اصلی را تغییر نمیدهد، بلکه فقط نسخه فیلتر شده را برمیگرداند. اندروید مقدار برگشتی را روی Editable اعمال میکند. اگر فیلتر null برگرداند، هیچ اقدام اضافی لازم نیست. اگر متن تغییر یافته برگرداند، اندروید محدوده اصلی را حذف و محدوده جدید را جایگذاری میکند.
فیلترهای استاندارد در Android SDK
Android SDK چندین پیادهسازی داخلی InputFilter ارائه میدهد. رایجترین آن InputFilter.LengthFilter است که حداکثر طول متن را محدود میکند. سازنده آن یک عدد صحیح — حداکثر تعداد کاراکترها — دریافت میکند. اگر طول متن فعلی با احتساب ورودی از حد مجاز فراتر رود، فیلتر رشته بریدهشده را برمیگرداند و اجازه تجاوز از محدودیت را نمیدهد.
همچنین InputFilter.AllCaps در دسترس است که همه کاراکترهای ورودی را به حروف بزرگ تبدیل میکند. این فیلتر در فیلدهای کد، کد پستی و سایر دادههایی که در آنها حروف بزرگ اهمیت دارد استفاده میشود. فیلتر فقط حروف کوچک را مسدود نمیکند، بلکه آنها را تبدیل میکند، که برای کاربر راحت است — او نتیجه تبدیل را میبیند.
InputFilter.LengthFilter برای چندین محدودیت وجود دارد — از طریق ترکیب فیلترها. به عنوان مثال، اگر نیاز به محدود کردن طول تا 20 کاراکتر و مجاز بودن فقط ارقام دارید، میتوانید LengthFilter + فیلتر رقمی سفارشی را اعمال کنید. هر فیلتر به صورت ترتیبی اجرا میشود و نتیجه قبلی به dest فیلتر بعدی تبدیل میشود.
| فیلتر | کاربرد | مثال استفاده |
|---|---|---|
| LengthFilter | محدود کردن طول متن | فیلد نام تا 50 کاراکتر |
| AllCaps | تبدیل به حروف بزرگ | فیلد کد پستی |
| InputFilter سفارشی | قوانین دلخواه فیلتر کردن | فقط ارقام، کاراکترهای خاص ممنوع هستند |
ساخت InputFilter سفارشی
برای ساخت فیلتر سفارشی باید رابط InputFilter را پیادهسازی و متد filter را بازنویسی کنید. یک کار رایج — فیلتری که فقط ارقام را مجاز میداند. در این حالت متد هر کاراکتر از source را از طریق Character.isDigit بررسی میکند و رشته فیلتر شده یا null را در صورت مجاز بودن همه کاراکترها برمیگرداند.
kotlin
class DigitsInputFilter : InputFilter {
override fun filter(
source: CharSequence?,
start: Int,
end: Int,
dest: Spanned?,
dstart: Int,
dend: Int
): CharSequence? {
val sb = StringBuilder()
for (i in start until end) {
val c = source?.get(i)
if (c != null && Character.isDigit(c)) {
sb.append(c)
}
}
return if (sb.length == end - start) null else sb
}
}مثال فیلتر DigitsInputFilter از همه کاراکترهای متن ورودی عبور میکند و فقط ارقام را نگه میدارد. اگر همه کاراکترها از بررسی عبور کنند، متد null برمیگرداند — این حالت بهینه است، زیرا عملیات اضافی با حافظه انجام نمیدهد. اگر بخشی از کاراکترها حذف شود، رشته جدید برگردانده میشود و فقط ارقام وارد EditText میشوند.
سناریوی محبوب دیگر — فیلتر برای ممنوع کردن کاراکترهای خاص. پیادهسازی مشابه است: بررسی هر کاراکتر از طریق Character.isLetterOrDigit یا مقایسه با فهرست کاراکترهای مجاز. چنین فیلترهایی در فیلدهای نام کاربری، نوارهای جستجو و سایر مکانهایی که کاراکترهای خاص مجاز نیستند استفاده میشوند.
اعمال InputFilter روی EditText
فیلترها روی EditText از طریق متد setFilters(InputFilter[]) تنظیم میشوند. آرایه فیلترها فیلترهای فعلی را جایگزین میکند، بنابراین اگر نیاز به افزودن فیلتر به فیلترهای موجود دارید، ابتدا باید فیلترهای فعلی را از طریق getFilters() دریافت کنید، یک آرایه جدید بسازید و آن را دوباره تنظیم کنید. EditText به طور پیشفرض یک فیلتر دارد — LengthFilter، که از طریق android:maxLength در XML تنظیم میشود.
kotlin
val editText = findViewById<EditText>(R.id.phone_input)
editText.filters = arrayOf(
DigitsInputFilter(),
InputFilter.LengthFilter(10)
)در مثال دو فیلتر تنظیم میشود: DigitsInputFilter (فقط ارقام) و LengthFilter (حداکثر 10 کاراکتر). ترتیب فیلترها در آرایه مهم است: فیلتر اول ورودی اصلی را دریافت میکند، آن را پردازش میکند و نتیجه را به فیلتر دوم منتقل میکند. اگر DigitsInputFilter بخشی از کاراکترها را فیلتر کند، LengthFilter متن فیلتر شده را میبیند و محدودیت طول خود را روی آن اعمال میکند.
همچنین میتوان فیلترها را از طریق ویژگی XML android:inputType تنظیم کرد که به صورت خودکار برخی فیلترها را اضافه میکند. به عنوان مثال، inputType="phone" باعث افزودن DigitsKeyListener میشود و فقط ارقام و برخی کاراکترهای خاص را مجاز میداند. با این حال، برای کنترل کامل فیلتر کردن توصیه میشود از setFilters به صورت برنامهنویسی استفاده کنید، به خصوص وقتی لازم است چندین قانون ترکیب شوند.
InputFilter و اعتبارسنجی ورودی
InputFilter و TextWatcher وظایف متفاوتی انجام میدهند و اغلب با هم استفاده میشوند. InputFilter در سطح ورود کار میکند — اجازه نمیدهد کاراکترهای نادرست وارد فیلد شوند. TextWatcher پس از ورود کار میکند — به شما امکان میدهد به تغییرات واکنش نشان دهید، اعتبارسنجی قوانین پیچیده را انجام دهید و UI را بهروزرسانی کنید. ترکیب دو رویکرد بهترین نتیجه را به ارمغان میآورد.
به عنوان مثال، برای فیلد ورود ایمیل: InputFilter میتواند فاصلهها و حروف سیریلیک را در سطح ورود ممنوع کند، و TextWatcher میتواند تطابق کامل با الگوی ایمیل را پس از هر تغییر بررسی کند. اولی از خطاهای واضح محافظت میکند، دومی — از خطاهای ساختاری. چنین تقسیم مسئولیتی کد را تمیزتر میکند و بار اعتبارسنجی را کاهش میدهد.
بر اساس Material Design Guidelines، فیلترها باید برای فیلدهایی با محدودیتهای سختگیرانه اعمال شوند: شماره تلفن، کد تأیید، کد PIN، کد پستی. برای فیلدهای با اعتبارسنجی نرم — نام، آدرس، نظر — TextWatcher کافی است تا مانع ورود مقادیر مجاز اما غیراستاندارد توسط کاربر نشویم.
| معیار | InputFilter | TextWatcher |
|---|---|---|
| زمان اعمال | پیش از تغییر متن | پس از تغییر متن |
| کاربرد | مسدود کردن کاراکترهای نادرست | واکنش به تغییرات، اعتبارسنجی، UI |
| مقدار برگشتی | متن فیلتر شده یا null | خیر (void) |
| نحوه اعمال | setFilters() | addTextChangedListener() |
سوالات متداول
تفاوت InputFilter با TextWatcher چیست؟
InputFilter ورودی را پیش از تغییر متن رهگیری میکند و میتواند آن را مسدود یا تغییر دهد. TextWatcher پس از تغییر فراخوانی میشود و امکان واکنش به مقدار جدید را فراهم میکند. InputFilter — محافظت پیشگیرانه، TextWatcher — پردازش پس از اعمال. برای اعتبارسنجی کامل فرم توصیه میشود از هر دو رویکرد استفاده کنید.
چگونه چند فیلتر را روی EditText اعمال کنیم؟
آرایه فیلترها را به متد setFilters() پاس دهید. فیلترها به صورت ترتیبی و مطابق ترتیب آرایه اجرا میشوند. برای اینکه فیلترهای موجود را از دست ندهید، آنها را از طریق getFilters() دریافت کنید، فیلترهای جدید را به یک کپی از آرایه اضافه کنید و از طریق setFilters تنظیم کنید. فیلترها را بدون در نظر گرفتن فیلترهای از قبل تنظیمشده بازنویسی نکنید.
آیا میتوان از InputFilter برای قالببندی متن استفاده کرد؟
بله، InputFilter میتواند ورودی را تغییر دهد و CharSequence تغییر یافته برگرداند. به عنوان مثال، فیلتر شماره تلفن میتواند فاصلهها یا پرانتزها را اضافه کند. با این حال، برای قالببندی پیچیده بهتر است InputFilter را با TextWatcher ترکیب کنید، زیرا فیلتر بر مسدود کردن تمرکز دارد نه پردازش پس از اعمال.
چه کاراکترهایی را میتوان از طریق InputFilter ممنوع کرد؟
هر چیزی: فاصلهها، حروف، ارقام، کاراکترهای خاص، کاراکترهای Unicode. در فیلتر سفارشی شما شرط Character.isLetter, isDigit, isWhitespace را تعیین میکنید یا با فهرست سیاه/سفید مقایسه میکنید. فیلتر میتواند فقط حروف لاتین، فقط حروف سیریلیک یا فقط مجموعه خاصی از کاراکترها را مجاز کند.
آیا InputFilter با تغییر برنامهنویسی متن کار میکند؟
خیر، InputFilter فقط هنگام ورود کاربر یا جایگذاری از کلیپبورد فعال میشود. اگر متن از طریق setText() به صورت برنامهنویسی تنظیم شود، فیلترها اعمال نمیشوند. برای بررسی متن برنامهنویسی از اعتبارسنجی از طریق TextWatcher یا بررسی صریح پیش از تنظیم استفاده کنید.
جمعبندی
- InputFilter — رابط اندروید برای فیلتر کردن و قالببندی ورودی در سطح کاراکترها پیش از نمایش در EditText.
- متد filter برای اجازه ورود null، برای مسدود کردن "" یا یک CharSequence جدید برای اصلاح برمیگرداند.
- LengthFilter و AllCaps — فیلترهای استاندارد Android SDK برای محدود کردن طول و تغییر حروف.
- فیلترهای سفارشی از طریق پیادهسازی رابط InputFilter با منطق دلخواه بررسی کاراکترها ساخته میشوند.
- زنجیره فیلترها امکان ترکیب چندین قانون را فراهم میکند که به صورت ترتیبی اجرا میشوند.
- InputFilter و TextWatcher با هم تداخل ندارند، بلکه مکمل یکدیگرند: اولی کاراکترها را مسدود میکند، دومی به تغییرات واکنش نشان میدهد.
- تغییر برنامهنویسی متن از طریق setText() از InputFilter عبور نمیکند — بررسی جداگانه لازم است.
ما یک اپلیکیشن موبایل به صورت کلید در دست توسعه خواهیم داد
IT Sectr از سال 2017 برنامههای iOS و Android را برای استارتاپها و کسبوکارها ایجاد میکند. ما به شما مشاوره میدهیم و بهترین راهحل را پیشنهاد خواهیم کرد.
همچنین بخوانید