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

توفّر أدوات اختيار الوقت طريقة للمستخدمين لاختيار وقت. يمكنك استخدام الدالتَين المركّبتَين TimePicker وTimeInput لتنفيذ أداة اختيار الوقت في تطبيقك.

الأنواع

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

• قرص: يتيح للمستخدمين ضبط الوقت من خلال تحريك مقبض حول قرص.
• الإدخال: تتيح للمستخدمين ضبط الوقت باستخدام لوحة المفاتيح.

تعرض الصورة التالية مثالاً على أداة اختيار الوقت من خلال القرص على اليمين، وأداة اختيار الوقت من خلال الإدخال على اليسار:

الشكل 1. قرص وأداة اختيار وقت الإدخال

مساحة عرض واجهة برمجة التطبيقات

لتنفيذ أداة اختيار الوقت، استخدِم الدالة المركّبة TimePicker أو TimeInput:

• ‫TimePicker: لتنفيذ أداة اختيار الوقت من خلال الاتصال الهاتفي
• ‫TimeInput: لتنفيذ أداة اختيار وقت الإدخال

ملاحظة: على الرغم من أنّ الدالتَين TimePicker وTimeInput تعرضان مكوّنات مختلفة، إلا أنّهما متشابهتان جدًا من حيث المَعلمات. وبالتالي، يمكن استخدام أي منهما كبديل عن الآخر.

الولاية

بالنسبة إلى كل من TimePicker وTimeInput، يجب أيضًا تمرير TimePickerState. يتيح لك هذا الإعداد ضبط الوقت التلقائي المحدّد الذي يظهر على أداة الاختيار. وتسجّل أيضًا الوقت الذي اختاره المستخدم باستخدام أداة الاختيار.

مربع حوار

تظهر أدوات اختيار الوقت في مربّعات الحوار. لا تستخدم الأمثلة في هذا الدليل مربّعات الحوار. للاطّلاع على أمثلة تستخدم مربّعات الحوار، راجِع دليل مربّعات الحوار لأدوات اختيار الوقت.

أداة اختيار الوقت من خلال القرص

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

@Composable
fun DialExample(
    onConfirm: () -> Unit,
    onDismiss: () -> Unit,
) {
    val currentTime = Calendar.getInstance()

    val timePickerState = rememberTimePickerState(
        initialHour = currentTime.get(Calendar.HOUR_OF_DAY),
        initialMinute = currentTime.get(Calendar.MINUTE),
        is24Hour = true,
    )

    Column {
        TimePicker(
            state = timePickerState,
        )
        Button(onClick = onDismiss) {
            Text("Dismiss picker")
        }
        Button(onClick = onConfirm) {
            Text("Confirm selection")
        }
    }
}
TimePickers.kt

ضع في اعتبارك ما يلي في هذا المقتطف:

• تُهيئ الدالة Calendar.getInstance() السمة TimePickerState بالوقت الحالي.
  • يستخدم هذا المثال java.util.Calendar. فعِّل إزالة التجميل اللغوي لواجهة برمجة التطبيقات Java 8+‎ في مشروعك لاستخدام java.time.LocalTime بدلاً من ذلك على جميع إصدارات Android.
• تعرض الدالة المركّبة TimePicker أداة اختيار الوقت، وتستخدم timePickerState كمَعلمة.
• يتضمّن التنفيذ زرَّين: أحدهما لتأكيد الاختيار والآخر لإغلاق أداة الاختيار.

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

الشكل 2. أداة اختيار الوقت على شكل قرص

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

يوضّح هذا المقتطف كيفية تنفيذ أداة اختيار وقت أساسية بنمط الإدخال.

@Composable
fun InputExample(
    onConfirm: () -> Unit,
    onDismiss: () -> Unit,
) {
    val currentTime = Calendar.getInstance()

    val timePickerState = rememberTimePickerState(
        initialHour = currentTime.get(Calendar.HOUR_OF_DAY),
        initialMinute = currentTime.get(Calendar.MINUTE),
        is24Hour = true,
    )

    Column {
        TimeInput(
            state = timePickerState,
        )
        Button(onClick = onDismiss) {
            Text("Dismiss picker")
        }
        Button(onClick = onConfirm) {
            Text("Confirm selection")
        }
    }
}
TimePickers.kt

النقاط الرئيسية التي يجب مراعاتها في عملية التنفيذ هذه:

• البنية هي نفسها في الأساس أداة اختيار وقت الاتصال، مع الاختلاف الرئيسي هو استخدام TimeInput بدلاً من TimePicker.
• تم ضبط مَعلمة is24Hour لـ "timePickerState" بشكل صريح على true. تكون هذه القيمة تلقائيًا false.

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

الشكل 3. أداة اختيار الوقت

استخدام الحالة

للاستفادة من الوقت الذي اختاره المستخدم في أداة اختيار الوقت، عليك تمرير السمة TimePickerState المناسبة إلى الدالة onConfirm. يمكن بعد ذلك للدالة المركّبة الرئيسية الوصول إلى الوقت المحدّد من خلال TimePickerState.hour وTimePickerState.minute.

يوضّح المقتطف التالي كيفية إجراء ذلك:

@Composable
fun DialUseStateExample(
    onConfirm: (TimePickerState) -> Unit,
    onDismiss: () -> Unit,
) {
    val currentTime = Calendar.getInstance()

    val timePickerState = rememberTimePickerState(
        initialHour = currentTime.get(Calendar.HOUR_OF_DAY),
        initialMinute = currentTime.get(Calendar.MINUTE),
        is24Hour = true,
    )

    Column {
        TimePicker(
            state = timePickerState,
        )
        Button(onClick = onDismiss) {
            Text("Dismiss picker")
        }
        Button(onClick = { onConfirm(timePickerState) }) {
            Text("Confirm selection")
        }
    }
}
TimePickers.kt

يمكنك بعد ذلك استدعاء الدالة المركّبة على النحو التالي:

var selectedTime: TimePickerState? by remember { mutableStateOf(null) }

// ...

DialUseStateExample(
    onDismiss = {
        showDialExample = false
    },
    onConfirm = {
            time ->
        selectedTime = time
        showDialExample = false
    },
)

// ...

if (selectedTime != null) {
    val cal = Calendar.getInstance()
    cal.set(Calendar.HOUR_OF_DAY, selectedTime!!.hour)
    cal.set(Calendar.MINUTE, selectedTime!!.minute)
    cal.isLenient = false
    Text("Selected time = ${formatter.format(cal.time)}")
} else {
    Text("No time selected.")
}

لمزيد من التفاصيل، يمكنك الاطّلاع على التنفيذ الكامل في تطبيق المقتطفات.

مراجع إضافية

• TimePicker
• التصميم المتعدد الأبعاد - أدوات اختيار الوقت