افزودن انتخابگر به برنامه

امتحان کردن روش Compose

Jetpack Compose جعبه‌ابزار واسط کاربر توصیه‌شده برای Android است. با نحوه افزودن مؤلفه‌ها در Compose آشنا شوید.

انتخابگر تاریخ →

Android کنترل‌هایی را برای کاربر فراهم می‌کند تا زمان یا تاریخ را به‌صورت کادرهای گفتگوی آماده استفاده انتخاب کند. این انتخاب‌گرها کنترل‌هایی برای انتخاب هر بخش از زمان (ساعت، دقیقه، قبل‌ازظهر/بعدازظهر) یا تاریخ (ماه، روز، سال) ارائه می‌دهند.

توجه: برای تجربه کاربری بهتر، به اسناد انتخابگر تاریخ و انتخابگر زمان در «طراحی مواد» مراجعه کنید.

شکل ۱. انتخاب ساعت در انتخاب‌گر تقویم تلفن همراه.

استفاده از این انتخابگرها کمک می‌کند مطمئن شوید کاربران می‌توانند زمان یا تاریخی را انتخاب کنند که معتبر باشد، به‌درستی قالب‌بندی شده باشد، و با منطقه زبانی کاربر مطابقت داشته باشد.

شکل ۲. انتخاب‌گر تاریخ مدال.

توصیه می‌کنیم از DialogFragment برای میزبانی هر انتخابگر زمان یا تاریخ استفاده کنید. DialogFragment چرخه حیات گفتگو را برای شما مدیریت می‌کند و به شما امکان می‌دهد انتخابگرها را در پیکربندی‌های مختلف چیدمان نمایش دهید، مثلاً در یک گفتگوی ساده در گوشی‌ها یا به‌عنوان بخشی جاسازی‌شده از چیدمان در صفحه‌نمایش‌های بزرگ.

ایجاد انتخاب‌گر زمان

برای نمایش TimePickerDialog بااستفاده از DialogFragment، کلاس قطعه‌ای را تعریف کنید که DialogFragment را گسترش دهد و TimePickerDialog را از روش onCreateDialog() قطعه برگرداند.

گسترش دادن DialogFragment برای انتخاب‌گر زمان

برای تعریف کردن DialogFragment برای TimePickerDialog، کارهای زیر را انجام دهید:

• روش onCreateDialog() را برای برگرداندن نمونه‌ای از TimePickerDialog تعریف کنید.
• واسط TimePickerDialog.OnTimeSetListener را پیاده‌سازی کنید تا وقتی کاربر زمان را تنظیم می‌کند، بازخوانی دریافت کنید.

مثالی در اینجا ارائه شده است:

کاتلین

class TimePickerFragment : DialogFragment(), TimePickerDialog.OnTimeSetListener {

    override fun onCreateDialog(savedInstanceState: Bundle): Dialog {
        // Use the current time as the default values for the picker.
        val c = Calendar.getInstance()
        val hour = c.get(Calendar.HOUR_OF_DAY)
        val minute = c.get(Calendar.MINUTE)

        // Create a new instance of TimePickerDialog and return it.
        return TimePickerDialog(activity, this, hour, minute, DateFormat.is24HourFormat(activity))
    }

    override fun onTimeSet(view: TimePicker, hourOfDay: Int, minute: Int) {
        // Do something with the time the user picks.
    }
}

جاوا

public static class TimePickerFragment extends DialogFragment
                            implements TimePickerDialog.OnTimeSetListener {

    @Override
    public Dialog onCreateDialog(Bundle savedInstanceState) {
        // Use the current time as the default values for the picker.
        final Calendar c = Calendar.getInstance();
        int hour = c.get(Calendar.HOUR_OF_DAY);
        int minute = c.get(Calendar.MINUTE);

        // Create a new instance of TimePickerDialog and return it.
        return new TimePickerDialog(getActivity(), this, hour, minute,
                DateFormat.is24HourFormat(getActivity()));
    }

    public void onTimeSet(TimePicker view, int hourOfDay, int minute) {
        // Do something with the time the user picks.
    }
}

برای اطلاعات درباره آرگومان‌های سازنده، کلاس TimePickerDialog را ببینید.

اکنون فقط به رویدادی نیاز دارید که نمونه‌ای از این قطعه را به فعالیت شما اضافه کند.

