Angular Material 日期选择器 API 参考

import {MatDatepickerModule} from '@angular/material/datepicker';

提供默认的日期范围选择行为。

方法
createDrag
参数

dragOrigin

D

originalRange

DateRange<D>

newDate

D

createPreview
参数

activeDate

D

currentRange

DateRange<D>

selectionFinished
参数

date

D

currentRange

DateRange<D>

需要国际化的日期选择器数据。

属性
名称 描述

calendarLabel: 'Calendar'

日历弹出框的标签（由屏幕阅读器使用）。

changes: Subject<void>

只要这里的标签发生了变化就会发出流。如果标签在初始化后发生了变化，用它来通知组件。

closeCalendarLabel: 'Close calendar'

该按钮的标签用于关闭日历弹出窗口。

nextMonthLabel: 'Next month'

下个月按钮的标签（由屏幕阅读器使用）。

nextMultiYearLabel: 'Next 24 years'

下一个多年按钮的标签（由屏幕阅读器使用）。

nextYearLabel: 'Next year'

下一年按钮的标签（由屏幕阅读器使用）。

openCalendarLabel: 'Open calendar'

该按钮的标签，用于打开日历弹出框（由屏幕阅读器使用）。

prevMonthLabel: 'Previous month'

上个月按钮的标签（由屏幕阅读器使用）。

prevMultiYearLabel: 'Previous 24 years'

前一个多年按钮的标签（由屏幕阅读器使用）。

prevYearLabel: 'Previous year'

上一年按钮的标签（由屏幕阅读器使用）。

switchToMonthViewLabel: 'Choose date'

“切换到月份视图”按钮的标签（由屏幕阅读器使用）。

switchToMultiYearViewLabel: 'Choose month and year'

“切换到年份视图”按钮的标签（由屏幕阅读器使用）。
Deprecated

endDateLabel: 'End date'

日期范围中最后一个日期的标签（由屏幕阅读器使用）。
Deprecated

startDateLabel: 'Start date'

日期范围中第一个日期的标签（由屏幕阅读器使用）。
方法
formatYearRange

格式化年份范围（供视觉读取使用）。
参数

start

string

end

string

返回值
string

formatYearRangeLabel

格式化一系列年份的标签（由屏幕阅读器使用）。
参数

start

string

end

string

返回值
string

用于把输入框连接到 MatDatepicker 的指令。

选择器： input[matDatepicker]

Exported as: matDatepickerInput
属性
名称 描述
@Input('matDatepickerFilter')

dateFilter: DateFilterFn<D>

可以用来过滤掉日期选择器中日期的函数。
@Input({ transform: booleanAttribute })

disabled: boolean

datepicker-input 是否已禁用了。
@Input()

matDatepicker: MatDatepickerPanel<MatDatepickerControl<D>, D, D>

与此输入框关联的日期选择器。
@Input()

max: D | null

最大有效日期。
@Input()

min: D | null

最小有效日期。
@Input()

value: D | null

输入框的值。
@Output()

dateChange: EventEmitter<MatDatepickerInputEvent<D, S>>

<input> 上触发 change 事件时发出通知。
@Output()

dateInput: EventEmitter<MatDatepickerInputEvent<D, S>>

<input> 上触发 input 事件时发出通知。

stateChanges: Subject<void>

当内部状态发生变化时触发
方法
getConnectedOverlayOrigin

获取日期选择器弹出框应该连接到的元素。
返回值
ElementRef

要把弹出框连接到的元素。
getOverlayLabelId

获取元素的 ID，该元素的 ID 用作日历浮层的描述。
返回值
string | null

getStartValue

获取日历的起始日期。
返回值
D | null

getThemePalette

返回输入框表单字段中使用的调色板（如果有）。
返回值
ThemePalette

负责管理日期范围选择器弹出/对话框的组件。

选择器： mat-date-range-picker

Exported as: matDateRangePicker
属性
名称 描述
@Input()

calendarHeaderComponent: ComponentType<any>

一个输入属性，用于指示日历的自定义标头组件的类型（如果已设置）。
@Input()

color: ThemePalette

要在日期选择器的日历上使用的调色板。
@Input()

dateClass: MatCalendarCellClassFunction<D>

可以用来为日期添加自定义 CSS 类的函数。
@Input({ transform: booleanAttribute })

disabled: boolean

是否应该禁用日期选择器的弹出窗口。
@Input({ transform: booleanAttribute })

opened: boolean

