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

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

סוגים

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

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

בתמונה הבאה מוצגת דוגמה לחלונית לבחירת זמן חיוג בצד ימין. חלונית לבחירת שעה משמאל:

בורר זמן עם ספירה לאחור וחלונית לבחירת שעת ההתחלה.
איור 1. חוגה ובורר של זמני הקלט.

פלטפורמת API

כדי להטמיע בורר זמן, צריך להשתמש בעמודות 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. לאחר מכן, ל-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

לאחר מכן תוכלו להפעיל את הרכיב הניתן לקיבוץ כך:

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

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

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