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

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

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

مراجع إضافية