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

توفّر أداة اختيار الوقت للمستخدمين طريقة لاختيار وقت. يمكنك استخدام العنصرَين القابلَين للتجميع 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+ API المُحلَّى في مشروعك لاستخدام 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.")
}

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

مصادر إضافية

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