日历是否处于打开状态。
@Input()

panelClass: string | string[]

要传递给日期选择器面板的类。支持字符串和字符串数组的值，类似于 ngClass。
@Input({ transform: booleanAttribute })

restoreFocus: boolean

当日历关闭时，是否要把焦点恢复到之前拥有焦点的元素。请注意，自动恢复焦点是一种无障碍功能，如果你决定将其关闭，建议你提供自己的等效对象。
@Input()

startAt: D | null

打开日历时的初始日期。
@Input()

startView: 'month' | 'year' | 'multi-year'

日历应该启动到哪个视图。
@Input({ transform: booleanAttribute })

touchUi: boolean

日历 UI 是否处于触摸模式。在触摸模式下，日历会在一个对话框中打开，而不是下拉框，而且元素有更大的衬距，以允许更大的触摸目标。
@Input()

xPosition: DatepickerDropdownPositionX

日期选择器在 X 轴上的首选位置。
@Input()

yPosition: DatepickerDropdownPositionY

日期选择器在 Y 轴上的首选位置。
@Output('closed')

closedStream: EventEmitter<void>

当日期选择器已关闭时触发。
@Output()

monthSelected: EventEmitter<D>

在年份视图中选定月份时触发。这并不会更改选定日期。
@Output('opened')

openedStream: EventEmitter<void>

当日期选择器打开时发出通知。
@Output()

viewChanged: EventEmitter<MatCalendarView>

当前视图发生变化时触发。
@Output()

yearSelected: EventEmitter<D>

在多年视图中选出年份时触发。这并不会更改选定日期。

datepickerInput: C

此日期选择器关联到的输入框元素。

id: string

日期选择器日历的 id。

stateChanges: Subject<void>

当日期选择器的状态发生变化时触发。
方法
close

关闭日历。
open

打开日历。
registerActions

使用日期选择器注册一个包含操作按钮的传送点。
参数

portal

TemplatePortal<any>

要注册的传送点。
registerInput

用这个日期选择器注册一个输入框。
参数

input

C

要注册这个日期选择器的输入框。
返回值
MatDateSelectionModel<S, D>

输入应该挂钩到的选择模型。
removeActions

从日期选择器中删除一个包含动作按钮的传送点。
参数

portal

TemplatePortal<any>

要删除的传送点。
select

选择指定的日期
参数

date

D

用于在 mat-date-range-input 中输入起始日期的输入框。

选择器： input[matStartDate]

属性
名称 描述
@Input({ transform: booleanAttribute })

disabled: boolean

datepicker-input 是否已禁用了。
@Input()

errorStateMatcher: ErrorStateMatcher

用于控制何时显示错误信息的对象。
@Input()

value: D | null

输入框的值。
@Output()

dateChange: EventEmitter<MatDatepickerInputEvent<D, S>>

<input> 上触发 change 事件时发出通知。
@Output()

dateInput: EventEmitter<MatDatepickerInputEvent<D, S>>

<input> 上触发 input 事件时发出通知。

errorState: boolean

输入框是否处于出错状态。

stateChanges: Subject<void>

当内部状态发生变化时触发
方法
focus

让输入框获得焦点。
getMirrorValue

获取镜像输入框大小时应该使用的值。
返回值
string

isEmpty

获取输入框的结果是否为空。
返回值
boolean

updateErrorState

刷新输入的错误状态。

用于在 mat-date-range-input 中输入结束日期的输入框。

选择器： input[matEndDate]

属性
名称 描述
@Input({ transform: booleanAttribute })

disabled: boolean

datepicker-input 是否已禁用了。
@Input()

errorStateMatcher: ErrorStateMatcher

用于控制何时显示错误信息的对象。
@Input()

value: D | null

输入框的值。
@Output()

dateChange: EventEmitter<MatDatepickerInputEvent<D, S>>

<input> 上触发 change 事件时发出通知。
@Output()

dateInput: EventEmitter<MatDatepickerInputEvent<D, S>>

<input> 上触发 input 事件时发出通知。

errorState: boolean

输入框是否处于出错状态。

stateChanges: Subject<void>

当内部状态发生变化时触发
方法
focus

让输入框获得焦点。
getMirrorValue

获取镜像输入框大小时应该使用的值。
返回值
string

isEmpty

获取输入框的结果是否为空。
返回值
boolean

updateErrorState

刷新输入的错误状态。

MatCalendar 的默认标头

选择器： mat-calendar-header

