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

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

סוגים

יש שני סוגים של בורר זמן:

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

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

ממשק API

כדי להטמיע בורר זמן, משתמשים ב-composable‏ 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. מפעילים בפרויקט את הסרת הסוכר מ-API של Java 8 ואילך כדי להשתמש ב-java.time.LocalTime בכל גרסאות Android.
• הרכיב הקומפוזיבי TimePicker מציג את בורר השעות, עם timePickerState כפרמטר.
• ההטמעה כוללת שני לחצנים: אחד לאישור הבחירה והשני לסגירת הבורר.

ההטמעה הזו נראית כך:

קלט של בורר השעה

קטע הקוד הזה מדגים איך מטמיעים בורר זמן בסגנון קלט בסיסי.

@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.

ההטמעה הזו נראית כך:

שימוש במצב

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

פרטים נוספים זמינים במאמר הטמעה מלאה באפליקציית ה-snippets.

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

• TimePicker
• Material Design – בוררי זמן