Datumsauswahl

In der Datumsauswahl können Nutzer ein Datum, einen Zeitraum oder beides auswählen. Sie verwenden eine Kalenderdialogfeld oder Texteingabe, über die Nutzer Datumsangaben auswählen können.

Typen

Es gibt drei Arten von Datumsauswahlen:

  • Angedockt: Wird im Layout Inline angezeigt. Sie eignet sich für kompakte Layouts, in denen ein spezielles Dialogfeld aufdringlich wirken könnte.
  • Modal: Wird als Dialogfeld über den App-Inhalten angezeigt. Dies bietet eine den Fokus auf die Datumsauswahl aufheben.
  • Modaleingabe: Kombiniert ein Textfeld mit einer modalen Datumsauswahl.

Sie können diese Datumsauswahlen mit den folgenden Composeables in Ihrer App implementieren:

  • DatePicker: Allgemeines Composeable für eine Datumsauswahl. Je nach Container wird das Gerät angedockt oder als Modell angezeigt.
  • DatePickerDialog: Der Container für das modale und modale Eingabedatum Auswahlmöglichkeiten.
  • DateRangePicker: Für jede Datumsauswahl, in der Nutzer einen Zeitraum mit Start- und Enddatum auswählen können.

Bundesland

Der wichtigste Parameter, den die verschiedenen Datumsauswahl-Kompositionen gemeinsam haben, ist state. Er kann entweder ein DatePickerState- oder ein DateRangePickerState-Objekt annehmen. Ihre Properties erfassen Informationen über die Auswahl des Nutzers mithilfe der Datumsauswahl, z. B. das aktuell ausgewählte Datum.

Weitere Informationen zur Verwendung des ausgewählten Datums finden Sie im Abschnitt Verwenden Bereich mit ausgewähltem Datum.

Angedockte Datumsauswahl

Im folgenden Beispiel gibt es ein Textfeld, in dem der Nutzer zur Eingabe aufgefordert wird. ihr Geburtsdatum. Wenn sie auf das Kalendersymbol in dem Feld klicken, wird ein angedockte Datumsauswahl unter dem Eingabefeld.

@Composable
fun DatePickerDocked() {
    var showDatePicker by remember { mutableStateOf(false) }
    val datePickerState = rememberDatePickerState()
    val selectedDate = datePickerState.selectedDateMillis?.let {
        convertMillisToDate(it)
    } ?: ""

    Box(
        modifier = Modifier.fillMaxWidth()
    ) {
        OutlinedTextField(
            value = selectedDate,
            onValueChange = { },
            label = { Text("DOB") },
            readOnly = true,
            trailingIcon = {
                IconButton(onClick = { showDatePicker = !showDatePicker }) {
                    Icon(
                        imageVector = Icons.Default.DateRange,
                        contentDescription = "Select date"
                    )
                }
            },
            modifier = Modifier
                .fillMaxWidth()
                .height(64.dp)
        )

        if (showDatePicker) {
            Popup(
                onDismissRequest = { showDatePicker = false },
                alignment = Alignment.TopStart
            ) {
                Box(
                    modifier = Modifier
                        .fillMaxWidth()
                        .offset(y = 64.dp)
                        .shadow(elevation = 4.dp)
                        .background(MaterialTheme.colorScheme.surface)
                        .padding(16.dp)
                ) {
                    DatePicker(
                        state = datePickerState,
                        showModeToggle = false
                    )
                }
            }
        }
    }
}

@Composable
fun DatePickerFieldToModal(modifier: Modifier = Modifier) {
    var selectedDate by remember { mutableStateOf<Long?>(null) }
    var showModal by remember { mutableStateOf(false) }

    OutlinedTextField(
        value = selectedDate?.let { convertMillisToDate(it) } ?: "",
        onValueChange = { },
        label = { Text("DOB") },
        placeholder = { Text("MM/DD/YYYY") },
        trailingIcon = {
            Icon(Icons.Default.DateRange, contentDescription = "Select date")
        },
        modifier = modifier
            .fillMaxWidth()
            .pointerInput(selectedDate) {
                awaitEachGesture {
                    // Modifier.clickable doesn't work for text fields, so we use Modifier.pointerInput
                    // in the Initial pass to observe events before the text field consumes them
                    // in the Main pass.
                    awaitFirstDown(pass = PointerEventPass.Initial)
                    val upEvent = waitForUpOrCancellation(pass = PointerEventPass.Initial)
                    if (upEvent != null) {
                        showModal = true
                    }
                }
            }
    )

    if (showModal) {
        DatePickerModal(
            onDateSelected = { selectedDate = it },
            onDismiss = { showModal = false }
        )
    }
}

