כלי לבחירת שעה

כלי לבחירת שעה מאפשרים למשתמשים לבחור שעה. אפשר להשתמש ברכיבי ה-Composable‏ TimePicker ו-TimeInput כדי להטמיע כלי לבחירת שעה באפליקציה.

סוגים

יש שני סוגים של כלי לבחירת שעה:

  • חיוג: מאפשר למשתמשים להגדיר שעה על ידי הזזת ידית סביב חוגה.
  • קלט: מאפשר למשתמשים להגדיר שעה באמצעות המקלדת.

בתמונה הבאה מוצגת דוגמה לכלי לבחירת שעה עם חוגה בצד ימין, ולכלי לבחירת שעה עם שדה קלט בצד שמאל:

חוגה וכלי לבחירת שעה.
איור 1. חוגה ובוחר שעה להזנה.

פלטפורמת ה-API

כדי להטמיע את בוחר השעות, משתמשים בקוד TimePicker או TimeInput קומפוזבילי:

  • ‫TimePicker: הטמעה של כלי לבחירת שעה עם חוגה.
  • ‫TimeInput: הטמעה של בוחר שעות לקלט.

מדינה

גם בשביל TimePicker וגם בשביל TimeInput, צריך לעבור TimePickerState. כך תוכלו להגדיר את הזמן שנבחר כברירת מחדל שמופיע בכלי לבחירת תאריכים. הוא גם מתעד את השעה שהמשתמש בחר באמצעות הכלי לבחירת שעה.

Dialog

החלוניות לבחירת השעה מופיעות בתיבות דו-שיח. בדוגמאות במדריך הזה לא נעשה שימוש בתיבות דו-שיח. דוגמאות לשימוש בתיבות דו-שיח מופיעות במדריך בנושא תיבות דו-שיח לבחירת שעה.

חלונית לבחירת שעה עם חוגה

בקטע הקוד הבא אפשר לראות איך מטמיעים בורר זמן בסיסי.

@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 desugaring כדי להשתמש ב-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. לאחר מכן, רכיב ה-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")
        }
    }
}
TimePickers.kt

אחר כך אפשר לקרוא לרכיב ה-Composable כך:

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

פרטים נוספים זמינים בקטעי הקוד של האפליקציה.

מקורות מידע נוספים