Exported as: matCalendarHeader
属性
名称 描述

calendar: MatCalendar<D>

nextButtonLabel: string

下一个按钮的标签。

periodButtonDescription: string

当前日历视图的 ARIA 描述。

periodButtonLabel: string

用于更改日历视图的 aria-label 。

periodButtonText: string

当前日历视图的标签。

prevButtonLabel: string

前一个按钮的标签。
方法
currentPeriodClicked

处理用户点击“时间段标签”的操作。
nextClicked

处理用户点击“下月”按钮的操作。
nextEnabled

是否启用“下个时间段”按钮。
返回值
boolean

previousClicked

处理用户点击“上月”按钮的操作。
previousEnabled

是否启用“上个时间段”按钮。
返回值
boolean

一个用作日期选择器一部分的日历。

选择器： mat-calendar

Exported as: matCalendar
属性
名称 描述
@Input()

comparisonEnd: D | null

比较范围的结束日期。
@Input()

comparisonStart: D | null

比较范围的起始日期。
@Input()

dateClass: MatCalendarCellClassFunction<D>

可以用来为日期添加自定义 CSS 类的函数。
@Input()

dateFilter: (date: D) => boolean

用于过滤可选择哪些日期的函数。
@Input()

endDateAccessibleName: string | null

<input matEndDate/> 的 ARIA 无障碍名称
@Input()

headerComponent: ComponentType<any>

一个指出标头组件类型的输入属性（如果已设置）。
@Input()

maxDate: D | null

最大可选日期。
@Input()

minDate: D | null

最小可选日期。
@Input()

selected: DateRange<D> | D | null

当前选定日期。
@Input()

startAt: D | null

表示时间段（月或年）的起始日期。
@Input()

startDateAccessibleName: string | null

<input matStartDate/> 的 ARIA 无障碍名称
@Input()

startView: MatCalendarView

日历应该开始于月份视图还是年份视图。
@Output()

monthSelected: EventEmitter<D>

在年份视图中选择月份。这不会更改选定日期。
@Output()

selectedChange: EventEmitter<D | null>

当前选定的日期发生变化时发出通知。
@Output()

viewChanged: EventEmitter<MatCalendarView>

当前视图发生变化时触发。
@Output()

yearSelected: EventEmitter<D>

在多年份视图中选择年份。这不会更改选定日期。

activeDate: D

目前的活跃日期。这决定了在使用键盘导航时会显示哪个时间段以及突出显示的是哪个日期。

currentView: MatCalendarView

此日历是否位于月份视图中。

monthView: MatMonthView<D>

引用当前的月份视图组件。

multiYearView: MatMultiYearView<D>

引用当前的多年份视图组件。

stateChanges: Subject<void>

每当状态发生变化时，都会发出标头可能需要响应的信息。

yearView: MatYearView<D>

引用当前的年份视图组件。
方法
focusActiveCell

聚焦活动日期。
updateTodaysDate

在活动日期更新后更新今天的日期

负责管理日期选择器弹出/对话框的组件。

选择器： mat-datepicker

Exported as: matDatepicker
属性
名称 描述
@Input()

calendarHeaderComponent: ComponentType<any>

一个输入属性，用于指示日历的自定义标头组件的类型（如果已设置）。
@Input()

color: ThemePalette

要在日期选择器的日历上使用的调色板。
@Input()

dateClass: MatCalendarCellClassFunction<D>

可以用来为日期添加自定义 CSS 类的函数。
@Input({ transform: booleanAttribute })

disabled: boolean

是否应该禁用日期选择器的弹出窗口。
@Input({ transform: booleanAttribute })

opened: boolean

日历是否处于打开状态。
@Input()

panelClass: string | string[]

要传递给日期选择器面板的类。支持字符串和字符串数组的值，类似于 ngClass。
@Input({ transform: booleanAttribute })

restoreFocus: boolean

当日历关闭时，是否要把焦点恢复到之前拥有焦点的元素。请注意，自动恢复焦点是一种无障碍功能，如果你决定将其关闭，建议你提供自己的等效对象。
@Input()

startAt: D | null

打开日历时的初始日期。
@Input()

startView: 'month' | 'year' | 'multi-year'

日历应该启动到哪个视图。
@Input({ transform: booleanAttribute })

touchUi: boolean

日历 UI 是否处于触摸模式。在触摸模式下，日历会在一个对话框中打开，而不是下拉框，而且元素有更大的衬距，以允许更大的触摸目标。
@Input()

