منتقي التاريخ

تتيح أداة اختيار التاريخ للمستخدمين اختيار تاريخ أو نطاق زمني أو كليهما. تستخدم مربّع حوار التقويم أو إدخال النص للسماح للمستخدمين باختيار التواريخ

الأنواع

هناك ثلاثة أنواع من منتقي التاريخ:

• جزء من الشاشة: يظهر مضمّنًا في التنسيق. وهي مناسبة للإطارات الصغيرة التنسيقات التي قد يبدو فيها مربع الحوار المخصص تطفليًا.
• نمط: يظهر كمربّع حوار متراكبًا على محتوى التطبيق. يوفر هذا مسح التركيز على اختيار التاريخ.
• الإدخال المشروط: يدمج هذا الحقل حقلاً نصيًا مع أداة اختيار التاريخ المشروطة.

يمكنك تطبيق منتقي التاريخ هذا في تطبيقك باستخدام ما يلي عناصر قابلة للإنشاء:

• DatePicker: عام قابل للإنشاء لأداة اختيار التاريخ. تحتوي الحاوية التي واستخدامها يحدد ما إذا كان مثبّتًا على قاعدة الإرساء أو إلى النموذج.
• DatePickerDialog: حاوية تاريخ الإدخال المشروط والنمطي المنتقيين.
• DateRangePicker: لأي أداة اختيار تاريخ يمكن للمستخدم فيها اختيار نطاق مع تاريخ بدء وتاريخ انتهاء.

ملاحظة: DatePicker وDatePickerDialog وDateRangePicker في مرحلة تجريبية. يُرجى الإبلاغ عن أيّ مشاكل في أداة تتبُّع المشاكل.

الولاية

المعلمة الرئيسية التي تشترك فيها أدوات اختيار التاريخ المختلفة والقابلة للإنشاء هي state، والذي يأخذ إما DatePickerState أو الكائن DateRangePickerState. تلتقط ممتلكاتها معلومات عن اختيار المستخدم باستخدام أداة اختيار التاريخ، مثل التاريخ المحدّد الحالي.

لمزيد من المعلومات حول كيفية الاستفادة من التاريخ المحدّد، راجِع مقالة استخدام قسم التاريخ الذي اخترته.

أداة اختيار التاريخ الذي تم إرساؤه

في المثال التالي، يوجد حقل نصي يطلب من المستخدم إدخال وتاريخ ميلادهم. عندما ينقر المستخدم على رمز التقويم في الحقل، فإنه يفتح منتقي تاريخ قاعدة الإرساء أسفل حقل الإدخال.

@Composable
fun DatePickerDocked() {
    var showDatePicker by remember { mutableStateOf(false) }
    val datePickerState = rememberDatePickerState()
    val selectedDate = datePickerState.selectedDateMillis?.let {
        convertMillisToDate(it)
    } ?: ""

    Box(
        modifier = Modifier.fillMaxWidth()
    ) {
        OutlinedTextField(
            value = selectedDate,
            onValueChange = { },
            label = { Text("DOB") },
            readOnly = true,
            trailingIcon = {
                IconButton(onClick = { showDatePicker = !showDatePicker }) {
                    Icon(
                        imageVector = Icons.Default.DateRange,
                        contentDescription = "Select date"
                    )
                }
            },
            modifier = Modifier
                .fillMaxWidth()
                .height(64.dp)
        )

        if (showDatePicker) {
            Popup(
                onDismissRequest = { showDatePicker = false },
                alignment = Alignment.TopStart
            ) {
                Box(
                    modifier = Modifier
                        .fillMaxWidth()
                        .offset(y = 64.dp)
                        .shadow(elevation = 4.dp)
                        .background(MaterialTheme.colorScheme.surface)
                        .padding(16.dp)
                ) {
                    DatePicker(
                        state = datePickerState,
                        showModeToggle = false
                    )
                }
            }
        }
    }
}

fun convertMillisToDate(millis: Long): String {
    val formatter = SimpleDateFormat("MM/dd/yyyy", Locale.getDefault())
    return formatter.format(Date(millis))
}
DatePickers.kt

ملاحظة: هذا المثال مستند بذاته. لمعرفة كيفية عرض التاريخ المحدّد إلى أحد الوالدَين قابل للإنشاء، اطّلِع على الأمثلة الأخرى.