نمایش انتخاب‌گر زمان

پس‌از تعریف کردن DialogFragment مانند آنچه در مثال قبلی آمده است، می‌توانید با ایجاد نمونه‌ای از DialogFragment و فراخوانی روش show()، انتخابگر زمان را نمایش دهید.

برای مثال، در اینجا دکمه‌ای وجود دارد که وقتی روی آن ضربه می‌زنید، روشی را برای نمایش کادر گفتگو فراخوانی می‌کند:

<Button
    android:id="@+id/pickTime"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Pick time" />

وقتی کاربر روی این دکمه تک‌ضرب می‌زند، سیستم روش زیر را فراخوانی می‌کند:

کاتلین

findViewById<Button>(R.id.pickTime).setOnClickListener {
    TimePickerFragment().show(supportFragmentManager, "timePicker")
}

جاوا

findViewById<Button>(R.id.pickTime).setOnClickListener {
    TimePickerFragment().show(supportFragmentManager, "timePicker");
}

این روش show() را در نمونه جدیدی از DialogFragment تعریف‌شده در مثال قبلی فراخوانی می‌کند. روش show() به نمونه‌ای از FragmentManager و نام برچسب یکتا برای قطعه نیاز دارد.

ایجاد انتخاب‌گر تاریخ

ایجاد DatePickerDialog مثل ایجاد TimePickerDialog است. تفاوت در کادر گفتگویی است که برای قطعه ایجاد می‌کنید.

برای نمایش DatePickerDialog بااستفاده از DialogFragment، کلاس قطعه‌ای را تعریف کنید که DialogFragment را گسترش دهد و DatePickerDialog را از روش onCreateDialog() قطعه برگرداند.

گسترش دادن DialogFragment برای انتخاب‌گر تاریخ

برای تعریف کردن DialogFragment برای DatePickerDialog، کارهای زیر را انجام دهید:

• روش onCreateDialog() را برای برگرداندن نمونه‌ای از DatePickerDialog تعریف کنید.
• واسط DatePickerDialog.OnDateSetListener را پیاده‌سازی کنید تا وقتی کاربر تاریخ را تنظیم می‌کند، بازخوان دریافت کنید.

مثالی در اینجا ارائه شده است:

کاتلین

class DatePickerFragment : DialogFragment(), DatePickerDialog.OnDateSetListener {

    override fun onCreateDialog(savedInstanceState: Bundle): Dialog {
        // Use the current date as the default date in the picker.
        val c = Calendar.getInstance()
        val year = c.get(Calendar.YEAR)
        val month = c.get(Calendar.MONTH)
        val day = c.get(Calendar.DAY_OF_MONTH)

        // Create a new instance of DatePickerDialog and return it.
        return DatePickerDialog(requireContext(), this, year, month, day)

    }

    override fun onDateSet(view: DatePicker, year: Int, month: Int, day: Int) {
        // Do something with the date the user picks.
    }
}

جاوا

public static class DatePickerFragment extends DialogFragment
                            implements DatePickerDialog.OnDateSetListener {

    @Override
    public Dialog onCreateDialog(Bundle savedInstanceState) {
        // Use the current date as the default date in the picker.
        final Calendar c = Calendar.getInstance();
        int year = c.get(Calendar.YEAR);
        int month = c.get(Calendar.MONTH);
        int day = c.get(Calendar.DAY_OF_MONTH);

        // Create a new instance of DatePickerDialog and return it.
        return new DatePickerDialog(requireContext(), this, year, month, day);
    }

    public void onDateSet(DatePicker view, int year, int month, int day) {
        // Do something with the date the user picks.
    }
}

برای کسب اطلاعات درباره آرگومان‌های سازنده، به کلاس DatePickerDialog مراجعه کنید.

فقط به رویدادی نیاز دارید که نمونه‌ای از این قطعه را به فعالیتتان اضافه کند.

نمایش انتخاب‌گر تاریخ

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

برای مثال، در اینجا دکمه‌ای وجود دارد که وقتی روی آن ضربه می‌زنید، روشی را برای نمایش کادر گفتگو فراخوانی می‌کند:

<Button
    android:id="@+id/pickDate"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Pick date"/>

وقتی کاربر روی این دکمه تک‌ضرب می‌زند، سیستم روش زیر را فراخوانی می‌کند:

