قابلیت جستجو امروزه تقریباً در همه اپلیکیشن‌های وب و موبایل دیده می‌شود و به طور روزمره مورد استفاده قرار می‌گیرد. هر اپلیکیشن موبایل مانند توییتر را در نظر بگیرید، اگر بخواهید به دنبال یک فرد یا هشتگ بگردید، به محض این که شروع به نوشتن بکنید، می‌بینید که پیشنهادهایی در یک لیست بازشدنی ظاهر می‌شوند. جستجوی گوگل بهترین مثال برای این قابلیت است. به محض شروع به نوشتن یک کلیدواژه، پیشنهادهایی ارائه می‌کند که می‌توان از میان آن‌ها انتخاب کرد. زمانی که گزینه مطلوب انتخاب شد، متن انتخابی در فیلد جستجو نمایش پیدا می‌کند. این فر‌ایند موجب سهولت زیادی در کار می‌شود. در این مقاله شیوه پیاده‌سازی فهرست جستجوی تکمیل خودکار را در اپلیکیشن‌های فلاتر معرفی می‌کنیم.

نکته: توجه کنید که بین دو واژه «تکمیل خودکار» و «پیشنهاد خودکار» تفاوت وجود دارد و ما در این مقاله از فهرست تکمیل خودکار صحبت می‌کنیم. برای درک تفاوت کلیدی بین این دو اصطلاح به این صفحه (+) مراجعه کنید.

کاربرد

ما به دلیل مقاصد آموزشی یک ورودی Textfield ساده می‌سازیم که به محض وارد کردن نام بازیکن، نام کامل وی به همراه کشوری که در آن بازی می‌کند در یک فهرست ظاهر می‌شود تا امکان تکمیل خودکار جستجو وجود داشته باشد. زمانی که کاربری مدخلی را از فهرست انتخاب کند، آن مدخل در Textfield نمایش می‌یابد.

منابع داده

ما داده‌ها را از یک فایل JSON محلی استخراج می‌کنیم که در آن از قبل keyword و کلمه autocomplete مربوطه کنار هم تعریف شده‌اند. مقادیر country نیز که در نهایت در فهرست و زمانی که کاربر کلیدواژه را در رابط کاربری وارد می‌کند، نمایش پیدا می‌کنند، در همین فایل تعریف شده‌اند.

قطعه کد زیر ساختار فایل JSON را نشان می‌دهد:

 تکمیل خودکار

فلاتر افزونه‌های مختلفی برای پیاده‌سازی تکمیل خودکار در یک ورودی متنی ارائه می‌کند. افزونه‌ای که ما در این راهنما مورد استفاده قرار می‌دهیم Autocomplete_TextField است. دلایل استفاده از این افزونه به شرح زیر است:

  1. از چند نوع داده پشتیبانی می‌کند و استفاده آسانی دارد.
  2. این پکیج از سوی مالک آن به طور مرتب به‌روزرسانی می‌شود و بهبودهای خوبی مانند پشتیبانی از شیء علاوه بر مقادیر رشته‌ای نیز دارد که امکان تبدیل یک آیتم به کلاس را به جای String به دست می‌دهد.

کار خود را با ایجاد یک پروژه جدید فلاتر آغاز می‌کنیم:

کد موجود در main.dart را حذف می‌کنیم و ابتدا پکیج را در pubspec.yaml اضافه می‌کنیم:

دستور packages get را اجرا کنید تا پکیج مورد ارجاع را نصب کنید و همچنین پکیج مورد نظر را در main.dart ایمپورت نمایید:

همچنان که قبلاً اشاره کردیم، از یک فایل JSON محلی به عنوان منبع داده خود استفاده می‌کنیم و باید فایل را در پوشه assets به صورت زیر اضافه کنیم:

از آنجا که این پروژه جدیدی است که ساخته‌ایم، باید پوشه assets را در محل ریشه ایجاد کرده و JSON را مانند زیر کپی کرده و packages get را اجرا کنیم:

 تکمیل خودکار

