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

تجربة ميزة "الكتابة"
‫Jetpack Compose هي مجموعة أدوات واجهة المستخدم المُقترَحة لنظام التشغيل Android. تعرَّف على كيفية إضافة مكوّنات في ميزة "الإنشاء".
أداوات اختيار التاريخ →

ويوفر Android عناصر تحكم للمستخدمين لاختيار الوقت أو التاريخ كمربعات حوار جاهزة للاستخدام. توفر أدوات الاختيار هذه عناصر تحكم لاختيار كل جزء من الوقت (الساعة، الدقيقة، صباحًا/مساءً) أو التاريخ (الشهر واليوم والسنة).

مثال لأداة اختيار الوقت من material.io
الشكل 1. اختيار ساعة في أداة اختيار التقويم على الأجهزة الجوّالة

يساعد استخدام هذه الأدوات في ضمان تمكّن المستخدمين من اختيار وقت أو تاريخ صالحَين وهما منسَّقان بشكل صحيح ومُعدَّلان حسب لغة المستخدم.

مثال لأداة اختيار التاريخ من النافذة المنبثقة من material.io
الشكل 2. أداة اختيار التاريخ في وضع النافذة المنبثقة

ننصحك باستخدام السمة DialogFragment لاستضافة كل أداة اختيار وقت أو تاريخ. ويدير DialogFragment دورة حياة مربع الحوار نيابةً عنك، كما يتيح لك عرض أدوات الاختيار بتكوينات تنسيق مختلفة، كما هو الحال في مربع حوار أساسي على الهواتف المحمولة أو كجزء مضمّن من التنسيق على الشاشات الكبيرة.

إنشاء أداة اختيار الوقت

لعرض علامة TimePickerDialog باستخدام DialogFragment، حدِّد فئة تجزئة تمتد DialogFragment وعرض TimePickerDialog من طريقة onCreateDialog() للجزء.

توسيع DialogFragment لأداة اختيار الوقت

لتحديد DialogFragment للسمة TimePickerDialog، عليك اتّباع الخطوات التالية:

  • حدِّد طريقة onCreateDialog() لإرجاع مثيل من TimePickerDialog.
  • يمكنك تنفيذ واجهة TimePickerDialog.OnTimeSetListener لتلقي معاودة الاتصال عندما يضبط المستخدم الوقت.

وفي ما يلي مثال لذلك:

Kotlin

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.
    }
}

Java

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" />

عندما ينقر المستخدم على هذا الزر، يستدعي النظام الطريقة التالية:

Kotlin

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

Java

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 لتلقّي مكالمة هاتفية عندما يحدّد المستخدم التاريخ.

وفي ما يلي مثال لذلك:

Kotlin

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.
    }
}

Java

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"/>

عندما ينقر المستخدم على هذا الزر، يستدعي النظام الطريقة التالية:

Kotlin

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

Java

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. يعدّل العرض property text باستخدام تمثيل سلسلة للقيمة التي يختارها المستخدم في أداة الاختيار.

للحصول على مثال على فئة فرعية من EditText تعالج قيم AUTOFILL_TYPE_DATE، اطّلِع على نموذج إطار عمل الملء التلقائي في Java أو Kotlin.

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