النقاط الرئيسية حول الرمز البرمجي

• تظهر أداة اختيار التاريخ عندما ينقر المستخدم على IconButton.
  • يعمل زر الرمز كوسيطة لحساب OutlinedTextField مَعلمة trailingIcon.
  • يتحكّم متغير الحالة showDatePicker في إمكانية رؤية أداة اختيار تاريخ قاعدة الإرساء
• حاوية أداة اختيار التاريخ هي حاوية Popup قابلة للإنشاء، وتظهر على سطح الصفحة المحتوى دون التأثير في تخطيط العناصر الأخرى.
• يحصل selectedDate على قيمة التاريخ المحدّد من عنصر DatePickerState وينسقه باستخدام convertMillisToDate الأخرى.
• يظهر التاريخ المحدد في حقل النص.
• يتم وضع أداة اختيار التاريخ في وضع الإرساء أسفل حقل النص باستخدام offset. مفتاح التعديل.
• يتم استخدام Box كحاوية جذر للسماح بطبقات النص بشكل مناسب. ومنتقي التاريخ.

النتائج

بعد النقر على رمز التقويم، تظهر طريقة التنفيذ هذه على النحو التالي:

الشكل 1. أداة اختيار التاريخ على قاعدة الإرساء

أداة اختيار التاريخ المشروط

تعرض أداة اختيار التاريخ المشروطة مربّع حوار يطفو فوق الشاشة. للتنفيذ أنشئ DatePickerDialog وأرسِله إلى DatePicker.

@Composable
fun DatePickerModal(
    onDateSelected: (Long?) -> Unit,
    onDismiss: () -> Unit
) {
    val datePickerState = rememberDatePickerState()

    DatePickerDialog(
        onDismissRequest = onDismiss,
        confirmButton = {
            TextButton(onClick = {
                onDateSelected(datePickerState.selectedDateMillis)
                onDismiss()
            }) {
                Text("OK")
            }
        },
        dismissButton = {
            TextButton(onClick = onDismiss) {
                Text("Cancel")
            }
        }
    ) {
        DatePicker(state = datePickerState)
    }
}
DatePickers.kt

النقاط الرئيسية حول الرمز البرمجي

• تعرض دالة DatePickerModal القابلة للإنشاء أداة اختيار تاريخ مشروطة.
• يتم تنفيذ تعبير lambda onDateSelected عندما يختار المستخدم التاريخ.
  • يعرض التاريخ المحدّد للعنصر الرئيسي القابل للإنشاء.
• يتم تنفيذ تعبير lambda onDismiss عندما يرفض المستخدم .

النتائج

تظهر طريقة التنفيذ هذه على النحو التالي:

الشكل 2. أداة اختيار التاريخ المشروطة

أداة اختيار التاريخ المشروط الذي تم إدخاله

يعرض منتقي التاريخ المشروط الذي يتضمن إدخالاً مربع حوار يطفو فوق الشاشة يسمح للمستخدم بإدخال تاريخ.

@Composable
fun DatePickerModalInput(
    onDateSelected: (Long?) -> Unit,
    onDismiss: () -> Unit
) {
    val datePickerState = rememberDatePickerState(initialDisplayMode = DisplayMode.Input)

    DatePickerDialog(
        onDismissRequest = onDismiss,
        confirmButton = {
            TextButton(onClick = {
                onDateSelected(datePickerState.selectedDateMillis)
                onDismiss()
            }) {
                Text("OK")
            }
        },
        dismissButton = {
            TextButton(onClick = onDismiss) {
                Text("Cancel")
            }
        }
    ) {
        DatePicker(state = datePickerState)
    }
}
DatePickers.kt

النقاط الرئيسية حول الرمز البرمجي

يشبه هذا إلى حد كبير مثال أداة اختيار التاريخ المشروط. الأساسية هو ما يلي:

• تضبط المَعلمة initialDisplayMode وضع العرض الأولي على DisplayMode.Input

الشكل 3. أداة اختيار التاريخ المشروط مع البيانات التي تم إدخالها

أداة اختيار التاريخ بالنطاق

يمكنك إنشاء أداة اختيار تاريخ تتيح للمستخدم اختيار نطاق بين تاريخ بدء. وتاريخ الانتهاء. لإجراء ذلك، استخدِم DateRangePicker.

