- UI组件
- 前端
【免费下载链接】react-day-picker
DayPicker is a customizable date picker component for React. Add date pickers, calendars, and date inputs to your web applications.
DayPickerContext 是 react-day-picker 内部用于共享 props 的 React Context：它接收<DayPicker>传入的 props，为整个组件树（包括内置组件与你自定义的组件）提供统一的默认值、样式/标签/格式化配置以及渲染日历所需的一次性计算结果。本文以版本 8.10.2 的官方 API 文档为骨架，结合当前仓库源码与测试，完整梳理该 Context 的创建、注入、消费与全部上下文值，帮助你在自定义组件中安全地读取 DayPicker 状态并扩展日历功能。
DayPickerContext 是什么：一个承载所有 DayPicker props 的 React Context
在 react-day-picker 中，<DayPicker>组件需要把它的 props 与内部计算出的渲染数据"广播"给整棵组件树。官方文档对DayPickerContext的定义如下：
constDayPickerContext:Context<undefined|DayPickerContextValue>
即：这是一个类型为Context<undefined | DayPickerContextValue>的常量 Context。它把传给 DayPicker 的 props 在内置组件与自定义组件之间共享，用于设置默认值以及执行渲染日期所需的一次性计算（one-time calculations）。对文档中"set the default values"的佐证，见下方接口文档中大量带Overrides与Default Value标记的字段——它们正是"props 经过清洗与补默认值后"的最终形态。
从当前仓库源码看，这一设计在 v9 中同样延续：packages/react-day-picker/src/useDayPicker.ts中定义了dayPickerContext = createContext<DayPickerContext<T> | undefined>(undefined)，packages/react-day-picker/src/DayPicker.tsx则通过<dayPickerContext.Provider value={contextValue}>将计算好的上下文注入组件树。文档中明确说明，开发者应通过 useDayPicker 这个 hook 访问该 Context，而不是直接useContext(DayPickerContext)。
核心 API 三件套：Context、Provider 与 useDayPicker hook
围绕DayPickerContext常量，v8.10.2 文档还定义了另外两个配套 API，共同构成完整的"提供-消费"链路：
| API | 签名 | 职责 |
|---|---|---|
DayPickerProvider | DayPickerProvider(props): JSX.Element | Context 的 Provider 组件，负责从初始 props 中分配默认值（assigning the defaults from the initial DayPicker props） |
DayPickerProviderProps | { initialProps: DayPickerProps; children?: ReactNode } | Provider 的入参：initialProps为 DayPicker 组件传入的原始 props |
useDayPicker() | useDayPicker(): DayPickerContextValue | Hook，供内置与自定义组件读取 Context 值 |
DayPickerProviderProps只有两个字段：必需的initialProps（The initial props from the DayPicker component）与可选的children。也就是说，Provider 拿到的是"清洗前"的原始 props，而消费方拿到的是"清洗后"的DayPickerContextValue。
从仓库当前（v9）实现可以印证同一模式的底层细节：useDayPicker在useContext(dayPickerContext)返回undefined时会抛出Error("useDayPicker() must be used within a custom component.")，防止在 Provider 之外误用；其测试packages/react-day-picker/src/useDayPicker.test.tsx通过renderHook+ 手工构造的dayPickerContext.Provider包装器验证了 Context 值可被正确读取，并断言months[0].date、nextMonth、previousMonth、selected等值原样保持为Date实例、goToMonth/isSelected等回调被正确调用。v9 中 Context 值还扩展出goToMonth、getModifiers、select、isSelected等操作型成员，以及自 9.3.0 起加入的dayPickerProps原始 props 引用，功能比 v8 的"纯配置快照"更丰富。
DayPickerContextValue：继承 DayPickerBase 的清洗后 props 快照
useDayPicker()返回的DayPickerContextValue是DayPickerContext的实际值类型。它Extends自DayPickerBase——所有 DayPicker 的基础 props 接口——"extends the props from DayPicker with default and cleaned up values"，即：继承全部基础 props，并把其中的可选项补上默认值、整理成确定的配置。
理解DayPickerContextValue的关键，是分清它的三类成员：
- 普通继承字段（Inherited from DayPickerBase）：与用户传入的 props 一一对应，通常可选、保持原值；
- 覆写字段（Overrides）：从
DayPickerBase继承但在 Context 构建时被重新赋值/补默认值，变为必选； - Context 专属字段：只在
DayPickerContextValue中出现，是"一次性计算"的产物。
文档中DayPickerContextValue的所有"Overrides"字段均指向同一处源码位置：src/contexts/DayPicker/DayPickerContext.tsx，说明这些默认值的清洗逻辑全部集中在该文件中完成。
Context 专属的计算字段
| 字段 | 类型 | 说明 |
|---|---|---|
mode | DaySelectionMode | 选中模式，single/multiple/range之一，必选 |
onSelect | 三种 Select 事件 handler 的联合 | 随模式而定的选择回调，必选 |
required | boolean（可选） | 选择是否必填（即是否允许清空选择） |
min/max | number（可选） | 选择数量的最小/最大值，配合 multiple/range 模式使用 |
selected | Matcher \| Matcher[]（可选，Overrides） | 被应用selected修饰符的日期 |
Overrides 字段：Context 补上的默认值
| 字段 | 类型 | 默认值 | 作用 |
|---|---|---|---|
captionLayout | CaptionLayout | buttons | 标题布局：buttons（上一月/下一月按钮）或dropdown（月份/年份下拉）；dropdown仅在设置了fromDate/fromMonth/fromYear与toDate/toMonth/toYear时可用 |
classNames | Required<Partial<StyledElement<string>>> | — | 各 HTML 元素的类名，改类名而非新增时使用（CSS Modules 场景常用） |
formatters | Formatters | — | 覆盖默认的日期格式化函数（标题、日期、周数、星期名等） |
labels | Labels | — | 覆盖默认的 ARIA label 生成函数，用于无障碍定制 |
locale | Locale | en-US | date-fns 的 locale 对象，用于本地化日期 |
modifiers | DayModifiers | — | 为匹配的日期添加修饰符 |
modifiersClassNames | ModifiersClassNames | — | 修改匹配修饰符日期的类名 |
numberOfMonths | number | 1 | 一次展示的月份数量 |
styles | Partial<Omit<StyledElement<CSSProperties>, InternalModifiersElement>> | — | 各 HTML 元素的行内样式 |
today | Date | 当前日期 | 今天的日期，该日期会获得today修饰符以应用样式 |
注意：
classNames、formatters、labels、locale、modifiers、modifiersClassNames、numberOfMonths、styles、today、captionLayout、selected这些字段在文档中都标记为Overrides（来自DayPickerBase但在DayPickerContext.tsx中被重新赋值），意味着它们是"清洗/补默认值"的落点，读取到的一定是可用状态，而不是原始传入值。
普通继承字段（示例，均来自 DayPickerBase）
| 字段 | 类型 | 默认值 | 作用 |
|---|---|---|---|
className | string（可选） | — | 添加到容器元素的 CSS 类；要改名应使用classNames.root |
style | CSSProperties（可选） | — | 容器元素的行内样式 |
id | string（可选） | 随机生成 | 用于无障碍的唯一 id |
defaultMonth | Date（可选） | 当前月份 | 初始展示月份（受控请用month+onMonthChange） |
month | Date（可选） | — | 受控展示月份，配合onMonthChange编程式切换 |
fromDate/fromMonth/fromYear | Date/Date/number（可选） | — | 月份导航的最早边界 |
toDate/toMonth/toYear | Date/Date/number（可选） | — | 月份导航的最晚边界 |
disableNavigation | boolean | false | 禁用月份间导航 |
pagedNavigation | boolean | false | 分页导航，一次翻numberOfMonths个月 |
reverseMonths | boolean | false | numberOfMonths > 1时倒序渲染月份 |
fixedWeeks | boolean | false | 每月固定显示 6 周（需配合showOutsideDays） |
hideHead | boolean | false | 隐藏显示星期名的表头 |
showOutsideDays | boolean | false | 显示相邻月份落入本月的"外部日期" |
showWeekNumber | boolean | false | 显示周数列（可配合ISOWeek或Formatters定制） |
weekStartsOn | 0-6 | 跟随 locale | 一周起始日索引（0 为周日），覆盖 locale 设置 |
ISOWeek | boolean（可选） | — | 使用 ISO 周日期，设置后忽略weekStartsOn与firstWeekContainsDate |
firstWeekContainsDate | 1|4 | — | 1 月恒在当年第一周的日期：周一(1)或周四(4) |
disabled | Matcher \| Matcher[]（可选） | — | 为匹配日期应用disabled修饰符 |
hidden | Matcher \| Matcher[]（可选） | — | 为匹配日期应用hidden修饰符并从日历中隐藏 |
initialFocus | boolean（可选） | — | 设置选择模式后聚焦第一个选中日或今日，提升无障碍 |
footer | ReactNode（可选） | — | 表格页脚元素内容 |
dir | string | ltr | 文本方向，ltr或rtl |
lang | string（可选） | — | 容器元素的lang语言标签 |
nonce | string（可选） | — | 供 CSP 用于内联style属性的加密 nonce |
title | string（可选） | — | 容器元素的title属性 |
components | CustomComponents（可选） | — | 布局组件映射，用于注入自定义组件 |
onMonthChange | MonthChangeEventHandler（可选） | — | 月份导航时触发 |
onNextClick/onPrevClick | MonthChangeEventHandler（可选） | — | 点击下一月/上一月按钮时触发 |
onWeekNumberClick | WeekNumberClickEventHandler（可选） | — | 点击周数时触发（需showWeekNumbers） |
onDayClick/onDayFocus/onDayBlur | 对应 Day 事件 handler（可选） | — | 日期点击/聚焦/失焦回调 |
onDayMouseEnter/onDayMouseLeave | DayMouseEventHandler（可选） | — | 日期鼠标悬停/移出回调 |
onDayKeyDown/onDayKeyPress/onDayKeyUp | DayKeyboardEventHandler（可选） | — | 日期键盘事件回调 |
onDayPointerEnter/onDayPointerLeave | DayPointerEventHandler（可选） | — | 指针进入/离开日期回调 |
onDayTouchCancel/onDayTouchEnd/onDayTouchMove/onDayTouchStart | DayTouchEventHandler（可选） | — | 触摸事件回调 |
modifiersStyles | ModifiersStyles（可选） | — | 修改匹配修饰符日期的行内样式 |
使用场景：在自定义组件中读取 props 与配置
DayPickerContext的价值主要体现在自定义组件场景。当你通过componentsprop（见 DayPickerBase 中的CustomComponents）替换某个内部组件（如Caption、Day、Footer）时，你的组件会渲染在 Provider 之内，因此可以调用useDayPicker()拿到完整的清洗后 props，而不必在外部层层透传 props：
import { useDayPicker } from "react-day-picker"; function MyFooter() { const { footer, selected } = useDayPicker(); // 读取 DayPicker 传进来的 footer 内容与当前选中日期 return <tfoot>{footer ?? <tr><td>{selected ? "已选择" : "未选择"}</td></tr>}</tfoot>; }在 v8 中，这是"只读快照"式的访问：读取到的classNames、styles、labels、formatters、locale等都已具备默认值，可直接用于渲染；today也已是清洗后的日期对象。而在当前仓库的 v9 实现（packages/react-day-picker/src/useDayPicker.ts）中，Context 还额外暴露了goToMonth(month)（会触发onMonthChange）、getModifiers(day)、select(handler)、isSelected(date)等操作方法，并新增dayPickerProps保留原始 props，功能面更广——文档@since 9.3.0标注了dayPickerProps的引入版本。
编写自定义组件时的安全边界
结合文档与仓库源码，在使用DayPickerContext时有几点值得注意：
- 必须在 Provider 内消费：
useDayPicker脱离 DayPicker 树调用会抛错。仓库源码在useDayPicker.ts中显式throw new Error(...)，测试文件useDayPicker.test.tsx也验证了正常路径下的读取行为。 - 区分"已清洗"与"原始"值：文档中带
Overrides标记的字段（如classNames、formatters、locale）在 Context 中已是补默认值后的形态，不要假设它们与传入 props 完全一致。 - 版本差异：本文 API 文档对应 8.10.2（源码位置
src/contexts/DayPicker/DayPickerContext.tsx）；若升级到 v9/v10，Context 值类型已扩展为包含操作方法的形态（见 useDayPicker.ts 与 DayPicker.tsx），接口细节以对应版本的 API 文档为准。 - 关联 API 链路：
DayPickerContext→DayPickerProvider（注入）→DayPickerProviderProps（原始 props 入口）→useDayPicker（消费），完整链路见 变量文档 与 函数文档。
小结
DayPickerContext是 react-day-picker 数据流的枢纽：DayPickerProvider接收原始 props，在DayPickerContext.tsx中完成默认值注入与一次性计算，生成DayPickerContextValue快照，供内置与自定义组件通过useDayPicker消费。理解它的"继承DayPickerBase+ Overrides 补默认值 + 专属计算字段"三层结构，是写出健壮自定义组件、深入阅读 DayPicker 渲染链路的第一步。想进一步实践，可参考仓库中的自定义组件示例，如 CustomCaption.tsx 与 CustomDayContent.tsx。
- UI组件
- 前端
【免费下载链接】react-day-picker
DayPicker is a customizable date picker component for React. Add date pickers, calendars, and date inputs to your web applications.
相关推荐
react-day-picker 的 DayPickerContext 类型详解：日历上下文的核心属性与自定义组件实战
react day picker 的 DayPickerContext 类型详解：日历上下文的核心属性与自定义组件实战 导读 DayPickerContext<
UI组件前端深入解析 react-day-picker 的 MonthCaptionProps：月份标题组件的 Props 类型与自定义实践
深入解析 react day picker 的 MonthCaptionProps：月份标题组件的 Props 类型与自定义实践 导读 MonthCaption
UI组件前端React-Day-Picker 自定义组件深度指南
React Day Picker 自定义组件深度指南 前言 React Day Picker 是一个功能强大的 React 日期选择器组件库，它提供了丰富的 A
UI组件前端
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