برای واکشی داده‌ها JSON باید ابتدا آن را تجزیه کنیم. به این منظور یک شیء Plain Old Dart می‌سازیم تا نماینده ساختار JSON باشد. نام آن را players.dart می‌گذاریم:

توجه کنید که بررسی جزییات تجزیه ساختمان JSON خارج از حیطه این مقاله است.

اکنون ما شیئی از ساختمان JSON داریم که به آن ارجاع بدهیم، اما باید بتوانیم آن را دیکود کرده و داده‌ها را با ارائه مسیر JSON محلی نیز بارگذاری کنیم. به این منظور کلاس دیگری به نام PlayersViewModel در players.dart ایجاد می‌کنیم که در آن لیست استاتیکی از کلاس Players ایجاد کرده و داده‌های دیکود شده JSON را اضافه می‌کنیم.

متد ()loadPlayers را از فایل main.dart درون ()initState فراخوانی می‌کنیم تا داده‌ها در اختیار ما قرار گیرند و در زمان اجرای اپلیکیشن بتوانیم از آن‌ها به سهولت استفاده کنیم.

در فایل main.dart ساختمان اصلی دمو را می‌سازیم. کد مرتبط با ورودی متنی تکمیل خودکار را گام به گام اضافه خواهیم کرد:

کد فوق کاملاً سرراست است و نکته تازه‌ای ندارد. اینک UI به صورت زیر در آمده است:

 تکمیل خودکار

اکنون textfield را اضافه خواهیم کرد. به جای استفاده از ویجت TextField در فلاتر از AutoCompleteTextField استفاده می‌کنیم. این کلاس مشخصه‌ها و متدهای ساده و متنوعی دارد. این موارد در ادامه مقاله بیشتر بررسی می‌کنیم، اما اینک از این کلاس مانند زیر درون کلاس AutoCompleteState_‎ استفاده می‌کنیم:

از آنجا که AutoCompleteTextField یک اکستنشن از ویجت TextField است، همه مشخصه‌های خود را که برای ساخت و نمایش textfield ابتدایی شامل متن سرنخ ضروری هستند به ارث می‌برد. ابتدا این مورد را اضافه می‌کنیم. درون تابع build و زیر ویجت Column کد زیر را اضافه می‌کنیم تا textfield مقدماتی با یک سرنخ نمایش پیدا کند:

چنان که احتمالاً متوجه شده‌اید، کلاس Players به عنوان نوع داده به سازنده AutoCompleteTextField ارسال شده است، چون امکان ارائه هر نوع داده را به صورت پیشنهاد فراهم می‌سازد. کد فوق در UI به صورت زیر رندر می‌شود:

 تکمیل خودکار

سپس اگر ماوس را روی خط کد AutoCompleteTextField<Players>‎ از شما می‌خواهد که پارامترهای الزامی را پیاده‌سازی کنید. این موارد به صورت زیر هستند:

ابتدا آن‌ها را یک به یک بررسی می‌کنیم و کمکی که هر کدام به ما در پیاده‌سازی لیست تکمیل خودکار دارند را توضیح می‌دهیم.

itemBuilder

این یک callback برای ساخت هر آیتم در لیستی است که قرار است نمایش یابد و شامل داده‌های پیشنهادی است و یک ویجت بازگشت می‌دهد. ما کدی را درون این پارامتر اضافه می‌کنیم که در عمل داده‌های AutoCompleteTerm و country را در زمانی که کاربر کلیدواژه‌ای را وارد می‌کند رندر خواهد کرد.

itemFilter

این یک callback برای فیلتر کردن آیتم است و بسته به متن ورودی مقدار درست/نادرست بازگشت می‌دهد. اگر یک تطبیق با نام بازیکن وارد شده پیدا شود، مقدار درست بازگشت می‌یابد و متن مرتبط نمایش پیدا می‌کند و در غیر این صورت هیچ نام تطبیق یافته‌ای نشان داده نمی‌شود.

itemSorter

یک callback برای مرتب‌سازی آیتم‌ها محسوب می‌شود.

itemSubmitted