xPosition: DatepickerDropdownPositionX

日期选择器在 X 轴上的首选位置。
@Input()

yPosition: DatepickerDropdownPositionY

日期选择器在 Y 轴上的首选位置。
@Output('closed')

closedStream: EventEmitter<void>

当日期选择器已关闭时触发。
@Output()

monthSelected: EventEmitter<D>

在年份视图中选定月份时触发。这并不会更改选定日期。
@Output('opened')

openedStream: EventEmitter<void>

当日期选择器打开时发出通知。
@Output()

viewChanged: EventEmitter<MatCalendarView>

当前视图发生变化时触发。
@Output()

yearSelected: EventEmitter<D>

在多年视图中选出年份时触发。这并不会更改选定日期。

datepickerInput: C

此日期选择器关联到的输入框元素。

id: string

日期选择器日历的 id。

stateChanges: Subject<void>

当日期选择器的状态发生变化时触发。
方法
close

关闭日历。
open

打开日历。
registerActions

使用日期选择器注册一个包含操作按钮的传送点。
参数

portal

TemplatePortal<any>

要注册的传送点。
registerInput

用这个日期选择器注册一个输入框。
参数

input

C

要注册这个日期选择器的输入框。
返回值
MatDateSelectionModel<S, D>

输入应该挂钩到的选择模型。
removeActions

从日期选择器中删除一个包含动作按钮的传送点。
参数

portal

TemplatePortal<any>

要删除的传送点。
select

选择指定的日期
参数

date

D

可以用来改写 matDatepickerToggle 的图标。

选择器： [matDatepickerToggleIcon]

选择器： mat-datepicker-toggle

Exported as: matDatepickerToggle
属性
名称 描述
@Input('aria-label')

ariaLabel: string

该按钮的屏幕阅读器标签。
@Input('for')

datepicker: MatDatepickerPanel<MatDatepickerControl<any>, D>

该按钮将切换到的日期选择器实例。
@Input()

disableRipple: boolean

是否要禁用本开关上的涟漪。
@Input({ transform: booleanAttribute })

disabled: boolean

按钮开关是否已禁用。

选择器： mat-date-range-input

Exported as: matDateRangeInput
属性
名称 描述
@Input()

comparisonEnd: D | null

应该在日历中显示的比较范围的结束日期。
@Input()

comparisonStart: D | null

应该在日历中显示的比较范围的起始日期。
@Input()

dateFilter: DateFilterFn<D>

可用于过滤掉日期范围选择器中日期的函数。
@Input({ transform: booleanAttribute })

disabled: boolean

输入框是否已禁用。
@Input()

max: D | null

最大有效日期。
@Input()

min: D | null

最小有效日期。
@Input()

rangePicker: MatDatepickerPanel<MatDatepickerControl<D>, DateRange<D>, D>

此输入框所关联的范围选择器。
@Input({ transform: booleanAttribute })

required: boolean

输入框是否为必需的。
@Input()

separator: '–'

要在输入框之间显示的分隔符文本。

controlType: 'mat-date-range-input'

表单控件的名字。

empty: boolean

日期选择器输入框是否为空。

errorState: boolean

输入框是否处于出错状态。

focused: false

控件是否有焦点。

id: `mat-date-range-input-${nextUniqueId++}`

输入框的唯一 ID。

shouldLabelFloat: boolean

控件的标签是否应该浮动。

stateChanges: Subject<void>

当输入框状态发生变化时触发。

value:

范围输入框的当前值。
方法
getConnectedOverlayOrigin

获取要附着日历浮层的元素。
返回值
ElementRef

getOverlayLabelId

获取元素的 ID，该元素的 ID 用作日历浮层的描述。
返回值
string | null

getStartValue

获取日历的起始日期。
返回值
D | null

getThemePalette

获取输入框的主题调色板。
返回值
ThemePalette

该按钮用于关闭 datepicker，并将当前选择内容赋值给数据模型。

选择器： [matDatepickerApply] [matDateRangePickerApply]

该按钮用于关闭日期选择器并丢弃当前的选择。

选择器： [matDatepickerCancel] [matDateRangePickerCancel]

可以用来把一行动作按钮投影到日期选择器或日期范围选择器底部的容器。

选择器： mat-datepicker-actions mat-date-range-picker-actions