fun convertMillisToDate(millis: Long): String {
    val formatter = SimpleDateFormat("MM/dd/yyyy", Locale.getDefault())
    return formatter.format(Date(millis))
}
DatePickers.kt

Wichtige Informationen zum Code

  • Die Datumsauswahl wird angezeigt, wenn der Nutzer auf IconButton klickt.
    • Die Symbolschaltfläche dient als Argument für den OutlinedTextField trailingIcon-Parameter.
    • Die Statusvariable showDatePicker steuert die Sichtbarkeit des angedockte Datumsauswahl.
  • Der Container der Datumsauswahl ist eine zusammensetzbare Funktion vom Typ Popup, die über dem ohne das Layout anderer Elemente zu beeinträchtigen.
  • selectedDate erfasst den Wert des ausgewählten Datums aus dem DatePickerState-Objekt und formatiert ihn mit der convertMillisToDate-Funktion.
  • Das ausgewählte Datum wird im Textfeld angezeigt.
  • Die angedockte Datumsauswahl wird mit einem offset-Modifikator unter dem Textfeld platziert.
  • Ein Box wird als Stammcontainer verwendet, um eine korrekte Schichtung des Textfelds und der Datumsauswahl zu ermöglichen.

Ergebnisse

Nach dem Klicken auf das Kalendersymbol sieht diese Implementierung so aus:

Beispiel für eine angedockte Datumsauswahl.
Abbildung 1: Eine angedockte Datumsauswahl.

In der modalen Datumsauswahl ist ein Dialogfeld zu sehen, das über dem Bildschirm schwebt. Erstellen Sie dazu eine DatePickerDialog und übergeben Sie ihr eine DatePicker.

@Composable
fun DatePickerModal(
    onDateSelected: (Long?) -> Unit,
    onDismiss: () -> Unit
) {
    val datePickerState = rememberDatePickerState()

    DatePickerDialog(
        onDismissRequest = onDismiss,
        confirmButton = {
            TextButton(onClick = {
                onDateSelected(datePickerState.selectedDateMillis)
                onDismiss()
            }) {
                Text("OK")
            }
        },
        dismissButton = {
            TextButton(onClick = onDismiss) {
                Text("Cancel")
            }
        }
    ) {
        DatePicker(state = datePickerState)
    }
}
DatePickers.kt

  • Die zusammensetzbare Funktion DatePickerModal zeigt eine modale Datumsauswahl an.
  • Der Lambda-Ausdruck onDateSelected wird ausgeführt, wenn der Nutzer einen Datum.
    • Das ausgewählte Datum wird dem übergeordneten Composeable-Element zur Verfügung gestellt.
  • Der Lambda-Ausdruck onDismiss wird ausgeführt, wenn der Nutzer die Dialogfeld.

Ergebnisse

Diese Implementierung sieht so aus:

Beispiel für eine modale Datumsauswahl
Abbildung 2: Eine modale Datumsauswahl.

Modale Datumsauswahl für die Eingabe

Eine modale Datumsauswahl mit Eingabefeld blendet ein Dialogfeld über dem Bildschirm ein, in dem der Nutzer ein Datum eingeben kann.

@Composable
fun DatePickerModalInput(
    onDateSelected: (Long?) -> Unit,
    onDismiss: () -> Unit
) {
    val datePickerState = rememberDatePickerState(initialDisplayMode = DisplayMode.Input)

    DatePickerDialog(
        onDismissRequest = onDismiss,
        confirmButton = {
            TextButton(onClick = {
                onDateSelected(datePickerState.selectedDateMillis)
                onDismiss()
            }) {
                Text("OK")
            }
        },
        dismissButton = {
            TextButton(onClick = onDismiss) {
                Text("Cancel")
            }
        }
    ) {
        DatePicker(state = datePickerState)
    }
}
DatePickers.kt

