Angular Material Datepicker 公開 API 全解析從日歷組件到日期范圍選擇策略【免費下載鏈接】componentsComponent infrastructure and Material Design components for Angular項目地址: https://gitcode.com/GitHub_Trending/co/components本文基于 Angular Material 組件庫倉庫中的 API 報告 goldens/material/datepicker/index.api.md由 API Extractor 自動生成與官方使用指南 src/material/datepicker/datepicker.md 整理而成系統梳理 Datepicker 模塊的全部公開 API 表面日歷三視圖、日期選擇模型、范圍選擇策略、輸入/切換/操作按鈕指令以及國際化注入令牌。讀者讀完后可以準確理解MatDatepicker生態中各公開類型、接口與注入令牌的職責劃分并能在自己的 Angular 應用中正確引用、繼承或注入這些 API。Datepicker 模塊的公開 API 全景Datepicker 不是單一組件而是由「彈出面板 輸入框 日歷網格 選擇模型」組合而成的功能家族。API 報告顯示angular/material/datepicker的公開 API 覆蓋了從底層日歷視圖到高層表單控件的完整層級類型別名type aliasDateFilterFn、DatepickerDropdownPositionX/Y、MatCalendarView、MatCalendarCellClassFunction、MatCalendarCellCssClasses、ExtractDateTypeFromSelection常量與注入令牌yearsPerPage、yearsPerRow、MAT_DATE_RANGE_SELECTION_STRATEGY、MAT_DATEPICKER_SCROLL_STRATEGY、MAT_DATEPICKER_VALIDATORS、MAT_DATEPICKER_VALUE_ACCESSOR日歷視圖組件MatCalendar、MatMonthView、MatYearView、MatMultiYearView、MatCalendarBody、MatCalendarHeader、MatCalendarCell日期選擇模型MatDateSelectionModel抽象基類、MatSingleDateSelectionModel、MatRangeDateSelectionModel、DateRange日期選擇器組件MatDatepicker、MatDateRangePicker、MatDatepickerContent、MatDatepickerInput、MatDateRangeInput、MatStartDate、MatEndDate、MatDatepickerToggle、MatDatepickerActions、MatDatepickerApply、MatDatepickerCancel國際化服務MatDatepickerIntl模塊MatDatepickerModule。其中MatCalendarView是貫穿全模塊的核心類型其取值決定了日歷當前展示的視圖層級export type MatCalendarView month | year | multi-year;與之配套的是分頁常量yearsPerPage 24與yearsPerRow 4它們共同決定了多年度視圖multi-year view的網格布局——每行展示 4 個年份每頁共 24 個年份這與 API 報告中MatMultiYearView與MatCalendarBody的numCols、rows網格渲染邏輯一一對應。MatCalendar 內聯日歷三種視圖與事件流MatCalendarD是一個可在頁面中直接內聯使用的日歷組件不依賴彈出面板它同時是MatDatepickerContent內部的日歷實現。從 API 報告可以看出它實現了AfterContentInit、AfterViewChecked、OnChanges、OnDestroy四個生命周期接口輸入輸出非常豐富。關鍵輸入Input輸入類型說明headerComponentComponentTypeany自定義日歷頭部組件即指南中的calendarHeaderComponentstartAtD \| null日歷打開時定位的起始日期startViewMatCalendarView初始視圖month/year/multi-year默認為monthselectedDateRangeD \| D \| null當前選中值兼容單選與范圍選擇minDate/maxDateD \| null可選日期下限/上限dateFilter(date: D) boolean單日期禁用過濾器dateClassMatCalendarCellClassFunctionD為特定日期附加 CSS 類comparisonStart/comparisonEndD \| null對比范圍comparison range的起止startDateAccessibleName/endDateAccessibleNamestring \| null起止日期的無障礙名稱關鍵輸出OutputselectedChange選中值變化yearSelected/monthSelected在 multi-year 與 year 視圖中選中年份/月份時發出「歸一化日期」——年份會歸一化為該年 1 月 1 日月份會歸一化為該月 1 日例如使用原生Date時選中 2017 年會發出new Date(2017, 0, 1)viewChanged視圖切換事件_userSelection/_userDragDrop內部使用的用戶選擇與拖拽事件下劃線開頭屬于私有/內部 API。MatCalendar還暴露了focusActiveCell()、updateTodaysDate()等公開方法以及activeDate當前活動日期可讀寫和currentView當前視圖可讀寫兩個可讀寫屬性用于程序化控制日歷狀態。三種視圖組件的職責分工API 報告中的三個視圖組件MatMonthView、MatYearView、MatMultiYearView具有高度一致的結構都注入DateAdapter、實現AfterContentInit與OnDestroy、擁有activeDate/selected/minDate/maxDate/dateFilter/dateClass輸入并各自發出對應的選中事件MatMonthView發出selectedChange、_userSelection、dragStarted、dragEnded、activeDateChangeMatYearView發出selectedChange、monthSelected、activeDateChangeMatMultiYearView發出selectedChange、yearSelected、activeDateChange。三者均持有_matCalendarBody: MatCalendarBody把日期網格的實際渲染與鍵盤交互委托給MatCalendarBody選擇器[mat-calendar-body]。MatCalendarBody內部以rows: MatCalendarCell[][]描述網格并提供_isInRange、_isRangeStart、_isRangeEnd、_isInPreview、_isComparisonStart、_isInComparisonRange等大量私有判斷方法用于繪制選中、懸停預覽與對比范圍的高亮狀態。日歷單元格與 CSS 類MatCalendarCellD是網格中的單個單元格數據類字段包括value數值、displayValue顯示文本、ariaLabel無障礙標簽、enabled是否可選、cssClasses、compareValue對比值與rawValue原始日期值。MatCalendarHeaderD則是默認頭部提供上一段/下一段導航按鈕與視圖切換按鈕currentPeriodClicked、nextClicked、previousClicked等方法。日期高亮通過MatCalendarCellClassFunctionD實現export type MatCalendarCellClassFunctionD ( date: D, view: month | year | multi-year, ) MatCalendarCellCssClasses; export type MatCalendarCellCssClasses | string | string[] | Setstring | Recordstring, any;返回值可以是ngClass支持的任何形式例如在月份視圖中把周末日期附加自定義類。使用指南在「Highlighting specific dates」一節中對此有完整示例見 datepicker.md。日期選擇模型單選與范圍選的內在邏輯MatDateSelectionModelS, D是模塊內部的抽象選擇模型公開但標注為 docs-private 用途它通過selectionChanged: ObservableDateSelectionModelChangeS對外廣播變化DateSelectionModelChangeS接口包含selection新值、source觸發源與可選的oldValue舊值。抽象基類定義四個抽象方法add(date: D | null)向當前選擇添加一個日期isValid()當前選擇是否合法isComplete()當前選擇是否完整clone()克隆模型。MatSingleDateSelectionModelD的add語義是「新日期直接覆蓋舊選擇」isComplete()只要selection ! null即為真。MatRangeDateSelectionModelD的add語義則是經典的「兩段式填充」源碼見 date-selection-model.tsstart為空 → 把日期設為startstart非空且end為空 → 把日期設為end兩者都已填滿 → 重置新日期成為新的startend置空。其isValid()的判定同樣值得注意同一文件 L174-L197空范圍合法完整范圍要求兩端都是合法日期實例且start end部分范圍要求已有的那一端合法。兩個模型類都提供了工廠 providerMAT_SINGLE_DATE_SELECTION_MODEL_PROVIDER/MAT_RANGE_DATE_SELECTION_MODEL_PROVIDER通過useFactory在找不到父級模型時自動創建默認模型從而在MatCalendar與MatDatepickerContent之間共享同一份選擇狀態。DateRangeD是范圍選擇的載體類型start/end均為可空的只讀字段且通過私有字段_disableStructuralEquivalency!: never阻止結構等價的對象被直接賦值給DateRange類型變量保證類型安全。日期范圍選擇策略MAT_DATE_RANGE_SELECTION_STRATEGY 與拖拽范圍選擇的行為邏輯被抽象為MatDateRangeSelectionStrategyD接口與渲染層解耦。該接口包含三個方法完整定義見 date-range-selection-strategy.ts方法觸發時機selectionFinished(date, currentRange, event)用戶完成一次點選event目前對應clickcreatePreview(activeDate, currentRange, event)用戶懸停或聚焦新日期日歷需展示預覽范圍createDrag?(dragOrigin, originalRange, newDate, event)用戶拖拽已有范圍的一端可選實現模塊內置的默認實現是DefaultMatCalendarRangeStrategyD其點選邏輯是start為空則設置startstart已存在且end為空、新日期不早于start則補全end否則重置為「新日期為 start、end 為空」。預覽邏輯是只有「已有 start、無 end、存在活動日期」時才顯示從start到活動日期的預覽范圍。createDrag的默認實現支持拖拽范圍的兩端來調整范圍長度同時保持范圍長度不變——當拖拽起點是start時更新start若越過end則同步平移end拖拽end時對稱處理date-range-selection-strategy.ts。這一整套行為通過注入令牌替換export const MAT_DATE_RANGE_SELECTION_STRATEGY: InjectionTokenMatDateRangeSelectionStrategyany;官方指南中的典型場景是自定義策略把范圍限制為「恰好 5 天」。使用時先實現接口再在 providers 中提供該令牌即可bootstrapApplication(MyApp, { providers: [ {provide: MAT_DATE_RANGE_SELECTION_STRATEGY, useClass: FiveDayRangeSelectionStrategy}, ], });日期選擇器面板與表單控件MatDatepicker 與 MatDatepickerBaseMatDatepickerD繼承自MatDatepickerBaseMatDatepickerControlD, D | null, D負責彈出面板本身MatDateRangePickerD則繼承MatDatepickerBaseMatDateRangePickerInputD, DateRangeD, D用于范圍選擇。面板與輸入框之間的契約由接口MatDatepickerPanelC, S, D定義export interface MatDatepickerPanelC extends MatDatepickerControlD, S, D { closedStream: EventEmittervoid; color: ThemePalette; datepickerInput: C; disabled: boolean; id: string; opened: boolean; openedStream: EventEmittervoid; registerInput(input: C): MatDateSelectionModelS, D; stateChanges: Subjectvoid; open(): void; }MatDatepickerControlD則是輸入控件需要實現的接口包含dateFilter、min/max、disabled、stateChanges、getConnectedOverlayOrigin()、getStartValue()、getThemePalette()、getOverlayLabelId()等成員。這種接口化設計使得MatDatepickerToggle、MatDatepickerActions等都能面向接口編程同時兼容普通 input 與 range input。MatDatepickerInput 與表單接入MatDatepickerInputD選擇器input[matDatepicker]實現了ControlValueAccessor因此可以無縫配合formControl、ngModel、formGroupName等angular/forms指令。其輸入別名在 API 報告中可以查到輸入別名說明matDatepickermatDatepicker綁定的日期選擇器面板min/maxmin/max最小/最大可選日期同時注冊驗證器dateFiltermatDatepickerFilter日期過濾函數DateFilterFnDDateFilterFnD的類型定義是(date: D | null) boolean。min/max/matDatepickerFilter三種驗證分別產生matDatepickerMin、matDatepickerMax、matDatepickerFilter三種錯誤鍵可直接在模板錯誤提示中判斷。MatDatepickerInput還提供兩個專有事件與原生(input)/(change)區分原生事件在日歷中選擇時不會觸發(dateInput)用戶在輸入框鍵入或從日歷選擇導致值變化時觸發(dateChange)用戶完成鍵入輸入框失焦或從日歷選定日期時觸發。MatDateRangeInput 家族MatDateRangeInputD選擇器mat-date-range-input實現MatFormFieldControlDateRangeD內部要求兩個子輸入框input[matStartDate]與input[matEndDate]對應MatStartDateD與MatEndDateD兩個指令。典型模板mat-date-range-input [rangePicker]picker input matStartDate placeholderStart date input matEndDate placeholderEnd date /mat-date-range-input mat-date-range-picker #picker/mat-date-range-picker該組件還支持separator起止日期間的分隔符、comparisonStart/comparisonEnd對比范圍輸入并實現了disableAutomaticLabeling、onContainerClick()、setDescribedByIds()等MatFormFieldControl契約方法可與mat-form-field的浮動標簽、錯誤提示深度集成。配合FormGroup指令可以把起止日期作為一個整體分組校驗官方示例見 date-range-picker-forms。切換按鈕與操作按鈕MatDatepickerToggleD選擇器mat-datepicker-toggle提供打開面板的圖標按鈕輸入for別名綁定面板、tabIndex、aria-label、disabled、disableRipple。圖標內容可通過[matDatepickerToggleIcon]指令自定義對應MatDatepickerToggleIcon指令。MatDatepickerActions選擇器mat-datepicker-actions, mat-date-range-picker-actions與兩個指令配合實現「確認/取消」流程[matDatepickerApply]/[matDateRangePickerApply]應用當前選擇并關閉[matDatepickerCancel]/[matDateRangePickerCancel]放棄選擇并關閉。啟用操作按鈕后點擊日期不再立即提交而是等用戶顯式點擊「Apply」才把值寫入數據模型這對無障礙用戶尤其重要。此特性在 API 報告中體現為MatDatepickerContent的_actionsPortal與_assignActions()機制——操作按鈕內容通過TemplatePortal注入到彈出面板的 actions 區域。注入令牌與國際化MAT_DATEPICKER 系令牌API 報告列出了三個與日期選擇器內部機制相關的注入令牌export const MAT_DATEPICKER_SCROLL_STRATEGY: InjectionToken() ScrollStrategy; export const MAT_DATEPICKER_VALIDATORS: any; export const MAT_DATEPICKER_VALUE_ACCESSOR: any;MAT_DATEPICKER_SCROLL_STRATEGY自定義彈出面板的滾動策略返回ScrollStrategy工廠函數基于angular/cdk/overlayMAT_DATEPICKER_VALUE_ACCESSOR提供ControlValueAccessor的 multi-provider實現MatDatepickerInput與angular/forms的橋接MAT_DATEPICKER_VALIDATORS注冊日期驗證器的 multi-provider。這些令牌在 datepicker-input.ts 與 datepicker-base.ts 中定義并提供普通使用者一般不需要直接觸碰但理解它們有助于排查表單接入問題。國際化四要素與 MatDatepickerIntl指南把日期選擇器國際化拆成四個層面區域設置locale、日期實現DateAdapter、顯示/解析格式MAT_DATE_FORMATS、界面文案MatDatepickerIntl。MatDatepickerIntl服務集中管理所有界面文案API 報告完整列出了其公開字段openCalendarLabel、closeCalendarLabel、nextMonthLabel、prevMonthLabel、nextYearLabel、prevYearLabel、nextMultiYearLabel、prevMultiYearLabel、switchToMonthViewLabel、switchToMultiYearViewLabel、calendarLabel、comparisonDateLabel以及兩個已廢棄字段startDateLabel/endDateLabel標注deprecated。此外還有formatYearRange(start, end)與formatYearRangeLabel(start, end)兩個格式化方法以及changes: Subjectvoid用于廣播文案變更。自定義文案只需子類化并覆蓋字段bootstrapApplication(MyApp, { providers: [ {provide: MatDatepickerIntl, useClass: MyIntl}, provideNativeDateAdapter(), ], });日期實現與格式DateAdapter 與 MAT_DATE_FORMATSDatepicker 是「日期實現無關」的DateAdapterD抽象類定義了對日期類型D的全部操作比較、加減、格式化、解析等。倉庫提供多種現成適配器對應源碼目錄見 src/material 下的 material-date-fns-adapter、material-luxon-adapter、material-moment-adapterAPI 報告中MatCalendar、MatDatepickerInput等類的泛型參數D即由所選適配器決定provideNativeDateAdapter/MatNativeDateModule日期類型Date僅完整支持 en-USprovideDateFnsAdapter/MatDateFnsModule日期類型Date依賴 date-fnsprovideLuxonDateAdapter/MatLuxonDateModule日期類型DateTime依賴 LuxonprovideMomentDateAdapter/MatMomentDateModule日期類型Moment依賴 Moment.js。所有 provider 都同時提供DateAdapter與MAT_DATE_FORMATS。若需自定義解析/顯示格式可覆蓋MAT_DATE_FORMATS或直接把格式對象傳入 provider例如provideNativeDateAdapter(MY_NATIVE_DATE_FORMATS)也可以完全自定義子類化DateAdapter并通過{provide: DateAdapter, useClass: MyDateAdapter}提供。由于DateAdapter是泛型類在ViewChild(MatDatepicker)等場景中應攜帶與所選適配器對應的泛型參數ViewChild(MatDatepicker) datepicker: MatDatepickerDate;無障礙設計與鍵盤交互指南的 Accessibility 一節與 API 報告相互印證MatDatepicker彈出層使用roledialog交互模式內部日歷實現rolegrid模式MatDatepickerInput與MatDatepickerToggle均會設置aria-haspopup屬性對應 API 報告中的getOverlayLabelId()、ariaLabel等成員始終建議啟用確認操作按鈕matDatepickerActions讓輔助技術用戶顯式確認選擇輸入框應通過mat-label、aria-label、aria-labelledby或MatDatepickerIntl提供有意義的標簽并通過mat-hint等方式告知日期格式如 MM/DD/YYYYMatDatepickerToggle與MatDatepicker應同時使用——移動端屏幕閱讀器用戶依賴圖標按鈕打開面板。鍵盤交互方面打開/關閉面板的快捷鍵為AltDown Arrow與Escape月份視圖內支持方向鍵逐日移動、Home/End跳到月初/月末、Page Up/Page Down跨月移動、AltPage Up/Page Down跨年移動、Enter選中當前日期年視圖與多年視圖有對應的同類操作年視圖按 4 個月一行、多年視圖按 4 年一行、每頁 24 項——與yearsPerRow/yearsPerPage常量吻合。常見報錯與排查API 報告與指南共同指向三類高頻錯誤MatDatepicker: No provider found for DateAdapter/MAT_DATE_FORMATS應用缺少日期適配器 provider在 app config 中調用provideNativeDateAdapter()或其它適配器 provider即可解決A MatDatepicker can only be associated with a single input同一個mat-datepicker被多個input通過matDatepicker屬性綁定一個面板只能關聯一個輸入框Attempted to open an MatDatepicker with no associated input面板未關聯任何輸入框需要用模板引用建立綁定input [matDatepicker]picker mat-datepicker #picker/mat-datepicker模塊組織與按需引入MatDatepickerModule的 NgModule 聲明與導出列表在 API 報告中完整可見它內部引入MatButtonModule、OverlayModule來自angular/cdk/overlay、A11yModule、PortalModule聲明并導出了MatCalendar、MatCalendarBody、MatDatepicker、MatDatepickerContent、MatDatepickerInput、MatDatepickerToggle、MatDatepickerToggleIcon、MatMonthView、MatYearView、MatMultiYearView、MatCalendarHeader、MatDateRangeInput、MatStartDate、MatEndDate、MatDateRangePicker、MatDatepickerActions、MatDatepickerCancel、MatDatepickerApply等全部公開組件與指令同時導出BidiModule與CdkScrollableModule供消費者使用。在獨立組件standalone模式下可僅導入用到的組件或MatDatepickerModule整體模塊化應用則在 NgModule 的imports中聲明MatDatepickerModule并在 app config 中同時提供日期適配器。提示完整的 API 報告由 API Extractor 自動生成并受版本金樣golden file機制保護任何公開 API 的增刪改都需要同步更新該報告它是理解模塊「穩定契約」的一手資料。文中所有類型定義、令牌名與組件成員均可對照 goldens/material/datepicker/index.api.md 逐一核實更詳細的用法示例與配置參數請參閱 src/material/datepicker/datepicker.md。【免費下載鏈接】componentsComponent infrastructure and Material Design components for Angular項目地址: https://gitcode.com/GitHub_Trending/co/components創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 Angular Material Datepicker 公開 API 全解析：從日歷組件到日期范圍選擇策略
Angular Material Datepicker 公開 API 全解析從日歷組件到日期范圍選擇策略【免費下載鏈接】componentsComponent infrastructure and Material Design components for Angular項目地址: https://gitcode.com/GitHub_Trending/co/components本文基于 Angular Material 組件庫倉庫中的 API 報告 goldens/material/datepicker/index.api.md由 API Extractor 自動生成與官方使用指南 src/material/datepicker/datepicker.md 整理而成系統梳理 Datepicker 模塊的全部公開 API 表面日歷三視圖、日期選擇模型、范圍選擇策略、輸入/切換/操作按鈕指令以及國際化注入令牌。讀者讀完后可以準確理解MatDatepicker生態中各公開類型、接口與注入令牌的職責劃分并能在自己的 Angular 應用中正確引用、繼承或注入這些 API。Datepicker 模塊的公開 API 全景Datepicker 不是單一組件而是由「彈出面板 輸入框 日歷網格 選擇模型」組合而成的功能家族。API 報告顯示angular/material/datepicker的公開 API 覆蓋了從底層日歷視圖到高層表單控件的完整層級類型別名type aliasDateFilterFn、DatepickerDropdownPositionX/Y、MatCalendarView、MatCalendarCellClassFunction、MatCalendarCellCssClasses、ExtractDateTypeFromSelection常量與注入令牌yearsPerPage、yearsPerRow、MAT_DATE_RANGE_SELECTION_STRATEGY、MAT_DATEPICKER_SCROLL_STRATEGY、MAT_DATEPICKER_VALIDATORS、MAT_DATEPICKER_VALUE_ACCESSOR日歷視圖組件MatCalendar、MatMonthView、MatYearView、MatMultiYearView、MatCalendarBody、MatCalendarHeader、MatCalendarCell日期選擇模型MatDateSelectionModel抽象基類、MatSingleDateSelectionModel、MatRangeDateSelectionModel、DateRange日期選擇器組件MatDatepicker、MatDateRangePicker、MatDatepickerContent、MatDatepickerInput、MatDateRangeInput、MatStartDate、MatEndDate、MatDatepickerToggle、MatDatepickerActions、MatDatepickerApply、MatDatepickerCancel國際化服務MatDatepickerIntl模塊MatDatepickerModule。其中MatCalendarView是貫穿全模塊的核心類型其取值決定了日歷當前展示的視圖層級export type MatCalendarView month | year | multi-year;與之配套的是分頁常量yearsPerPage 24與yearsPerRow 4它們共同決定了多年度視圖multi-year view的網格布局——每行展示 4 個年份每頁共 24 個年份這與 API 報告中MatMultiYearView與MatCalendarBody的numCols、rows網格渲染邏輯一一對應。MatCalendar 內聯日歷三種視圖與事件流MatCalendarD是一個可在頁面中直接內聯使用的日歷組件不依賴彈出面板它同時是MatDatepickerContent內部的日歷實現。從 API 報告可以看出它實現了AfterContentInit、AfterViewChecked、OnChanges、OnDestroy四個生命周期接口輸入輸出非常豐富。關鍵輸入Input輸入類型說明headerComponentComponentTypeany自定義日歷頭部組件即指南中的calendarHeaderComponentstartAtD \| null日歷打開時定位的起始日期startViewMatCalendarView初始視圖month/year/multi-year默認為monthselectedDateRangeD \| D \| null當前選中值兼容單選與范圍選擇minDate/maxDateD \| null可選日期下限/上限dateFilter(date: D) boolean單日期禁用過濾器dateClassMatCalendarCellClassFunctionD為特定日期附加 CSS 類comparisonStart/comparisonEndD \| null對比范圍comparison range的起止startDateAccessibleName/endDateAccessibleNamestring \| null起止日期的無障礙名稱關鍵輸出OutputselectedChange選中值變化yearSelected/monthSelected在 multi-year 與 year 視圖中選中年份/月份時發出「歸一化日期」——年份會歸一化為該年 1 月 1 日月份會歸一化為該月 1 日例如使用原生Date時選中 2017 年會發出new Date(2017, 0, 1)viewChanged視圖切換事件_userSelection/_userDragDrop內部使用的用戶選擇與拖拽事件下劃線開頭屬于私有/內部 API。MatCalendar還暴露了focusActiveCell()、updateTodaysDate()等公開方法以及activeDate當前活動日期可讀寫和currentView當前視圖可讀寫兩個可讀寫屬性用于程序化控制日歷狀態。三種視圖組件的職責分工API 報告中的三個視圖組件MatMonthView、MatYearView、MatMultiYearView具有高度一致的結構都注入DateAdapter、實現AfterContentInit與OnDestroy、擁有activeDate/selected/minDate/maxDate/dateFilter/dateClass輸入并各自發出對應的選中事件MatMonthView發出selectedChange、_userSelection、dragStarted、dragEnded、activeDateChangeMatYearView發出selectedChange、monthSelected、activeDateChangeMatMultiYearView發出selectedChange、yearSelected、activeDateChange。三者均持有_matCalendarBody: MatCalendarBody把日期網格的實際渲染與鍵盤交互委托給MatCalendarBody選擇器[mat-calendar-body]。MatCalendarBody內部以rows: MatCalendarCell[][]描述網格并提供_isInRange、_isRangeStart、_isRangeEnd、_isInPreview、_isComparisonStart、_isInComparisonRange等大量私有判斷方法用于繪制選中、懸停預覽與對比范圍的高亮狀態。日歷單元格與 CSS 類MatCalendarCellD是網格中的單個單元格數據類字段包括value數值、displayValue顯示文本、ariaLabel無障礙標簽、enabled是否可選、cssClasses、compareValue對比值與rawValue原始日期值。MatCalendarHeaderD則是默認頭部提供上一段/下一段導航按鈕與視圖切換按鈕currentPeriodClicked、nextClicked、previousClicked等方法。日期高亮通過MatCalendarCellClassFunctionD實現export type MatCalendarCellClassFunctionD ( date: D, view: month | year | multi-year, ) MatCalendarCellCssClasses; export type MatCalendarCellCssClasses | string | string[] | Setstring | Recordstring, any;返回值可以是ngClass支持的任何形式例如在月份視圖中把周末日期附加自定義類。使用指南在「Highlighting specific dates」一節中對此有完整示例見 datepicker.md。日期選擇模型單選與范圍選的內在邏輯MatDateSelectionModelS, D是模塊內部的抽象選擇模型公開但標注為 docs-private 用途它通過selectionChanged: ObservableDateSelectionModelChangeS對外廣播變化DateSelectionModelChangeS接口包含selection新值、source觸發源與可選的oldValue舊值。抽象基類定義四個抽象方法add(date: D | null)向當前選擇添加一個日期isValid()當前選擇是否合法isComplete()當前選擇是否完整clone()克隆模型。MatSingleDateSelectionModelD的add語義是「新日期直接覆蓋舊選擇」isComplete()只要selection ! null即為真。MatRangeDateSelectionModelD的add語義則是經典的「兩段式填充」源碼見 date-selection-model.tsstart為空 → 把日期設為startstart非空且end為空 → 把日期設為end兩者都已填滿 → 重置新日期成為新的startend置空。其isValid()的判定同樣值得注意同一文件 L174-L197空范圍合法完整范圍要求兩端都是合法日期實例且start end部分范圍要求已有的那一端合法。兩個模型類都提供了工廠 providerMAT_SINGLE_DATE_SELECTION_MODEL_PROVIDER/MAT_RANGE_DATE_SELECTION_MODEL_PROVIDER通過useFactory在找不到父級模型時自動創建默認模型從而在MatCalendar與MatDatepickerContent之間共享同一份選擇狀態。DateRangeD是范圍選擇的載體類型start/end均為可空的只讀字段且通過私有字段_disableStructuralEquivalency!: never阻止結構等價的對象被直接賦值給DateRange類型變量保證類型安全。日期范圍選擇策略MAT_DATE_RANGE_SELECTION_STRATEGY 與拖拽范圍選擇的行為邏輯被抽象為MatDateRangeSelectionStrategyD接口與渲染層解耦。該接口包含三個方法完整定義見 date-range-selection-strategy.ts方法觸發時機selectionFinished(date, currentRange, event)用戶完成一次點選event目前對應clickcreatePreview(activeDate, currentRange, event)用戶懸停或聚焦新日期日歷需展示預覽范圍createDrag?(dragOrigin, originalRange, newDate, event)用戶拖拽已有范圍的一端可選實現模塊內置的默認實現是DefaultMatCalendarRangeStrategyD其點選邏輯是start為空則設置startstart已存在且end為空、新日期不早于start則補全end否則重置為「新日期為 start、end 為空」。預覽邏輯是只有「已有 start、無 end、存在活動日期」時才顯示從start到活動日期的預覽范圍。createDrag的默認實現支持拖拽范圍的兩端來調整范圍長度同時保持范圍長度不變——當拖拽起點是start時更新start若越過end則同步平移end拖拽end時對稱處理date-range-selection-strategy.ts。這一整套行為通過注入令牌替換export const MAT_DATE_RANGE_SELECTION_STRATEGY: InjectionTokenMatDateRangeSelectionStrategyany;官方指南中的典型場景是自定義策略把范圍限制為「恰好 5 天」。使用時先實現接口再在 providers 中提供該令牌即可bootstrapApplication(MyApp, { providers: [ {provide: MAT_DATE_RANGE_SELECTION_STRATEGY, useClass: FiveDayRangeSelectionStrategy}, ], });日期選擇器面板與表單控件MatDatepicker 與 MatDatepickerBaseMatDatepickerD繼承自MatDatepickerBaseMatDatepickerControlD, D | null, D負責彈出面板本身MatDateRangePickerD則繼承MatDatepickerBaseMatDateRangePickerInputD, DateRangeD, D用于范圍選擇。面板與輸入框之間的契約由接口MatDatepickerPanelC, S, D定義export interface MatDatepickerPanelC extends MatDatepickerControlD, S, D { closedStream: EventEmittervoid; color: ThemePalette; datepickerInput: C; disabled: boolean; id: string; opened: boolean; openedStream: EventEmittervoid; registerInput(input: C): MatDateSelectionModelS, D; stateChanges: Subjectvoid; open(): void; }MatDatepickerControlD則是輸入控件需要實現的接口包含dateFilter、min/max、disabled、stateChanges、getConnectedOverlayOrigin()、getStartValue()、getThemePalette()、getOverlayLabelId()等成員。這種接口化設計使得MatDatepickerToggle、MatDatepickerActions等都能面向接口編程同時兼容普通 input 與 range input。MatDatepickerInput 與表單接入MatDatepickerInputD選擇器input[matDatepicker]實現了ControlValueAccessor因此可以無縫配合formControl、ngModel、formGroupName等angular/forms指令。其輸入別名在 API 報告中可以查到輸入別名說明matDatepickermatDatepicker綁定的日期選擇器面板min/maxmin/max最小/最大可選日期同時注冊驗證器dateFiltermatDatepickerFilter日期過濾函數DateFilterFnDDateFilterFnD的類型定義是(date: D | null) boolean。min/max/matDatepickerFilter三種驗證分別產生matDatepickerMin、matDatepickerMax、matDatepickerFilter三種錯誤鍵可直接在模板錯誤提示中判斷。MatDatepickerInput還提供兩個專有事件與原生(input)/(change)區分原生事件在日歷中選擇時不會觸發(dateInput)用戶在輸入框鍵入或從日歷選擇導致值變化時觸發(dateChange)用戶完成鍵入輸入框失焦或從日歷選定日期時觸發。MatDateRangeInput 家族MatDateRangeInputD選擇器mat-date-range-input實現MatFormFieldControlDateRangeD內部要求兩個子輸入框input[matStartDate]與input[matEndDate]對應MatStartDateD與MatEndDateD兩個指令。典型模板mat-date-range-input [rangePicker]picker input matStartDate placeholderStart date input matEndDate placeholderEnd date /mat-date-range-input mat-date-range-picker #picker/mat-date-range-picker該組件還支持separator起止日期間的分隔符、comparisonStart/comparisonEnd對比范圍輸入并實現了disableAutomaticLabeling、onContainerClick()、setDescribedByIds()等MatFormFieldControl契約方法可與mat-form-field的浮動標簽、錯誤提示深度集成。配合FormGroup指令可以把起止日期作為一個整體分組校驗官方示例見 date-range-picker-forms。切換按鈕與操作按鈕MatDatepickerToggleD選擇器mat-datepicker-toggle提供打開面板的圖標按鈕輸入for別名綁定面板、tabIndex、aria-label、disabled、disableRipple。圖標內容可通過[matDatepickerToggleIcon]指令自定義對應MatDatepickerToggleIcon指令。MatDatepickerActions選擇器mat-datepicker-actions, mat-date-range-picker-actions與兩個指令配合實現「確認/取消」流程[matDatepickerApply]/[matDateRangePickerApply]應用當前選擇并關閉[matDatepickerCancel]/[matDateRangePickerCancel]放棄選擇并關閉。啟用操作按鈕后點擊日期不再立即提交而是等用戶顯式點擊「Apply」才把值寫入數據模型這對無障礙用戶尤其重要。此特性在 API 報告中體現為MatDatepickerContent的_actionsPortal與_assignActions()機制——操作按鈕內容通過TemplatePortal注入到彈出面板的 actions 區域。注入令牌與國際化MAT_DATEPICKER 系令牌API 報告列出了三個與日期選擇器內部機制相關的注入令牌export const MAT_DATEPICKER_SCROLL_STRATEGY: InjectionToken() ScrollStrategy; export const MAT_DATEPICKER_VALIDATORS: any; export const MAT_DATEPICKER_VALUE_ACCESSOR: any;MAT_DATEPICKER_SCROLL_STRATEGY自定義彈出面板的滾動策略返回ScrollStrategy工廠函數基于angular/cdk/overlayMAT_DATEPICKER_VALUE_ACCESSOR提供ControlValueAccessor的 multi-provider實現MatDatepickerInput與angular/forms的橋接MAT_DATEPICKER_VALIDATORS注冊日期驗證器的 multi-provider。這些令牌在 datepicker-input.ts 與 datepicker-base.ts 中定義并提供普通使用者一般不需要直接觸碰但理解它們有助于排查表單接入問題。國際化四要素與 MatDatepickerIntl指南把日期選擇器國際化拆成四個層面區域設置locale、日期實現DateAdapter、顯示/解析格式MAT_DATE_FORMATS、界面文案MatDatepickerIntl。MatDatepickerIntl服務集中管理所有界面文案API 報告完整列出了其公開字段openCalendarLabel、closeCalendarLabel、nextMonthLabel、prevMonthLabel、nextYearLabel、prevYearLabel、nextMultiYearLabel、prevMultiYearLabel、switchToMonthViewLabel、switchToMultiYearViewLabel、calendarLabel、comparisonDateLabel以及兩個已廢棄字段startDateLabel/endDateLabel標注deprecated。此外還有formatYearRange(start, end)與formatYearRangeLabel(start, end)兩個格式化方法以及changes: Subjectvoid用于廣播文案變更。自定義文案只需子類化并覆蓋字段bootstrapApplication(MyApp, { providers: [ {provide: MatDatepickerIntl, useClass: MyIntl}, provideNativeDateAdapter(), ], });日期實現與格式DateAdapter 與 MAT_DATE_FORMATSDatepicker 是「日期實現無關」的DateAdapterD抽象類定義了對日期類型D的全部操作比較、加減、格式化、解析等。倉庫提供多種現成適配器對應源碼目錄見 src/material 下的 material-date-fns-adapter、material-luxon-adapter、material-moment-adapterAPI 報告中MatCalendar、MatDatepickerInput等類的泛型參數D即由所選適配器決定provideNativeDateAdapter/MatNativeDateModule日期類型Date僅完整支持 en-USprovideDateFnsAdapter/MatDateFnsModule日期類型Date依賴 date-fnsprovideLuxonDateAdapter/MatLuxonDateModule日期類型DateTime依賴 LuxonprovideMomentDateAdapter/MatMomentDateModule日期類型Moment依賴 Moment.js。所有 provider 都同時提供DateAdapter與MAT_DATE_FORMATS。若需自定義解析/顯示格式可覆蓋MAT_DATE_FORMATS或直接把格式對象傳入 provider例如provideNativeDateAdapter(MY_NATIVE_DATE_FORMATS)也可以完全自定義子類化DateAdapter并通過{provide: DateAdapter, useClass: MyDateAdapter}提供。由于DateAdapter是泛型類在ViewChild(MatDatepicker)等場景中應攜帶與所選適配器對應的泛型參數ViewChild(MatDatepicker) datepicker: MatDatepickerDate;無障礙設計與鍵盤交互指南的 Accessibility 一節與 API 報告相互印證MatDatepicker彈出層使用roledialog交互模式內部日歷實現rolegrid模式MatDatepickerInput與MatDatepickerToggle均會設置aria-haspopup屬性對應 API 報告中的getOverlayLabelId()、ariaLabel等成員始終建議啟用確認操作按鈕matDatepickerActions讓輔助技術用戶顯式確認選擇輸入框應通過mat-label、aria-label、aria-labelledby或MatDatepickerIntl提供有意義的標簽并通過mat-hint等方式告知日期格式如 MM/DD/YYYYMatDatepickerToggle與MatDatepicker應同時使用——移動端屏幕閱讀器用戶依賴圖標按鈕打開面板。鍵盤交互方面打開/關閉面板的快捷鍵為AltDown Arrow與Escape月份視圖內支持方向鍵逐日移動、Home/End跳到月初/月末、Page Up/Page Down跨月移動、AltPage Up/Page Down跨年移動、Enter選中當前日期年視圖與多年視圖有對應的同類操作年視圖按 4 個月一行、多年視圖按 4 年一行、每頁 24 項——與yearsPerRow/yearsPerPage常量吻合。常見報錯與排查API 報告與指南共同指向三類高頻錯誤MatDatepicker: No provider found for DateAdapter/MAT_DATE_FORMATS應用缺少日期適配器 provider在 app config 中調用provideNativeDateAdapter()或其它適配器 provider即可解決A MatDatepicker can only be associated with a single input同一個mat-datepicker被多個input通過matDatepicker屬性綁定一個面板只能關聯一個輸入框Attempted to open an MatDatepicker with no associated input面板未關聯任何輸入框需要用模板引用建立綁定input [matDatepicker]picker mat-datepicker #picker/mat-datepicker模塊組織與按需引入MatDatepickerModule的 NgModule 聲明與導出列表在 API 報告中完整可見它內部引入MatButtonModule、OverlayModule來自angular/cdk/overlay、A11yModule、PortalModule聲明并導出了MatCalendar、MatCalendarBody、MatDatepicker、MatDatepickerContent、MatDatepickerInput、MatDatepickerToggle、MatDatepickerToggleIcon、MatMonthView、MatYearView、MatMultiYearView、MatCalendarHeader、MatDateRangeInput、MatStartDate、MatEndDate、MatDateRangePicker、MatDatepickerActions、MatDatepickerCancel、MatDatepickerApply等全部公開組件與指令同時導出BidiModule與CdkScrollableModule供消費者使用。在獨立組件standalone模式下可僅導入用到的組件或MatDatepickerModule整體模塊化應用則在 NgModule 的imports中聲明MatDatepickerModule并在 app config 中同時提供日期適配器。提示完整的 API 報告由 API Extractor 自動生成并受版本金樣golden file機制保護任何公開 API 的增刪改都需要同步更新該報告它是理解模塊「穩定契約」的一手資料。文中所有類型定義、令牌名與組件成員均可對照 goldens/material/datepicker/index.api.md 逐一核實更詳細的用法示例與配置參數請參閱 src/material/datepicker/datepicker.md。【免費下載鏈接】componentsComponent infrastructure and Material Design components for Angular項目地址: https://gitcode.com/GitHub_Trending/co/components創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考