تتيح أداة اختيار التاريخ للمستخدمين اختيار تاريخ أو نطاق زمني أو كليهما. تستخدم مربّع حوار التقويم أو إدخال النص للسماح للمستخدمين باختيار التواريخ
الأنواع
هناك ثلاثة أنواع من منتقي التاريخ:
- جزء من الشاشة: يظهر مضمّنًا في التنسيق. وهي مناسبة للإطارات الصغيرة التنسيقات التي قد يبدو فيها مربع الحوار المخصص تطفليًا.
- نمط: يظهر كمربّع حوار متراكبًا على محتوى التطبيق. يوفر هذا مسح التركيز على اختيار التاريخ.
- الإدخال المشروط: يدمج هذا الحقل حقلاً نصيًا مع أداة اختيار التاريخ المشروطة.
يمكنك تطبيق منتقي التاريخ هذا في تطبيقك باستخدام ما يلي عناصر قابلة للإنشاء:
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)) }
النقاط الرئيسية حول الرمز البرمجي
- تظهر أداة اختيار التاريخ عندما ينقر المستخدم على
IconButton
.- يعمل زر الرمز كوسيطة لحساب
OutlinedTextField
مَعلمةtrailingIcon
. - يتحكّم متغير الحالة
showDatePicker
في إمكانية رؤية أداة اختيار تاريخ قاعدة الإرساء
- يعمل زر الرمز كوسيطة لحساب
- حاوية أداة اختيار التاريخ هي حاوية
Popup
قابلة للإنشاء، وتظهر على سطح الصفحة المحتوى دون التأثير في تخطيط العناصر الأخرى. - يحصل
selectedDate
على قيمة التاريخ المحدّد من عنصرDatePickerState
وينسقه باستخدامconvertMillisToDate
الأخرى. - يظهر التاريخ المحدد في حقل النص.
- يتم وضع أداة اختيار التاريخ في وضع الإرساء أسفل حقل النص باستخدام
offset
. مفتاح التعديل. - يتم استخدام
Box
كحاوية جذر للسماح بطبقات النص بشكل مناسب. ومنتقي التاريخ.
النتائج
بعد النقر على رمز التقويم، تظهر طريقة التنفيذ هذه على النحو التالي:
![مثال على أداة اختيار تاريخ تم إرساؤه](https://developer.android.com/static/develop/ui/compose/images/components/datepicker-docked.png?hl=ar)
أداة اختيار التاريخ المشروط
تعرض أداة اختيار التاريخ المشروطة مربّع حوار يطفو فوق الشاشة. للتنفيذ
أنشئ 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) } }
النقاط الرئيسية حول الرمز البرمجي
- تعرض دالة
DatePickerModal
القابلة للإنشاء أداة اختيار تاريخ مشروطة. - يتم تنفيذ تعبير lambda
onDateSelected
عندما يختار المستخدم التاريخ.- يعرض التاريخ المحدّد للعنصر الرئيسي القابل للإنشاء.
- يتم تنفيذ تعبير lambda
onDismiss
عندما يرفض المستخدم .
النتائج
تظهر طريقة التنفيذ هذه على النحو التالي:
![مثال على أداة اختيار التاريخ المشروط](https://developer.android.com/static/develop/ui/compose/images/components/datepicker-modal.png?hl=ar)
أداة اختيار التاريخ المشروط الذي تم إدخاله
يعرض منتقي التاريخ المشروط الذي يتضمن إدخالاً مربع حوار يطفو فوق الشاشة يسمح للمستخدم بإدخال تاريخ.
@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) } }
النقاط الرئيسية حول الرمز البرمجي
يشبه هذا إلى حد كبير مثال أداة اختيار التاريخ المشروط. الأساسية هو ما يلي:
- تضبط المَعلمة
initialDisplayMode
وضع العرض الأولي علىDisplayMode.Input
![أداة اختيار التاريخ المشروط مع البيانات التي تم إدخالها](https://developer.android.com/static/develop/ui/compose/images/components/datepicker-modal-input.png?hl=ar)
أداة اختيار التاريخ بالنطاق
يمكنك إنشاء أداة اختيار تاريخ تتيح للمستخدم اختيار نطاق بين تاريخ بدء.
وتاريخ الانتهاء. لإجراء ذلك، استخدِم 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) ) } }
النقاط الرئيسية حول الرمز البرمجي
- المعلمة
onDateRangeSelected
هي استدعاء تتلقىPair<Long?, Long?>
الذي يمثّل تاريخَي البدء والانتهاء المحدّدَين. هذا النمط لمنح الأصل القابل للإنشاء إمكانية الوصول إلى النطاق المحدد. - تنشئ
rememberDateRangePickerState()
الحالة للنطاق الزمني. المنتقي. - تنشئ
DatePickerDialog
حاوية مربّع حوار مشروطة. - في معالج
onClick
لزر التأكيد، يتم تمريرonDateRangeSelected
. النطاق المحدد إلى العنصر الرئيسي القابل للإنشاء. - يعمل عنصر
DateRangePicker
القابل للإنشاء كمحتوى مربّع الحوار.
النتائج
تظهر طريقة التنفيذ هذه على النحو التالي:
![مثال على أداة اختيار تاريخ النطاق المشروط](https://developer.android.com/static/develop/ui/compose/images/components/datepicker-range.png?hl=ar)
استخدام التاريخ المحدّد
لالتقاط التاريخ المحدّد، يجب تتبّعه في العنصر الرئيسي القابل للإنشاء على أنّه 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 } ) } // ...
ينطبق الأمر نفسه بشكل أساسي على أدوات اختيار تاريخ النطاق، ولكن عليك
استخدام Pair<Long?, Long?>
أو فئة بيانات للحصول على قيم البداية والنهاية.