استخدام DateRangePicker في الأساس هو نفسه استخدام DatePicker. يمكنك استخدِمها لأداة الاختيار في وضع الإرساء كعنصر فرعي لتطبيق PopUp، أو يمكنك استخدامها كأداة اختيار أداة الاختيار المشروطة وتمريرها إلى DatePickerDialog. الاختلاف الأساسي هو التي تستخدمينها DateRangePickerState بدلاً من DatePickerState

يوضح المقتطف التالي كيفية إنشاء أداة اختيار تاريخ مشروطة النطاق:

@Composable
fun DateRangePickerModal(
    onDateRangeSelected: (Pair<Long?, Long?>) -> Unit,
    onDismiss: () -> Unit
) {
    val dateRangePickerState = rememberDateRangePickerState()

    DatePickerDialog(
        onDismissRequest = onDismiss,
        confirmButton = {
            TextButton(
                onClick = {
                    onDateRangeSelected(
                        Pair(
                            dateRangePickerState.selectedStartDateMillis,
                            dateRangePickerState.selectedEndDateMillis
                        )
                    )
                    onDismiss()
                }
            ) {
                Text("OK")
            }
        },
        dismissButton = {
            TextButton(onClick = onDismiss) {
                Text("Cancel")
            }
        }
    ) {
        DateRangePicker(
            state = dateRangePickerState,
            title = {
                Text(
                    text = "Select date range"
                )
            },
            showModeToggle = false,
            modifier = Modifier
                .fillMaxWidth()
                .height(500.dp)
                .padding(16.dp)
        )
    }
}
DatePickers.kt

النقاط الرئيسية حول الرمز البرمجي

• المعلمة onDateRangeSelected هي استدعاء تتلقى Pair<Long?, Long?> الذي يمثّل تاريخَي البدء والانتهاء المحدّدَين. هذا النمط لمنح الأصل القابل للإنشاء إمكانية الوصول إلى النطاق المحدد.
• تنشئ rememberDateRangePickerState() الحالة للنطاق الزمني. المنتقي.
• تنشئ DatePickerDialog حاوية مربّع حوار مشروطة.
• في معالج onClick لزر التأكيد، يتم تمرير onDateRangeSelected. النطاق المحدد إلى العنصر الرئيسي القابل للإنشاء.
• يعمل عنصر DateRangePicker القابل للإنشاء كمحتوى مربّع الحوار.

النتائج

تظهر طريقة التنفيذ هذه على النحو التالي:

الشكل 4. أداة اختيار التاريخ المشروط مع نطاق محدّد

استخدام التاريخ المحدّد

لالتقاط التاريخ المحدّد، يجب تتبّعه في العنصر الرئيسي القابل للإنشاء على أنّه Long و تمرير القيمة إلى DatePicker في onDateSelected. المقتطف التالي ذلك، على الرغم من أنه يمكنك الاطلاع على التنفيذ الكامل في الصفحة الرئيسية والمقتطفات.

// ...
    var selectedDate by remember { mutableStateOf<Long?>(null) }
// ...
        if (selectedDate != null) {
            val date = Date(selectedDate!!)
            val formattedDate = SimpleDateFormat("MMM dd, yyyy", Locale.getDefault()).format(date)
            Text("Selected date: $formattedDate")
        } else {
            Text("No date selected")
        }
// ...
        DatePickerModal(
            onDateSelected = {
                selectedDate = it
                showModal = false
            },
            onDismiss = { showModal = false }
        )
    }
// ...
DatePickers.kt

ينطبق الأمر نفسه بشكل أساسي على أدوات اختيار تاريخ النطاق، ولكن عليك استخدام Pair<Long?, Long?> أو فئة بيانات للحصول على قيم البداية والنهاية.

ملاحظة مهمة: بدلاً من استخدام Long في التاريخ المحدّد، يمكنك اجتياز كائن الحالة نفسه من العنصر الرئيسي القابل للإنشاء إلى العنصر الثانوي القيام بذلك قد يسمح يمكنك الحصول على الحالة الكاملة في الجهاز الرئيسي.

انظر أيضًا

• أداة اختيار التاريخ في Material Design
• أدوات اختيار الوقت