DatePicker
DatePicker 是独立的日期选择界面。TextField 在 type="date" 和 type="datetime-local" 时会自动使用它。
原生弹出层关闭时会触发 update:open(false)。DatePicker 自身的退出动画结束后会触发 closed。退出期间会保留当前日历视图，动画结束后再重置。
密度
DatePicker 和 DateRangePicker 继承 --md-density。日期单元格保持等宽等高，日历宽度、星期行、月份／年份列表和操作间距会随密度调整。视口较窄时，单元格会限制在可用列宽内。显式设置的组件尺寸 token 优先。
星期起始日
firstDayOfWeek 使用 0 表示星期日，6 表示星期六。显式属性优先于 datePickerContextKey 中的 firstDayOfWeek；否则根据配置的区域设置或浏览器区域设置确定星期起始日。
可通过 M3VuePlugin 设置 datePickerDefaults.firstDayOfWeek，或通过上下文配置子树。TextField 内嵌的日期选择器会继承相同偏好。详见组件默认值。
示例
默认
模态模式
限制条件
参考
结构
| 元素 | 部件 | 选择器 |
|---|---|---|
<div> | root | [data-scope="date-picker"][data-part="root"]鼠标左键单击复制 |
<div> | surface | [data-scope="date-picker"][data-part="surface"]鼠标左键单击复制 |
<div> | header | [data-scope="date-picker"][data-part="header"]鼠标左键单击复制 |
<IconButton> | previous-month | [data-scope="date-picker"][data-part="previous-month"]鼠标左键单击复制 |
<Button> | month-switch | [data-scope="date-picker"][data-part="month-switch"]鼠标左键单击复制 |
<IconButton> | next-month | [data-scope="date-picker"][data-part="next-month"]鼠标左键单击复制 |
<IconButton> | previous-year | [data-scope="date-picker"][data-part="previous-year"]鼠标左键单击复制 |
<Button> | year-switch | [data-scope="date-picker"][data-part="year-switch"]鼠标左键单击复制 |
<IconButton> | next-year | [data-scope="date-picker"][data-part="next-year"]鼠标左键单击复制 |
<div> | calendar条件显示 | [data-scope="date-picker"][data-part="calendar"]鼠标左键单击复制 |
<div> | weekdays | [data-scope="date-picker"][data-part="weekdays"]鼠标左键单击复制 |
<span> | weekday | [data-scope="date-picker"][data-part="weekday"]鼠标左键单击复制 |
<div> | grid | [data-scope="date-picker"][data-part="grid"]鼠标左键单击复制 |
<button> | day | [data-scope="date-picker"][data-part="day"]鼠标左键单击复制 |
<div> | months | [data-scope="date-picker"][data-part="months"]鼠标左键单击复制 |
<button> | month | [data-scope="date-picker"][data-part="month"]鼠标左键单击复制 |
<span> | list-icon | [data-scope="date-picker"][data-part="list-icon"]鼠标左键单击复制 |
<span> | list-label | [data-scope="date-picker"][data-part="list-label"]鼠标左键单击复制 |
<div> | years | [data-scope="date-picker"][data-part="years"]鼠标左键单击复制 |
<button> | year | [data-scope="date-picker"][data-part="year"]鼠标左键单击复制 |
<div> | actions | [data-scope="date-picker"][data-part="actions"]鼠标左键单击复制 |
属性
| 名称 | 说明 | 默认值 | 控件 |
|---|---|---|---|
shape可选 | Corner style; inherits the shared shape default. M3Shape | undefined | - | - |
id可选 | Optional explicit id for the popover element. string | undefined | undefined | - |
variant可选 | Visual and positioning mode. Auto uses docked layout until a narrow/coarse pointer viewport. DatePickerVariant | undefined | "auto" | - |
anchorName可选 | CSS anchor name used to position the docked popover. string | undefined | undefined | - |
anchorElement可选 | Element passed to showPopover as the source for focus and dismissal semantics. HTMLElement | undefined | undefined | - |
ariaLabel可选 | Accessible label for the picker surface. string | undefined | undefined | |
min可选 | Earliest selectable date, formatted as YYYY-MM-DD. string | undefined | undefined | |
max可选 | Latest selectable date, formatted as YYYY-MM-DD. string | undefined | undefined | |
locale可选 | BCP 47 locale used for month, weekday, and date accessibility labels. string | undefined | undefined | - |
firstDayOfWeek可选 | First day of the week, where 0 is Sunday and 6 is Saturday. 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined | undefined | - |
confirmText可选 | Text for the confirmation button. string | undefined | undefined | |
cancelText可选 | Text for the cancel button. string | undefined | undefined | |
today可选 | Date treated as today, formatted as YYYY-MM-DD. Useful for deterministic tests. string | undefined | undefined | - |
modelValue可选 | - DatePickerModelValue | - | - |
open可选 | - boolean | undefined | false |
事件6
| 名称 | 类型 | 说明 |
|---|---|---|
update:open | [value: boolean] | - |
cancel | [] | - |
closed | [] | - |
update:modelValue | [value: DatePickerModelValue] | - |
change | [value: DatePickerModelValue] | - |
confirm | [value: DatePickerModelValue] | - |
样式45
| Token | 说明 |
|---|---|
--md-date-picker-docked-container-colorColor回退值 var(--md-sys-color-surface-container-high) | Controls docked container color. |
--md-date-picker-docked-container-elevationElevation回退值 var(--md-sys-elevation-level3) | Controls docked container elevation. |
--md-date-picker-docked-container-shapeShape回退值 var(--md-shape-overlay) | Controls docked container shape. |
--md-date-picker-docked-container-widthLayout回退值 22.5rem | Controls docked container width. |
--md-date-picker-docked-date-container-heightLayout回退值 3rem | Controls docked date container height. |
--md-date-picker-docked-date-container-shapeShape回退值 var(--md-shape-indicator) | Controls docked date container shape. |
--md-date-picker-docked-date-container-widthLayout回退值 3rem | Controls docked date container width. |
--md-date-picker-docked-date-label-text-fontTypography回退值 var(--md-sys-typescale-body-large-font) | Controls docked date label text font. |
--md-date-picker-docked-date-label-text-line-heightTypography回退值 var(--md-sys-typescale-body-large-line-height) | Controls docked date label text line height. |
--md-date-picker-docked-date-label-text-sizeLayout回退值 var(--md-sys-typescale-body-large-size) | Controls docked date label text size. |
--md-date-picker-docked-date-label-text-trackingTypography回退值 var(--md-sys-typescale-body-large-tracking) | Controls docked date label text tracking. |
--md-date-picker-docked-date-label-text-weightTypography回退值 var(--md-sys-typescale-body-large-weight) | Controls docked date label text weight. |
--md-date-picker-docked-date-selected-container-colorState回退值 var(--md-sys-color-primary) | Controls docked date selected container color. |
--md-date-picker-docked-date-selected-hover-state-layer-colorState回退值 var(--md-sys-color-on-primary) | Controls docked date selected hover state layer color. |
--md-date-picker-docked-date-selected-label-text-colorState回退值 var(--md-sys-color-on-primary) | Controls docked date selected label text color. |
--md-date-picker-docked-date-today-container-outline-colorColor回退值 var(--md-sys-color-primary) | Controls docked date today container outline color. |
--md-date-picker-docked-date-today-container-outline-widthLayout回退值 0.0625rem | Controls docked date today container outline width. |
--md-date-picker-docked-date-today-hover-state-layer-colorState回退值 var(--md-sys-color-primary) | Controls docked date today hover state layer color. |
--md-date-picker-docked-date-today-label-text-colorColor回退值 var(--md-sys-color-primary) | Controls docked date today label text color. |
--md-date-picker-docked-date-unselected-hover-state-layer-colorState回退值 var(--md-sys-color-on-surface-variant) | Controls docked date unselected hover state layer color. |
--md-date-picker-docked-date-unselected-label-text-colorState回退值 var(--md-sys-color-on-surface) | Controls docked date unselected label text color. |
--md-date-picker-docked-date-unselected-outside-month-label-text-colorState回退值 var(--md-sys-color-on-surface) | Controls docked date unselected outside month label text color. |
--md-date-picker-docked-date-unselected-outside-month-label-text-opacityState回退值 0.38 | Controls docked date unselected outside month label text opacity. |
--md-date-picker-docked-menu-button-container-shapeShape回退值 var(--md-shape-action) | Controls docked menu button container shape. |
--md-date-picker-docked-menu-button-label-text-colorColor回退值 var(--md-sys-color-on-surface-variant) | Controls docked menu button label text color. |
--md-date-picker-docked-menu-button-label-text-fontTypography回退值 var(--md-sys-typescale-label-large-font) | Controls docked menu button label text font. |
--md-date-picker-docked-menu-button-label-text-line-heightTypography回退值 var(--md-sys-typescale-label-large-line-height) | Controls docked menu button label text line height. |
--md-date-picker-docked-menu-button-label-text-sizeLayout回退值 var(--md-sys-typescale-label-large-size) | Controls docked menu button label text size. |
--md-date-picker-docked-menu-button-label-text-trackingTypography回退值 var(--md-sys-typescale-label-large-tracking) | Controls docked menu button label text tracking. |
--md-date-picker-docked-menu-button-label-text-weightTypography回退值 var(--md-sys-typescale-label-large-weight) | Controls docked menu button label text weight. |
--md-date-picker-docked-menu-list-item-hover-state-layer-colorState回退值 var(--md-sys-color-on-surface) | Controls docked menu list item hover state layer color. |
--md-date-picker-docked-menu-list-item-label-text-colorColor回退值 var(--md-sys-color-on-surface) | Controls docked menu list item label text color. |
--md-date-picker-docked-menu-list-item-label-text-fontTypography回退值 var(--md-sys-typescale-body-large-font) | Controls docked menu list item label text font. |
--md-date-picker-docked-menu-list-item-label-text-line-heightTypography回退值 var(--md-sys-typescale-body-large-line-height) | Controls docked menu list item label text line height. |
--md-date-picker-docked-menu-list-item-label-text-sizeLayout回退值 var(--md-sys-typescale-body-large-size) | Controls docked menu list item label text size. |
--md-date-picker-docked-menu-list-item-label-text-trackingTypography回退值 var(--md-sys-typescale-body-large-tracking) | Controls docked menu list item label text tracking. |
--md-date-picker-docked-menu-list-item-label-text-weightTypography回退值 var(--md-sys-typescale-body-large-weight) | Controls docked menu list item label text weight. |
--md-date-picker-docked-menu-list-item-selected-container-colorState回退值 var(--md-sys-color-surface-variant) | Controls docked menu list item selected container color. |
--md-date-picker-docked-menu-list-item-selected-leading-icon-colorState回退值 var(--md-sys-color-on-surface) | Controls docked menu list item selected leading icon color. |
--md-date-picker-docked-weekdays-label-text-colorColor回退值 var(--md-sys-color-on-surface) | Controls docked weekdays label text color. |
--md-date-picker-docked-weekdays-label-text-fontTypography回退值 var(--md-sys-typescale-body-large-font) | Controls docked weekdays label text font. |
--md-date-picker-docked-weekdays-label-text-line-heightTypography回退值 var(--md-sys-typescale-body-large-line-height) | Controls docked weekdays label text line height. |
--md-date-picker-docked-weekdays-label-text-sizeLayout回退值 var(--md-sys-typescale-body-large-size) | Controls docked weekdays label text size. |
--md-date-picker-docked-weekdays-label-text-trackingTypography回退值 var(--md-sys-typescale-body-large-tracking) | Controls docked weekdays label text tracking. |
--md-date-picker-docked-weekdays-label-text-weightTypography回退值 var(--md-sys-typescale-body-large-weight) | Controls docked weekdays label text weight. |