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

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

الأنواع

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

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

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

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

واجهة برمجة التطبيقات

لتنفيذ أداة اختيار الوقت، استخدِم 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")
        }
    }
}

راجِع ما يلي في المقتطف التالي:

  • Calendar.getInstance() يهيئ TimePickerState بالوقت الحالي.
  • يعرض العنصر القابل للإنشاء 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")
        }
    }
}

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

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

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

أداة اختيار وقت الإدخال يمكن للمستخدم إدخال وقت باستخدام حقول النص.
الشكل 3. أداة اختيار وقت الإدخال

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

للاستفادة من الوقت الذي اختاره المستخدم في أداة اختيار الوقت، مرِّرTimePickerState المناسب إلى دالة onConfirm. يمكن للوالد composable بعد ذلك الوصول إلى الوقت المحدّد من خلال 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")
        }
    }
}

يمكنك بعد ذلك تسمية العنصر القابل للإنشاء على النحو التالي:

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.")
}

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

مصادر إضافية