إضافة أدوات الاختيار إلى تطبيقك

يوفر 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 واسم علامة فريد للجزء.

استخدام أدوات الاختيار مع ميزة الملء التلقائي

في عام 2017، طرح 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.

لمزيد من المعلومات حول إثبات توافق ميزة الملء التلقائي لطرق العرض المخصّصة، يُرجى الاطّلاع على إطار عمل الملء التلقائي.