用于日期选择器的输入框和变更事件。我们并不总是能访问原生的 input 或者 change 事件，因为用户点击日历弹出窗口时可能会触发该事件。为了保持一致性，我们总是要改用 MatDatepickerInputEvent。

属性
名称 描述

target: MatDatepickerInputBase<S, D>

对发出事件的日期选择器输入组件的引用。

targetElement: HTMLElement

与日期选择器输入关联的原生输入元素的引用。

value: D | null

目标日期选择器输入框控件的新值。

表示日期范围的类。

属性
名称 描述

end: D | null

此范围的截止日期。

start: D | null

此范围的起始日期。

可以提供的对象是为了自定义日期范围的选择行为。

方法
createDrag

当用户将当前选定范围内的日期拖到另一个日期时调用。返回应由此交互产生的日期更新范围。
参数

dateOrigin

用户开始拖动的日期。

originalRange

DateRange<D>

最初选择的日期范围。

newDate

D

拖动操作中的当前目标日期。

event

Event

触发更新拖动状态的 DOM 事件。将是 mouseenter / mouseup 或 touchmove / touchend 之一，具体取决于设备类型。

dragOrigin

D

返回值
DateRange<D> | null

createPreview

当用户激活一个新日期时（例如，通过将鼠标悬停在此区域或移动焦点上）以及当日历尝试显示一个日期范围时，就会调用它。
参数

activeDate

D

用户已激活的日期。如果用户把焦点移到了一个不是日历单元格的元素上，它就是 null。

currentRange

DateRange<D>

当前在日历里显示的范围。

event

Event

导致预览发生变化的 DOM 事件。可能是 mouseenter/mouseleave 或 focus/blur，具体取决于用户的导航方式。
返回值
DateRange<D>

selectionFinished

当用户选择完一个值时调用。
参数

date

D

被选定的日期。如果用户清除了该选项，则该值为 null。

currentRange

DateRange<D>

当前显示在日历表中的范围。

event

Event

触发了此次选择的 DOM 事件。目前，它只对应一个 click 事件，但以后可能会进一步扩展。
返回值
DateRange<D>

可以和日期选择器关联的表单控件。

属性
名称 描述

dateFilter: DateFilterFn<D>

disabled: boolean

max: D | null

min: D | null

stateChanges: Observable<void>

方法
getConnectedOverlayOrigin
返回值
ElementRef

getOverlayLabelId
返回值
string | null

getStartValue
返回值
D | null

getThemePalette
返回值
ThemePalette

一个可以附着到 {@link MatDatepickerControl} 上的日期选择器。

属性
名称 描述

closedStream: EventEmitter<void>

只要日期选择器关闭就会发出通知的流。

color: ThemePalette

要在日期选择器的日历上使用的调色板。

datepickerInput: C

日期选择器关联到的输入框元素。

disabled: boolean

是否应该禁用日期选择器的弹出窗口。

id: string

日期选择器日历的 id。

opened: boolean

该日期选择器是否已打开。

openedStream: EventEmitter<void>

每当打开日期选择器时就会发出通知的流。

stateChanges: Subject<void>

当日期选择器的状态发生变化时触发。
方法
open

打开 datepicker。
registerInput

用日期选择器注册一个输入。
参数

input

C

返回值
MatDateSelectionModel<S, D>

当用户操作后发出日历中日期的事件。

属性
名称 描述

event: Event

value: D

日期选择器下拉列表沿 X 轴的可能位置。

type DatepickerDropdownPositionX = 'start' | 'end';

日期选择器下拉列表沿 Y 轴的可能位置。

type DatepickerDropdownPositionY = 'above' | 'below';

可以用来过滤日历中日期的函数。

type DateFilterFn = (date: D | null) => boolean;

可以与日历单元格关联的额外 CSS 类。

type MatCalendarCellCssClasses = string | string[] | Set<string> | {
    [key: string]: any;
};

一个函数，可以生成要添加到日历单元格中的额外类。

type MatCalendarCellClassFunction = (date: D, view: 'month' | 'year' | 'multi-year') => MatCalendarCellCssClasses;

用于自定义选择日期范围的行为的注入令牌。

const MAT_DATE_RANGE_SELECTION_STRATEGY: InjectionToken<MatDateRangeSelectionStrategy<any>>;

此注入令牌决定了当日历打开时滚动的处理策略。

const MAT_DATEPICKER_SCROLL_STRATEGY: InjectionToken<() => ScrollStrategy>;

const yearsPerPage: 24;

const yearsPerRow: 4;