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

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

ملاحظة: 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
• تصميم المواد - أدوات اختيار الوقت