این یک callback روی آیتم منتخب است. پس از این که آیتم از لیست انتخاب شد، این پارامتر آن آیتم را در textfield تنظیم می‌کند. از آنجا که باید آیتم منتخب را در Textfield حفظ کنیم، کد مورد نظر را درون متد ()setState قرار می‌دهیم. کد درون آن، آیتم منتخب را گرفته و آن را در Textfield قرار می‌دهد.

برای تعیین/بازیابی مقدار از Textfield باید از کلاس TextEditingController استفاده کنیم، به طوری که هر زمان هر مقداری در TextEditingController به‌روزرسانی شد یا متن تغییر یافت، بتوانیم به کنترلر گوش دهیم. به این منظور باید controller را به عنوان یک وهله جدید از کلاس TextEditingController به صورت زیر اعلان کنیم:

Key

یک کلید عمومی از نوع GlobalKey<AutoCompleteTextFieldState<T>>‎ است که برای فعال‌سازی افزودن پیشنهادها به textfiled ضروری است. همچنین متد ()clear می‌تواند در صورت نیاز برای پاک کردن فراخوانی شود.

Suggestions

این گزینه پیشنهادهایی را که قرار است در رابط کاربری نمایش پیدا کنند فعال می‌کند و ما وهله‌ای از کلاس PlayersViewModel را در این جا فرا می‌خوانیم تا پیشنهادها را بارگذاری کند.

بدین ترتیب ما همه پارامترهای الزامی را از کلاس AutoCompleteTextField پیاده‌سازی کرده‌ایم. اما چنان که قبلاً اشاره کردیم باید داده‌های بازیکن را با فراخوانی متد loadPlayers که در players.dart بارگذاری کنیم. این کار را با ایجاد یک متد viod به نام ()loadData_ و فراخوانی ()PlayersViewModel.loadPlayers انجام می‌دهیم:

اکنون اپلیکیشن را اجرا می‌کنیم و خروجی را تماشا می‌کنیم:

 تکمیل خودکار

اینک زمانی که کلیدواژه‌ای را به صورت تک حرف یا کلمه وارد کنیم، پیشنهادهای منطبق شروع به نمایش پیدا می‌کنند.

اما هنوز یک بخش مهم ناقص است. اگر نامی را از لیست انتخاب کنیم، آن نام باید در textfield نمایش پیدا کند اما فعلاً این اتفاق نمی‌افتد. AutoCompleteTextField پارامتری به نام clearOnSubmit دارد که یک مقدار بولی می‌گیرد تا در زمان ارسال autocompletetextfield را پاک کند. ما باید آن را روی flase تنظیم کنیم تا نام منتخب در فیلد نمایش یابد.

اینک خروجی کامل را روی هر دو پلتفرم نگاه می‌کنیم:

 تکمیل خودکار  

بدین ترتیب با موفقیت قابلیت تکمیل خودکار لیست جستجو را پیاده‌سازی کردیم. برای مشاهده کد کامل این اپلیکیشن به این ریپوی گیت‌هاب (+) مراجعه کنید.

همچنین می‌توانید ظاهر UI و حس و حال لیست تکمیل خودکار و متن درون آن را شخصی‌سازی کنید. به این منظور ویجت Row را درون یک Container قرار دهید که امکان تغییر رنگ پس‌زمینه لیست و استایل‌بندی متن را بسته به نیاز فراهم می‌کند. به مثال زیر توجه کنید:

 تکمیل خودکار در فلاتر

اگر این مطلب برای شما مفید بوده است، آموزش‌های زیر نیز به شما پیشنهاد می‌شوند:

==

میثم لطفی (+)

«میثم لطفی» دانش‌آموخته ریاضیات و شیفته فناوری به خصوص در حوزه رایانه است. وی در حال حاضر علاوه بر پیگیری علاقه‌مندی‌هایش در رشته‌های برنامه‌نویسی، کپی‌رایتینگ و محتوای چندرسانه‌ای، در زمینه نگارش مقالاتی با محوریت نرم‌افزار نیز با مجله فرادرس همکاری دارد.

بر اساس رای 1 نفر

آیا این مطلب برای شما مفید بود؟

نظر شما چیست؟

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *