日期选择器 (Date Pickers)

源：Date pickers

日期选择器允许用户选择单个日期或日期范围。M3 提供了三种变体。

1. Docked date picker (停靠式): 点击文本框后弹出的下拉式选择器。
2. Modal date picker (模态对话框): 标准的弹出式对话框。
3. Modal date input (文本输入式): 允许用户通过键盘直接输入。

---

核心功能

1. 选择单个日期

val datePicker = MaterialDatePicker.Builder.datePicker()
    .setTitleText("选择日期")
    .setSelection(MaterialDatePicker.todayInUtcMilliseconds())
    .build()

datePicker.show(supportFragmentManager, "DATE_PICKER")

2. 选择日期范围

val dateRangePicker = MaterialDatePicker.Builder.dateRangePicker()
    .setTitleText("选择日期范围")
    .build()

dateRangePicker.show(supportFragmentManager, "DATE_RANGE_PICKER")

---

日历约束 (Calendar Constraints)

你可以限制用户只能选择特定范围内的日期（如：仅未来日期）。

val constraintsBuilder = CalendarConstraints.Builder()
    .setValidator(DateValidatorPointForward.now()) // 仅允许选择今天及以后的日期

val datePicker = MaterialDatePicker.Builder.datePicker()
    .setCalendarConstraints(constraintsBuilder.build())
    .build()

---

监听事件

datePicker.addOnPositiveButtonClickListener { selection ->
    // selection 是选中的时间戳 (Long)
    val dateString = SimpleDateFormat("yyyy-MM-dd").format(Date(selection))
}

datePicker.addOnNegativeButtonClickListener {
    // 处理取消
}

---

辅助功能

日期选择器会自动朗读标题和选中的日期，符合 TalkBack 标准。建议始终通过 setTitleText() 设置一个清晰的操作描述。