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

تجربة طريقة Compose

‫Jetpack Compose هي مجموعة أدوات واجهة المستخدِم المقترَحة لنظام Android. تعرَّف على كيفية إضافة المكوّنات في Compose.

أدوات اختيار التاريخ ←

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

ملاحظة: للحصول على تجربة أفضل للمستخدمين، يمكنك الاطّلاع على مستندات أداة اختيار التاريخ وأداة اختيار الوقت في التصميم المتعدد الأبعاد.

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

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

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

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

لمزيد من المعلومات عن إثبات إمكانية استخدام ميزة "الملء التلقائي" لطرق العرض المخصّصة، يمكنك الاطّلاع على إطار عمل "الملء التلقائي".