UI组件前端【免费下载链接】ant-design-blazorA rich set of enterprise-class UI components based on Ant Design and Blazor.项目地址https://gitcode.com/gh_mirrors/an/ant-design-blazor点击查看免费下载导读本文围绕 ant-design-blazor 仓库中的 Calendar 组件文档 展开系统讲解日历组件的适用场景、全部 API 参数、事件回调与国际化注意事项并结合仓库源码与官方示例深入剖析dateCellRender、monthCellRender、headerRender等高级自定义能力的实现原理。读完本文你将掌握如何用Calendar组件快速搭建日程、课表、价格日历等按日期划分的数据展示容器并能按需定制日期单元格内容、切换年/月面板甚至完全重写日历头部。何时使用 Calendar 组件Calendar是按照日历形式展示数据的容器。当业务数据本身是日期、或者天然按照日期划分时就适合使用它典型场景包括日程/事件列表每天展示若干条提醒或事件课表按日期维度呈现课程安排价格日历在日期格内展示当天价格农历等历法信息在日期格内追加农历等附加数据。组件目前支持年/月两种面板模式切换配合自定义渲染函数即可在单元格内叠加任意内容。组件类定义位于 components/calendar/Calendar.razor.cs其文档注释与官方文档保持一致Container for displaying data in calendar form.。基本用法一个开箱即用的日历面板最简单的用法是直接声明Calendar /即可得到一个支持年/月切换的通用日历面板。官方示例 Basic.razor 展示了绑定面板切换事件的基本写法Calendar OnPanelChangeOnPanelChange / code { private void OnPanelChange(DateTime value, DatePickerType type) { Console.WriteLine(${value.ToString(yyyy-MM-dd)} {type}); } }OnPanelChange在用户切换年/月视图即面板变化时触发回调参数为当前面板代表日期DateTime与面板类型DatePickerType。注意DatePickerType定义在 components/date-picker/types 目录中它同时被日期选择器与日历组件共用用于标识日期粒度如Date、Month。API 参数全解以下参数表完整继承自官方文档 index.zh-CN.md并结合源码实现逐项补充了默认值与行为细节参数说明类型默认值dateCellRender自定义渲染日期单元格返回内容会被追加到单元格FuncDateTime, RenderFragment无dateFullCellRender自定义渲染日期单元格返回内容覆盖单元格FuncDateTime, RenderFragment无defaultValue默认展示的日期DateTime默认日期disabledDate不可选择的日期FuncDateTime, bool无fullscreen是否全屏显示booltruelocale国际化配置TODODatePickerLocale全局 Locale 的 DatePicker 配置mode初始模式CalendarMode.Month/CalendarMode.YearCalendarModeCalendarMode.MonthmonthCellRender自定义渲染月单元格返回内容会被追加到单元格FuncDateTime, RenderFragment无monthFullCellRender自定义渲染月单元格返回内容覆盖单元格FuncDateTime, RenderFragment无validRange设置可以显示的日期范围DateTime[]两个元素无value展示日期DateTime当前日期onPanelChange日期面板变化回调ActionDateTime, DatePickerType无onSelect点击选择日期回调已标记 Obsolete建议改用 onChangeEventCallbackDateTime无onChange日期变化回调EventCallbackDateTime无headerRender自定义头部内容FuncCalendarHeaderRenderArgs, RenderFragment无value 与 defaultValue源码中 Value 参数 默认值为DateTime.Now表示当前展示的日期DefaultValue 参数 的 setter 在赋值时会同步覆盖Value因此二者是联动关系——设置DefaultValue等价于同时设置了初始展示日期public DateTime DefaultValue { get _defaultValue; set { _defaultValue value; Value _defaultValue; // 同步写入 Value } }fullscreen 全屏与卡片模式FullScreen默认true即日历占据父容器全部可用宽度。当它设置为false时日历会以紧凑卡片形态呈现适合嵌套在空间有限的容器中如侧边栏面板。对应 CSS 类映射在 SetClass 方法 中FullScreen true时追加ant-picker-calendar-full类false时不追加。官方示例 Card_.razor 展示了卡片模式将日历放入一个 300px 宽的带边框容器中div classsite-calendar-demo-card Calendar FullScreenfalse OnPanelChangeOnPanelChange / /divdisabledDate 禁用日期disabledDate接收一个FuncDateTime, bool委托返回true的日期将不可选择。该参数在 Calendar.razor.cs 中声明默认值为null即全部日期可选可直接在 Razor 中传入 LambdaCalendar DisabledDatedate date.DayOfWeek DayOfWeek.Sunday /validRange 可显示范围validRange为DateTime[]两个元素的数组分别表示起止日期用于限定日历中可显示的日期区间。值得注意的源码细节在 OnInitialized 方法 中初始化时会检查当前Value是否越界——若Value小于范围下界则钳制到下界大于上界则钳制到上界确保初始展示日期始终落在合法范围内if (ValidRange ! null) { if (Value ValidRange[0]) { Value ValidRange[0]; } else if (Value ValidRange[1]) { Value ValidRange[1]; } }mode 初始模式mode决定日历初始展示的是月份面板CalendarMode.Month即逐日视图还是年份面板CalendarMode.Year即逐月视图默认CalendarMode.Month。枚举定义见 CalendarMode.cs。源码中 Mode 会被映射为日期选择器的面板粒度Month → DatePickerType.Date、Year → DatePickerType.Month见 OnInitialized并由内部组件 CalendarPanelChooser 负责实际渲染对应粒度的面板。locale 国际化与 moment locale 前置条件官方文档特别提醒Calendar 部分 locale 是从 value日期值中读取的因此请先正确设置 moment 的 locale。默认语言为en-US若需使用其他语言推荐在应用入口文件全局设置 locale例如// import moment from moment; // import moment/locale/zh-cn; // moment.locale(zh-cn);在源码层面Locale 参数 的类型为DatePickerLocale其默认值取自全局LocaleProvider.CurrentLocale.DatePicker同时组件还暴露了 CultureInfo 参数默认取LocaleProvider.CurrentLocale.CurrentCulture用于日期格式化——例如 GetFormatValue 方法 即以该 CultureInfo 格式化日期字符串。因此要获得正确的中文月名、周起始日等展示效果需要在初始化时同步配置 moment locale 与项目的 LocaleProvider。仓库各语言资源位于 components/locales如 zh-CN.json可供参考。事件回调机制onSelect、onChange 与 onPanelChange组件内部点击日期时统一走 OnSelectValue 方法其调用链清晰揭示了三个事件的关系protected void OnSelectValue(DateTime date) { Value date; // 1. 更新当前值 OnSelect.InvokeAsync(date); // 2. 触发 onSelect OnChange.InvokeAsync(date); // 3. 触发 onChange StateHasChanged(); }onSelect点击选择日期时触发。源码中该参数已标注[Obsolete(Use OnChange instead)]Calendar.razor.cs官方建议新代码改用onChangeonChange日期变化时触发点击选择同样会触发是当前推荐的选择回调onPanelChange仅当用户在年月面板之间切换时触发见下方 ChangeMode。ChangeMode面板切换的底层实现当用户点击头部切换视图时ChangeMode 方法 会完成模式更新、记录前一个面板类型_prePickerStack用于回退并触发OnPanelChange回调internal void ChangeMode(CalendarMode mode) { Mode mode; DatePickerType picker Mode switch { CalendarMode.Month DatePickerType.Date, CalendarMode.Year DatePickerType.Month, _ DatePickerType.Date }; _prePickerStack.Push(_picker); _picker picker; OnPanelChange?.Invoke(PickerValues[0], _picker); StateHasChanged(); }自定义日期/月份单元格dateCellRender 与 monthCellRender日历组件最核心的扩展点就是四个单元格渲染函数。理解追加与覆盖的区别至关重要dateCellRender/monthCellRender返回的RenderFragment会被追加到单元格默认内容之后dateFullCellRender/monthFullCellRender返回内容会整体覆盖单元格包括默认的日期数字。两者均接收DateTime参数代表当前要渲染的日期/月份。官方示例 NoticeCalendar.razor 是经典的事件日历实现按日期维护一份事件列表用dateCellRender在日期格内追加 Badge 事件条目用monthCellRender在月份格内追加Backlog number统计数字Calendar DateCellRenderDateCellRender MonthCellRenderMonthCellRender / code { private RenderFragment DateCellRender(DateTime value) { var listData GetListData(value); // 按 value.Day 返回当天事件列表 return Template ul classevents foreach (var data in listData) { li keydata.content Badge Statusdata.type Textdata.content / /li } /ul /Template; } private RenderFragment MonthCellRender(DateTime value) { int? num GetMonthData(value); // 如 8 月返回 1394 if (num null) return null; return Template div classNamenotes-month sectionnum/section spanBacklog number/span /div /Template; } }该示例同时展示了组件与 Badge 的组合用法将BadgeStatusWarning/Success/Error映射为徽标状态在日期格内呈现事件语义。参考样式.events与.notes-month位于同一示例文件末尾的Style块中用于控制事件列表的溢出省略与月份统计的居中排版。自定义头部headerRenderheaderRender允许完全替换日历顶部的年月切换区域其参数类型为CalendarHeaderRenderArgs定义见 CalendarHeaderRenderCallback.cs包含四个成员成员类型说明ValueDateTime当前面板代表日期TypeCalendarMode当前模式Month / YearOnChangeActionDateTime变更日期的回调切换年/月后调用OnTypeChangeActionCalendarMode变更模式回调切换 Month/Year 面板组件模板逻辑见 Calendar.razor当HeaderRender不为 null 时直接调用自定义头部否则渲染内置的CalendarHeader组件。官方示例 CustomizeHeader.razor 实现了一个标题 RadioGroup 模式切换 年份下拉 月份下拉的完全自定义头部其中调用args.OnTypeChange与args.OnChange驱动组件内部状态的关键代码如下Calendar FullScreenfalse HeaderRenderHeaderRender OnPanelChangeOnPanelChange / code { private RenderFragment HeaderRender(CalendarHeaderRenderArgs args) { int month args.Value.Month; int year args.Value.Year; return Template div stylepadding: 8px Title Level4Custom header/Title Row Gutter8 AntDesign.Col RadioGroup SizeInputSize.Small OnChangevalue args.OnTypeChange(value) Valueargs.Type TValueCalendarMode Radio RadioButton ValueCalendarMode.MonthMonth/Radio Radio RadioButton ValueCalendarMode.YearYear/Radio /RadioGroup /AntDesign.Col AntDesign.Col select onchangee OnSelectYear(e, args) valueyear GetYearOptions(year) /select /AntDesign.Col AntDesign.Col select onchangee OnSelectMonth(e, args) valuemonth GetMonthOptions() /select /AntDesign.Col /Row /div /Template; } private void OnSelectYear(ChangeEventArgs args, CalendarHeaderRenderArgs renderArgs) { int year Convert.ToInt32(args.Value); renderArgs.OnChange(DateHelper.CombineNewDate(renderArgs.Value, year: year)); } private void OnSelectMonth(ChangeEventArgs args, CalendarHeaderRenderArgs renderArgs) { int month Convert.ToInt32(args.Value); renderArgs.OnChange(DateHelper.CombineNewDate(renderArgs.Value, month: month)); } }注意示例中通过DateHelper.CombineNewDate工具类定义于 components/core/Helpers在保留原日期其他字段的基础上合成新日期再传给OnChange从而驱动面板日期更新。头部内的OnTypeChange会最终路由到源码中的ChangeMode触发OnPanelChange回调。源码级原理小结将文档 API 与源码 Calendar.razor.cs 对照可以归纳出组件设计的几个关键机制面板粒度映射CalendarMode.Month/Year与DatePickerType.Date/Month一一对应组件复用日期选择器的面板渲染体系内部使用CalendarPanelChooser见 Calendar.razor值联动DefaultValue的 setter 同步写入ValueValidRange在初始化时对Value做越界钳制回调分层点击日期统一经过OnSelectValue同时触发OnSelect已废弃与OnChange面板切换单独走ChangeMode并触发OnPanelChange且用_prePickerStack栈记录面板切换历史以支持回退渲染扩展点头部可由HeaderRender完全接管CalendarHeaderRenderArgs提供值、模式与两个驱动回调单元格则由追加式dateCellRender/monthCellRender与覆盖式dateFullCellRender/monthFullCellRender两类委托提供两级自定义能力国际化依赖locale 从日期值与全局LocaleProvider.CurrentLocale读取使用前需正确配置 moment locale默认 en-US。实战建议日程/事件日历优先使用dateCellRender Badge 组合事件数据按日期分组后在单元格内追加展示价格日历/课表若需要完全掌控单元格内容隐藏默认日期数字使用dateFullCellRender/monthFullCellRender覆盖式渲染嵌入窄容器设置FullScreenfalse并配合自定义容器宽度参考 Card_.razor 的 300px 卡片写法品牌化头部通过headerRender重写年月切换器可在其中混合使用 RadioGroup、Select 等组件与原生select注意 API 演进onSelect已标记[Obsolete]新代码应统一使用onChange响应日期选择。赞分享UI组件前端【免费下载链接】ant-design-blazorA rich set of enterprise-class UI components based on Ant Design and Blazor.项目地址https://gitcode.com/gh_mirrors/an/ant-design-blazor点击查看免费下载相关推荐Ant Design Blazor Calendar 日历组件完整指南API 参数、单元格自定义与面板切换原理Ant Design Blazor Calendar 日历组件完整指南API 参数、单元格自定义与面板切换原理 导读 本文围绕 Ant Design Blaz前端UI组件设计系统Ant Design Blazor Calendar 日历组件完整实战指南API、自定义渲染与本地化Ant Design Blazor Calendar 日历组件完整实战指南API、自定义渲染与本地化 本文围绕 Ant Design Blazor 官方文档UI组件前端Ant Design Calendar 日历组件深度指南完整 API、源码实现与自定义渲染实战Ant Design Calendar 日历组件深度指南完整 API、源码实现与自定义渲染实战 本文围绕 Ant Design 的 Calendar 日历组件前端UI组件设计系统上一篇智能姿态标注实战指南开源工具的高效应用与性能优化下一篇CHOC跨平台开发终极指南Windows、macOS、Linux统一接口设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考