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

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

כמה נקודות שכדאי לזכור לגבי קטע הקוד הזה:

  • ‫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")
        }
    }
}

נקודות חשובות שכדאי לשים לב אליהן בהטמעה הזו:

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

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

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