کاتلین

findViewById<Button>(R.id.pickDate).setOnClickListener {
    val newFragment = DatePickerFragment()
    newFragment.show(supportFragmentManager, "datePicker")
}

جاوا

findViewById<Button>(R.id.pickDate).setOnClickListener {
    val newFragment = DatePickerFragment();
    newFragment.show(supportFragmentManager, "datePicker");
}

این روش show() را در نمونه جدیدی از DialogFragment تعریف‌شده در مثال قبلی فراخوانی می‌کند. روش show() به نمونه‌ای از FragmentManager و نام برچسب یکتا برای قطعه نیاز دارد.

استفاده از انتخابگرها با تکمیل خودکار

در سال ۲۰۱۷، Android چارچوب تکمیل خودکار را معرفی کرد که به کاربران اجازه می‌دهد داده‌هایی را که می‌توانند برای تکمیل فرم‌ها در برنامه‌های مختلف استفاده شوند ذخیره کنند. انتخاب‌گرها می‌توانند در سناریوهای تکمیل خودکار مفید باشند، زیرا واسط کاربری‌ای ارائه می‌دهند که به کاربران اجازه می‌دهد مقدار فیلدی را که داده‌های تاریخ یا زمان را ذخیره می‌کند تغییر دهند. برای مثال، در فرم کارت اعتباری، انتخابگر تاریخ به کاربران اجازه می‌دهد تاریخ انقضای کارت اعتباری‌شان را وارد یا تغییر دهند.

ازآنجایی‌که انتخابگرها کادر گفتگو هستند، در فعالیت به‌همراه فیلدهای دیگر نمایش داده نمی‌شوند. برای نمایش داده‌های انتخابگر وقتی انتخابگر نمایان نیست، می‌توانید از نمای دیگری استفاده کنید، مثلاً EditText، که می‌تواند مقدار را وقتی انتخابگر نمایان نیست نمایش دهد.

شیء EditText به‌طور پیش‌فرض داده‌های تکمیل خودکار از نوع AUTOFILL_TYPE_TEXT را می‌پذیرد. درمقابل، سرویس‌های تکمیل خودکار داده‌ها را به‌صورت AUTOFILL_TYPE_DATE ذخیره می‌کنند تا نمایش مناسبی از آن ایجاد کنند. برای حل ناسازگاری در انواع، توصیه می‌کنیم نمای سفارشی‌ای ایجاد کنید که از EditText ارث‌بری کند و روش‌های لازم برای مدیریت صحیح مقادیر نوع AUTOFILL_TYPE_DATE را پیاده‌سازی کند.

برای ایجاد زیرکلاس EditText که بتواند مقادیر نوع AUTOFILL_TYPE_DATE را مدیریت کند، مراحل زیر را دنبال کنید:

1. کلاسی ایجاد کنید که از EditText ارث‌بری کند.
2. روش getAutofillType() را که AUTOFILL_TYPE_DATE را برمی‌گرداند پیاده‌سازی کنید.
3. روش getAutofillValue() را پیاده‌سازی کنید که شیء AutofillValue را برمی‌گرداند که تاریخ را به میلی‌ثانیه نشان می‌دهد. برای ایجاد شیء برگشتی، از روش forDate() برای تولید شیء AutofillValue استفاده کنید.
4. روش autofill() را پیاده‌سازی کنید. این روش منطق لازم را برای مدیریت پارامتر AutofillValue که از نوع AUTOFILL_TYPE_DATE است ارائه می‌دهد. برای مدیریت پارامتر، نمایش رشته‌ای مناسبی از آن ایجاد کنید، مثلاً mm/yyyy. از نمایش رشته برای تنظیم ویژگی text نمای خود استفاده کنید.
5. عملکردی را پیاده‌سازی کنید که وقتی کاربر می‌خواهد تاریخ را در زیرکلاس سفارشی EditText ویرایش کند، انتخاب‌گری را نمایش دهد. نمای به‌روزرسانی‌ها مشخصه text با نمایش رشته‌ای از مقداری که کاربر در انتخابگر انتخاب می‌کند.

برای نمونه‌ای از زیرکلاس EditText که مقادیر AUTOFILL_TYPE_DATE را مدیریت می‌کند، نمونه «چارچوب تکمیل خودکار» را در Java یا Kotlin ببینید.

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