UI组件前端【免费下载链接】react-day-pickerDayPicker is a customizable date picker component for React. Add date pickers, calendars, and date inputs to your web applications.项目地址https://gitcode.com/gh_mirrors/re/react-day-picker点击查看免费下载导读在 React DayPicker 中日历的每一个 HTML 元素——从根容器、月份网格、日期单元到导航按钮与年月下拉框——都可以通过components属性替换为你自己的 React 组件。本文以 DayPicker 文档中的CustomComponents类型定义src/types/shared.ts为核心完整梳理全部 25 个可定制组件的职责与挂载位置并结合源码实现与仓库内真实示例如 CustomDayButton.tsx、CustomCaption.tsx给出可直接落地的自定义方案。读完本文你将能够替换任意内置元素实现自己的设计系统组件、在日期单元中注入额外内容、拦截或改写点击行为同时保持键盘导航与无障碍ARIA语义完整。一、CustomComponents 是什么CustomComponents是 DayPicker 中用于声明可定制组件映射的 TypeScript 类型别名。官方文档对其定义如下The components that can be customized using thecomponentsprop.也就是说凡是出现在CustomComponents中的每一个字段都代表日历中一个真实渲染的 UI 元素你可以在DayPicker上通过components属性传入自己的实现来替换它。在文档版本9.14.0中该类型定义于src/types/shared.ts:45在当前仓库源码中该类型的实际定义位于packages/react-day-picker/src/types/shared.ts其完整形态如下export type CustomComponents { /** Render the chevron icon used in the navigation buttons and dropdowns. */ Chevron: typeof components.Chevron; /** Render the caption label of the month grid. */ CaptionLabel: typeof components.CaptionLabel; /** Render the day cell in the month grid. */ Day: typeof components.Day; /** Render the button containing the day in the day cell. */ DayButton: typeof components.DayButton; /** Render the dropdown element to select years and months. */ Dropdown: typeof components.Dropdown; /** Render the container of the dropdowns. */ DropdownNav: typeof components.DropdownNav; /** Render the footer element announced by screen readers. */ Footer: typeof components.Footer; /** Render the container of the MonthGrid. */ Month: typeof components.Month; /** Render the caption of the month grid. */ MonthCaption: typeof components.MonthCaption; /** Render the grid of days in a month. */ MonthGrid: typeof components.MonthGrid; /** Wrapper of the month grids. */ Months: typeof components.Months; /** Render the navigation element with the next and previous buttons. */ Nav: typeof components.Nav; /** Render the option HTML element in the dropdown. */ Option: typeof components.Option; /** Render the previous month button element in the navigation. */ PreviousMonthButton: typeof components.PreviousMonthButton; /** Render the next month button element in the navigation. */ NextMonthButton: typeof components.NextMonthButton; /** Render the root element of the calendar. */ Root: typeof components.Root; /** Render the select element in the dropdowns. */ Select: typeof components.Select; /** Render the weeks section in the month grid. */ Weeks: typeof components.Weeks; /** Render the week rows. */ Week: typeof components.Week; /** Render the weekday name in the header. */ Weekday: typeof components.Weekday; /** Render the row containing the week days. */ Weekdays: typeof components.Weekdays; /** Render the cell with the number of the week. */ WeekNumber: typeof components.WeekNumber; /** Render the header of the week number column. */ WeekNumberHeader: typeof components.WeekNumberHeader; /** Render the dropdown for selecting months. */ MonthsDropdown: typeof components.MonthsDropdown; /** Render the dropdown for selecting years. */ YearsDropdown: typeof components.YearsDropdown; };类型推导机制typeof components.X注意类型定义中每个字段的写法typeof components.Chevron、typeof components.DayButton……这里的components并不是组件实例而是从../components/custom-components.js导入的模块命名空间。该模块文件集中导出了全部 25 个默认组件见 custom-components.tsxexport * from ./CaptionLabel.js; export * from ./Chevron.js; export * from ./Day.js; export * from ./DayButton.js; // ……共 25 个组件typeof components.X表示取该模块中导出组件X的类型因此你的自定义组件只要签名的参数与返回值兼容内置组件就能通过类型检查。这种方式既保证了自定义组件的 props 与内置组件完全一致又无需手动维护一份庞大的 props 类型清单——所有 props 类型均由默认组件自动推导并与 functions 文档中导出的XxxProps如DayButtonProps、DropdownProps、RootProps一一对应。二、components属性Partial 映射与合并逻辑components是DayPickerProps上的一个可选属性在源码 props.ts:281 中定义/** * Change the components used for rendering the calendar elements. * * see https://daypicker.dev/guides/custom-components */ components?: PartialCustomComponents;两个关键点PartialCustomComponents类型被标记为部分可选意味着你不需要一次性替换全部 25 个组件只需传入想要覆盖的条目。例如components{{ Day: CustomDaycell }}或components{{ DayButton: DayButtonWithContext }}都合法。与默认组件合并在DayPicker.tsx中components会从 props 解构取出并参与渲染上下文的组装见同文件第 150 行、第 395 行附近未覆盖的组件会继续使用默认实现。因此你可以放心地只覆盖局部元素其余部分保持原样。这种默认实现 局部覆盖的设计让自定义成本降到最低绝大多数场景下你只需要写一个函数组件并传入components即可无需复制整个日历结构。三、25 个可定制组件全景图依据文档的 Properties 章节将全部组件按职责分组整理如下。每一组都对应日历中一个真实的 DOM 层级理解了分组也就理解了整个日历的组件树。1. 容器与结构组件组件文档描述挂载位置/职责RootRender the root element of the calendar.日历最外层根元素当启用animate时需转发rootRefMonthsWrapper of the month grids.多个月份网格的外层包装器MonthRender the container of the MonthGrid.单个月份容器接收calendarMonth与displayIndexMonthGridRender the grid of days in a month.月份内天数的网格主体MonthCaptionRender the caption of the month grid.月份标题caption区域CaptionLabelRender the caption label of the month grid.caption 中的文字标签部分FooterRender the footer element announced by screen readers.页脚作为屏幕阅读器播报的 live region2. 导航组件组件文档描述挂载位置/职责NavRender the navigation element with the next and previous buttons.包含上/下月按钮的导航工具栏NextMonthButtonRender the next month button element in the navigation.下一个月按钮PreviousMonthButtonRender the previous month button element in the navigation.上一个月按钮ChevronRender the chevron icon used in the navigation buttons and dropdowns.导航按钮与下拉框中的箭头图标从 Nav.tsx 源码可见Nav内部正是组合了components.PreviousMonthButton、components.NextMonthButton与components.Chevron三个可替换子组件并注入tabIndex、aria-disabled、aria-label由labelPrevious/labelNext生成与点击处理。也就是说自定义Nav或只自定义按钮/箭头都可以精细化控制导航交互。3. 日期单元组件组件文档描述挂载位置/职责DayRender the day cell in the month grid.日期单元格对应td结构DayButtonRender the button containing the day in the day cell.单元格内的日期按钮承担焦点管理与点击交互这是自定义最常用的两个组件。从 DayButton.tsx 源码看内置DayButton接收day: CalendarDay与modifiers: Modifiers两个专有 props其余为ButtonHTMLAttributes并在modifiers.focused为真时自动将焦点交给按钮export function DayButton( props: { day: CalendarDay; modifiers: Modifiers } ButtonHTMLAttributesHTMLButtonElement, ) { const { day, modifiers, ...buttonProps } props; const ref React.useRefHTMLButtonElement(null); React.useEffect(() { if (modifiers.focused) ref.current?.focus(); }, [modifiers.focused]); return button ref{ref} {...buttonProps} /; }因此官方指南特别提醒自定义DayButton时不要重建焦点管理逻辑推荐包装默认组件见下文实战示例。4. 下拉框组件月份/年份选择组件文档描述挂载位置/职责DropdownRender the dropdown element to select years and months.选择年月用的下拉框容器DropdownNavRender the container of the dropdowns.下拉框集合的容器MonthsDropdownRender the dropdown for selecting months.月份下拉框YearsDropdownRender the dropdown for selecting years.年份下拉框SelectRender the select element in the dropdowns.下拉框内部的select元素OptionRender theoptionHTML element in the dropdown.下拉框中的option元素从 Dropdown.tsx 源码可见内置Dropdown的组合方式外层span包裹components.Select与components.Option列表并附带一个由components.Chevron渲染的向下箭头和选中项标签。当captionLayoutdropdown时月份/年份下拉框才会被渲染。5. 星期与周数组件组件文档描述挂载位置/职责WeekdaysRender the row containing the week days.星期名称所在的行WeekdayRender the weekday name in the header.表头中的星期名称单元格WeeksRender the weeks section in the month grid.月份网格中的周区块WeekRender the week rows.一周的行容器WeekNumberRender the cell with the number of the week.周数列中的单元格WeekNumberHeaderRender the header of the week number column.周数列的列头4. 一个已废弃的字段Button文档明确标注Button字段为Deprecated自 9.x 版本起弃用不再作为推荐接口Button:typeofcomponents.Button— Render any button element in DayPicker. Deprecated: Use NextMonthButton or PreviousMonthButton instead.在当前源码的CustomComponents中Button字段已被移除代之以语义更精确的NextMonthButton/PreviousMonthButton。如果你的代码仍在使用components.Button请迁移到这两个新字段。四、实战自定义组件的基本套路与设计约束官方指南 custom-components.mdx 给出了自定义组件的三种典型动机与对应的实现原则拦截默认事件如阻止默认点击行为、添加触摸事件等注入额外内容如在日期单元中展示日程条目、加 tooltip接入设计系统用自家 Button、Select、Dropdown 替换内置元素或用自定义组件包装某个元素。保持无障碍与内置行为完整自定义组件时以下三条约束必须遵守否则会破坏键盘导航与屏幕阅读器支持始终透传收到的 props包括aria-*、tabIndex、ref和事件处理器确保 DayPicker 的焦点管理与 ARIA 语义继续生效复用useDayPicker中的classNames与labels渲染内置元素时使用来自 DayPicker 上下文的 class 与标签文本使 modifier 样式和 ARIA 文案保持一致优先组合默认组件不要重建DayButton中的焦点管理这类内建行为而是包装默认组件叠加你的 UI。组件 props 速查表组件Props 类型注意事项DayDayProps接收day含date与modifiersDayButtonDayButtonProps内部处理焦点务必继续转发ref/aria-*NavNavProps使用其提供的onPreviousClick/onNextClickDropdownDropdownProps转发aria-label并以target调用onChangeRootRootProps启用animate时必须转发rootRef示例一用 Context 改写点击行为双击选中来自 examples/CustomDayButton.tsx 的完整示例通过自定义 React Context 在自定义DayButton与主组件之间共享选中状态实现双击选中、单击取消import { DayButton, type DayButtonProps, DayPicker } from daypicker/react; const SelectedDateContext React.createContext{ selected?: Date; setSelected?: React.DispatchReact.SetStateActionDate | undefined; }({}); function DayButtonWithContext(props: DayButtonProps) { const { day, modifiers, ...buttonProps } props; const { setSelected } React.use(SelectedDateContext); return ( DayButton {...buttonProps} day{day} modifiers{modifiers} onClick{() setSelected?.(undefined)} onDoubleClick{() setSelected?.(day.date)} / ); } export function CustomDayButton() { const [selected, setSelected] React.useStateDate(); return ( SelectedDateContext.Provider value{{ selected, setSelected }} DayPicker modesingle selected{selected} onSelect{setSelected} components{{ DayButton: DayButtonWithContext }} / /SelectedDateContext.Provider ); }注意这里并没有重写DayButton的渲染逻辑而是包装默认组件并只叠加两个点击处理器——{...buttonProps}保留了aria-*、tabIndex、ref 与键盘事件内置的焦点管理依旧生效。示例二组合默认组件并注入额外 UI当你想添加视觉内容但保留内置行为焦点、标签、modifier 类名时从useDayPicker()上下文取出classNames再用默认组件包装import { DayButton, type DayButtonProps, DayPicker, UI, useDayPicker } from daypicker/react; function WrappedDayButton(props: DayButtonProps) { const { classNames } useDayPicker(); return ( DayButton {...props} className{${classNames[UI.DayButton]} my-custom-class} span{props.day.date.getDate()}/span small aria-hidden★/small /DayButton ); } export function WrappedDayExample() { return DayPicker components{{ DayButton: WrappedDayButton }} /; }这里UI.DayButton是 DayPicker 内部 UI 标识符定义于 UI.ts用于在ClassNames映射中取出默认类名从而保证自定义类名与内置 modifier 样式共存。示例三自定义月份标题并接管导航CustomCaption仓库示例 examples/CustomCaption.tsx 展示了完全替换MonthCaption的用法借助useDayPicker()返回的goToMonth、nextMonth、previousMonth在标题中自行渲染上一月/下一月按钮并配合hideNavigation隐藏内置导航import { DayPicker, type MonthCaptionProps, useDayPicker } from daypicker/react; function CustomMonthCaption(props: MonthCaptionProps) { const { goToMonth, nextMonth, previousMonth } useDayPicker(); return ( h2{format(props.calendarMonth.date, MMM yyy)}/h2 div style{{ display: flex, justifyContent: space-between }} button typebutton disabled{!previousMonth} onClick{() previousMonth goToMonth(previousMonth)} Previous /button button typebutton disabled{!nextMonth} onClick{() nextMonth goToMonth(nextMonth)} Next /button /div / ); } export function CustomCaption() { return ( DayPicker hideNavigation components{{ MonthCaption: CustomMonthCaption }} / ); }useDayPicker返回的上下文详见文档 custom-components.mdx 中的 DayPicker Context 表格还包含classNames、components、formatters、labels、getModifiers、isSelected、selected、select、goToMonth、months、nextMonth、previousMonth、styles、dayPickerProps等字段是自定义组件之间共享日历状态的主通道。示例四用 shadcn/ui Select 替换内置下拉框官方指南还给出了用shadcn/ui风格Select替换内置Dropdown的完整模式见 examples/CustomDropdown/CustomDropdown.tsx核心在于把 shadcn 的onValueChange(value: string)桥接回 DayPicker 期望的onChange(React.ChangeEventHTMLSelectElement)export function CustomSelectDropdown(props: DropdownProps) { const { options, value, onChange, aria-label: ariaLabel } props; const handleValueChange (newValue: string) { if (onChange) { const syntheticEvent { target: { value: newValue }, } as React.ChangeEventHTMLSelectElement; onChange(syntheticEvent); } }; return ( Select value{value?.toString()} onValueChange{handleValueChange} SelectTrigger aria-label{ariaLabel} SelectValue / /SelectTrigger SelectContent SelectGroup {options?.map((option) ( SelectItem key{option.value} value{option.value.toString()} disabled{option.disabled} {option.label} /SelectItem ))} /SelectGroup /SelectContent /Select ); } // 使用DayPicker captionLayoutdropdown components{{ Dropdown: CustomSelectDropdown }} /需要配合captionLayoutdropdown启用年月下拉布局若你的设计系统以下拉浮层portal渲染选项列表请确保浮层容器正确挂载在日历内部文档中特别提示参考examples/CustomDropdown/CustomDropdown.tsx的容器写法。示例五结构性定制Root 包装为卡片import { DayPicker, type RootProps } from daypicker/react; function CardRoot(props: RootProps) { const { rootRef, ...rest } props; return ( div ref{rootRef} classNamecard shadow-md {...rest} {rest.children} /div ); } export function CustomRootExample() { return DayPicker components{{ Root: CardRoot }} /; }注意Root的源码Root.tsx中rootRef是独立于HTMLAttributes的专有 props——它用于animate动画场景下的根元素 ref。自定义Root时必须像上面这样把rootRef转发到你真正渲染的容器元素上否则启用animate时动画会失效。五、选择决策Day vs DayButton vs Formatters官方指南对三者的分工做了清晰界定这也是避免过度自定义的关键DayButton用于改变交互行为或在按钮内部追加内容保持单元格布局不变Day用于改造表格单元格结构如td外层包装、tooltip、wrapper当你需要控制单元格本身时使用Formatters格式化器只改文字内容如标签文本不改结构。详见仓库文档 translation 自定义格式化器。一句话总结简单的文字变化用 Formatters内容与交互变化用DayButton结构性变化用Day或布局类组件Root、Months、Month、MonthGrid、Weeks、Week、Weekdays、Weekday。此外CustomComponents与Formatters是两套独立的扩展点formatters 修改的是内容custom components 修改的是HTML 结构官方指南的 note 专门强调了这一点。需要细化日期显示时两者可以组合使用。六、源码验证与延伸阅读类型定义packages/react-day-picker/src/types/shared.tsCustomComponents与同文件Formatters、Labels、ClassNames、Styles等配套类型默认组件实现全部 25 个组件源码位于 packages/react-day-picker/src/components/统一由 custom-components.tsx 导出components属性的声明与注释packages/react-day-picker/src/types/props.ts其类型为PartialCustomComponents并在 DayPicker.tsx 中与默认组件合并完整使用指南apps/website/docs/guides/custom-components.mdx包含本文所有示例的上下文、useDayPicker上下文字段表与组件 props 速查表可运行示例examples/CustomDayButton.tsx、examples/CustomCaption.tsx、examples/CustomDropdown/CustomDropdown.tsxdocs 站与 Playground 均基于这些示例渲染配套测试examples/CustomDayButton.test.tsx 验证了双击选中、单击取消的交互逻辑examples/CustomDropdown/CustomDropdown.test.tsx 验证了替换下拉框后月份/年份选择依然可用。结语CustomComponents是 DayPicker 组件化架构的对外契约Partial化让局部替换零成本typeof components.X让自定义组件的类型签名永远与内置组件对齐25 个命名清晰的字段则完整映射了日历的组件树。遵循透传 props、复用上下文 classNames/labels、包装默认组件三条原则你就能在保留无障碍与键盘行为的前提下将日历无缝融入自己的设计系统。赞分享UI组件前端【免费下载链接】react-day-pickerDayPicker is a customizable date picker component for React. Add date pickers, calendars, and date inputs to your web applications.项目地址https://gitcode.com/gh_mirrors/re/react-day-picker点击查看免费下载相关推荐react-day-picker v8 自定义组件完全指南CustomComponents 接口与 components 属性实战react day picker v8 自定义组件完全指南CustomComponents 接口与 components 属性实战 本文基于 react daUI组件前端React DayPicker 组件 Props 完全指南DayPickerProps 类型定义与全配置项深度解析React DayPicker 组件 Props 完全指南DayPickerProps 类型定义与全配置项深度解析 DayPickerProps 是 reacUI组件前端深入解析 React DayPicker 的 Footer 组件从 footer 属性到自定义渲染深入解析 React DayPicker 的 Footer 组件从 footer 属性到自定义渲染 导读 本文基于 React DayPicker v8.10UI组件前端上一篇九大网盘直链解析神器免费解锁全平台高速下载下一篇如何高效获取网盘直链九大平台一站式智能下载解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考