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

توفّر أداة اختيار الوقت للمستخدمين طريقة لاختيار وقت. يمكنك استخدام العنصرَين القابلَين للتجميع 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
• تصميم المواد - أدوات اختيار الوقت