Das ist im Grunde dasselbe wie beim Beispiel für eine modale Datumsauswahl. Die primäre den Unterschied:

  • Mit dem Parameter initialDisplayMode wird der anfängliche Anzeigemodus auf DisplayMode.Input festgelegt.
Modale Datumsauswahl mit Eingabe
Abbildung 3 Eine modale Datumsauswahl mit Eingabe.

Datumsauswahl mit Zeitraum

Sie können eine Datumsauswahl erstellen, mit der Nutzer einen Zeitraum zwischen einem Start- und einem Enddatum auswählen können. Verwenden Sie dazu DateRangePicker.

Die Verwendung von DateRangePicker entspricht im Wesentlichen der Verwendung von DatePicker. Sie können es als untergeordnetes Element von PopUp für eine angedockte Auswahl oder als modale Auswahl verwenden und an DatePickerDialog übergeben. Der Hauptunterschied ist dass Sie DateRangePickerState anstelle von DatePickerState verwenden.

Mit dem folgenden Snippet wird eine modale Datumsauswahl Bereich:

@Composable
fun DateRangePickerModal(
    onDateRangeSelected: (Pair<Long?, Long?>) -> Unit,
    onDismiss: () -> Unit
) {
    val dateRangePickerState = rememberDateRangePickerState()

    DatePickerDialog(
        onDismissRequest = onDismiss,
        confirmButton = {
            TextButton(
                onClick = {
                    onDateRangeSelected(
                        Pair(
                            dateRangePickerState.selectedStartDateMillis,
                            dateRangePickerState.selectedEndDateMillis
                        )
                    )
                    onDismiss()
                }
            ) {
                Text("OK")
            }
        },
        dismissButton = {
            TextButton(onClick = onDismiss) {
                Text("Cancel")
            }
        }
    ) {
        DateRangePicker(
            state = dateRangePickerState,
            title = {
                Text(
                    text = "Select date range"
                )
            },
            showModeToggle = false,
            modifier = Modifier
                .fillMaxWidth()
                .height(500.dp)
                .padding(16.dp)
        )
    }
}
DatePickers.kt

Wichtige Punkte zum Code

  • Der Parameter onDateRangeSelected ist ein Callback, der ein Pair<Long?, Long?> für das ausgewählte Start- und Enddatum. Dadurch erhält das übergeordnete Element Zugriff auf den ausgewählten Bereich.
  • rememberDateRangePickerState() erstellt den Status für den Zeitraum Auswahl.
  • Mit DatePickerDialog wird ein modaler Dialogfeldcontainer erstellt.
  • Im onClick-Handler der Bestätigungsschaltfläche gibt onDateRangeSelected den ausgewählten Bereich an das übergeordnete Composeable weiter.
  • Das DateRangePicker-Komposit dient als Dialoginhalt.

Ergebnisse

Diese Implementierung sieht so aus:

Beispiel für eine modale Datumsauswahl für einen Zeitraum
Abbildung 4: Eine modale Datumsauswahl mit einem ausgewählten Zeitraum.

Ausgewähltes Datum verwenden

Wenn Sie das ausgewählte Datum erfassen möchten, erfassen Sie es im übergeordneten Composeable als Long und übergeben Sie den Wert an die DatePicker in onDateSelected. Das folgende Snippet demonstriert dies. Die vollständige Implementierung finden Sie jedoch in der offiziellen Snippets-App verfügbar.

// ...
    var selectedDate by remember { mutableStateOf<Long?>(null) }
// ...
        if (selectedDate != null) {
            val date = Date(selectedDate!!)
            val formattedDate = SimpleDateFormat("MMM dd, yyyy", Locale.getDefault()).format(date)
            Text("Selected date: $formattedDate")
        } else {
            Text("No date selected")
        }
// ...
        DatePickerModal(
            onDateSelected = {
                selectedDate = it
                showModal = false
            },
            onDismiss = { showModal = false }
        )
    }
// ...
DatePickers.kt

Im Wesentlichen gilt das Gleiche für die Datumsauswahl für den Zeitraum. Sie müssen sich jedoch Verwenden Sie Pair<Long?, Long?> oder eine Datenklasse, um die Start- und Endwerte zu erfassen.

Siehe auch