日期选择器

日期选择器可让用户选择日期和/或日期范围。它们使用日历对话框或文本输入框让用户选择日期。

类型

日期选择器有三种类型：

  • 已固定：在布局中内嵌显示。它适用于紧凑的布局，在这种布局中，专用对话框可能会让人感到侵扰。
  • 模态：显示为叠加在应用内容上的对话框。这样可以让用户明确地选择日期。
  • 模态输入：将文本字段与模态日期选择器组合使用。

您可以使用以下可组合项在应用中实现这些日期选择器：

  • DatePicker：日期选择器的通用可组合项。您使用的容器决定了它是固定的还是模拟的。
  • DatePickerDialog：模态日期选择器和模态输入日期选择器的容器。
  • DateRangePicker：适用于用户可以选择包含开始日期和结束日期的范围的任何日期选择器。

状态

不同日期选择器可组合项共享的键参数是 state，它接受 DatePickerState 或 DateRangePickerState 对象。其属性会捕获用户使用日期选择器进行选择的相关信息，例如当前所选日期。

如需详细了解如何使用所选日期，请参阅“使用所选日期”部分。

固定的日期选择器

在以下示例中，有一个文本字段提示用户输入出生日期。当用户点击该字段中的日历图标时，系统会在输入字段下方打开一个固定的日期选择器。

@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

代码要点

  • 当用户点击 IconButton 时，系统会显示日期选择器。
    • 图标按钮用作 OutlinedTextField 的 trailingIcon 参数的参数。
    • showDatePicker 状态变量用于控制固定的日期选择器的可见性。
  • 日期选择器的容器是一个 Popup 可组合项，它会叠加内容，而不会影响其他元素的布局。
  • selectedDate 会从 DatePickerState 对象中捕获所选日期的值，并使用 convertMillisToDate 函数对其进行格式设置。
  • 所选日期会显示在文本字段中。
  • 通过使用 offset 修饰符，将固定的日期选择器放置在文本字段下方。
  • Box 用作根容器，以便文本字段和日期选择器正确分层。

结果

点击日历图标后，此实现会显示如下所示：

固定的日期选择器示例。
图 1. 固定的日期选择器。

模态日期选择器会显示一个浮动在屏幕上的对话框。如需实现它，请创建一个 DatePickerDialog 并将 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

  • DatePickerModal 可组合函数会显示模态日期选择器。
  • 当用户选择日期时，系统会执行 onDateSelected lambda 表达式。
    • 它会将所选日期公开给父级可组合项。
  • 当用户关闭对话框时，系统会执行 onDismiss lambda 表达式。

结果

此实现如下所示：

模态日期选择器示例。
图 2. 模态日期选择器。

输入模态日期选择器

带输入的模态日期选择器会显示一个浮动在屏幕上的对话框，并允许用户输入日期。

@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

这与模态日期选择器示例非常相似。主要区别如下：

  • initialDisplayMode 参数将初始显示模式设置为 DisplayMode.Input。
带输入的模态日期选择器。
图 3. 带输入的模态日期选择器。

带范围的日期选择器

您可以创建一个日期选择器，让用户选择开始日期和结束日期之间的范围。为此，请使用 DateRangePicker。

DateRangePicker 的使用方式与 DatePicker 基本相同。您可以将其用作 PopUp 的子项，作为固定的选择器使用；也可以将其用作模态选择器，并将其传递给 DatePickerDialog。主要区别在于，您使用 DateRangePickerState 而非 DatePickerState。

以下代码段演示了如何创建具有范围的模态日期选择器：

@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

代码要点

  • onDateRangeSelected 参数是一个回调，用于接收表示所选开始日期和结束日期的 Pair<Long?, Long?>。这会授予父级可组合项对所选范围的访问权限。
  • rememberDateRangePickerState() 会为日期范围选择器创建状态。
  • DatePickerDialog 会创建模态对话框容器。
  • 在确认按钮的 onClick 处理脚本中，onDateRangeSelected 会将所选范围向上传递给父级可组合项。
  • DateRangePicker 可组合项用作对话框内容。

结果

此实现如下所示：

模态范围日期选择器示例。
图 4. 包含所选范围的模态日期选择器。

使用所选日期

如需捕获所选日期，请在父级可组合项中将其作为 Long 进行跟踪，并将值传递给 onDateSelected 中的 DatePicker。以下代码段演示了这一点，不过您也可以在官方代码段应用中查看完整实现。

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

范围日期选择器基本上也是如此，不过您需要使用 Pair<Long?, Long?> 或数据类来捕获开始值和结束值。

另请参阅