react-day-picker 的 Formatters 类型详解：全面定制日期显示与本地化文本

react-day-picker 的 Formatters 类型详解：全面定制日期显示与本地化文本

发布时间：2026/10/9 1:57:56
react-day-picker 的 Formatters 类型详解：全面定制日期显示与本地化文本 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点击查看免费下载导读Formatters是 react-day-picker 中用于定制日历界面所有日期相关文本显示的核心类型别名Type Alias。它由 7 个格式化函数组成一张映射表map覆盖了月份标题caption、日期单元格、星期表头、周数、月份/年份下拉框标签等全部文本渲染场景。本文以 v9.14.0 的 Formatters.md 文档为主体结合仓库内源码与示例带你掌握每个 formatter 的签名、默认行为以及如何通过formattersprop 实现自定义格式化。Formatters 是什么从类型定义看Formatters是一个用于渲染本地化内容的格式化函数映射表Represents a map of formatters used to render localized content。它的定义位于 packages/react-day-picker/src/types/shared.ts/** Represents a map of formatters used to render localized content. */ export type Formatters { /** Format the caption of a month grid. */ formatCaption: typeof formatCaption; /** Format the day in the day cell. */ formatDay: typeof formatDay; /** Format the label in the month dropdown. */ formatMonthDropdown: typeof formatMonthDropdown; /** Format the week number. */ formatWeekNumber: typeof formatWeekNumber; /** Format the header of the week number column. */ formatWeekNumberHeader: typeof formatWeekNumberHeader; /** Format the week day name in the header. */ formatWeekdayName: typeof formatWeekdayName; /** Format the label in the year dropdown. */ formatYearDropdown: typeof formatYearDropdown; };每个属性都通过typeof引用../formatters/index.js中导出的同名函数见 packages/react-day-picker/src/formatters/index.ts。这意味着类型与实现严格同步你自定义的 formatter 必须与被覆盖函数的签名完全一致否则 TypeScript 编译期就会报错按需覆盖Formatters的所有属性都是必填的不是可选?但由于 DayPicker 内置了 7 个默认实现你只需在formattersprop 中传入想覆盖的字段其余字段自动回退到默认行为。在DayPickerProps中formatters是可选 prop类型即为PartialFormatters因此传一个就覆盖一个是它的设计意图。七个 formatter 的职责与默认实现Formatters的 7 个成员分别负责日历界面的一个文本区域它们都在 packages/react-day-picker/src/formatters/ 目录下有独立实现文件与配套测试。下面逐一说明。formatCaption格式化月份网格的标题// packages/react-day-picker/src/formatters/formatCaption.ts export function formatCaption( month: Date, options?: DateLibOptions, dateLib?: DateLib, ) { const lib dateLib ?? new DateLib(options); return lib.formatMonthYear(month); }参数month表示月份的日期对象、options?日期库配置如 locale、dateLib?日期库实例未传时内部新建默认行为调用DateLib.formatMonthYear输出随 locale 变化的月 年组合例如英文环境下的November 2022见 formatCaption.ts 的defaultValue注释。formatDay格式化日期单元格中的数字// packages/react-day-picker/src/formatters/formatDay.ts export function formatDay( date: Date, options?: DateLibOptions, dateLib?: DateLib, ) { return (dateLib ?? new DateLib(options)).format(date, d); }默认行为以d令牌格式化日期即不含前导零的天数如1、23如需显示01这样的两位数可自定义为dateLib.format(date, dd)。formatWeekdayName格式化星期表头// packages/react-day-picker/src/formatters/formatWeekdayName.ts export function formatWeekdayName( weekday: Date, options?: DateLibOptions, dateLib?: DateLib, ) { return (dateLib ?? new DateLib(options)).format(weekday, cccccc); }默认行为使用cccccc令牌输出窄格式星期名例如Mo周一、Su周日该输出出现在日历顶部的一周表头行中是界面最显眼的文本之一常用于自定义成一、Mon等短形式。formatWeekNumber格式化周数// packages/react-day-picker/src/formatters/formatWeekNumber.ts export function formatWeekNumber(weekNumber: number, dateLib defaultDateLib) { if (weekNumber 10) { return dateLib.formatNumber(0${weekNumber.toLocaleString()}); } return dateLib.formatNumber(${weekNumber.toLocaleString()}); }参数weekNumber周数数字类型dateLib默认defaultDateLib默认行为个位数周数补前导零如05两位数直接输出如32并经由dateLib.formatNumber适配当前数字系统numeral system。formatWeekNumberHeader格式化周数列的表头// packages/react-day-picker/src/formatters/formatWeekNumberHeader.ts export function formatWeekNumberHeader() { return ; }默认行为返回空字符串见 formatWeekNumberHeader.ts 的defaultValue注释当启用showWeekNumber时周数列顶部需要一个表头单元格默认留空你可以返回#、Wk等自定义文案。注意此函数不接受任何参数签名与其余 6 个不同。formatMonthDropdown格式化月份下拉框的选项标签// packages/react-day-picker/src/formatters/formatMonthDropdown.ts export function formatMonthDropdown( month: Date, dateLib: DateLib defaultDateLib, ): string { return dateLib.format(month, LLLL); }参数month月份日期、dateLib默认defaultDateLib默认行为使用LLLL令牌输出本地化的完整月份名如英文的January。formatYearDropdown格式化年份下拉框的选项标签// packages/react-day-picker/src/formatters/formatYearDropdown.ts export function formatYearDropdown( year: Date, dateLib: DateLib defaultDateLib, ): string { return dateLib.format(year, yyyy); }参数year年份日期、dateLib默认defaultDateLib默认行为使用yyyy令牌输出四位年份如2022。注意formatMonthDropdown与formatYearDropdown均默认使用defaultDateLib而不像formatCaption/formatDay/formatWeekdayName那样接收options并创建新实例。自定义这两个函数时若你的环境未显式传入dateLib请自行处理 locale 或直接使用默认实例。7 个 formatter 一览Formatter负责区域默认输出en-USformatCaption月份网格标题November 2022月 年formatDay日期单元格1、23d令牌formatWeekdayName星期表头Mo、Succcccc令牌formatWeekNumber周数05、32个位补零formatWeekNumberHeader周数列表头空字符串formatMonthDropdown月份下拉框选项JanuaryLLLL令牌formatYearDropdown年份下拉框选项2022yyyy令牌如何使用 formatters prop 自定义Formatters类型不会直接出现在 JSX 中它作为DayPickerProps.formatters的底层类型被消费。在 translation.mdx 中官方给出了最简用法只覆盖formatCaption其余字段保持内置实现。import { format } from date-fns; DayPicker formatters{{ formatCaption: (date, options) format(date, LLLL yyyy, options), }} /;核心要点formatters是部分覆盖语义未传入的 key 自动使用内置实现自定义函数的签名必须与对应内置函数一致参数类型由typeof约束否则编译报错若使用date-fns的format其选项对象与DateLibOptions兼容可直接透传options从而保留 locale 配置。完整覆盖示例仓库示例 examples/Formatters.tsx 演示了同时自定义formatCaption的完整写法——根据月份计算季节并附加 emojiimport { type DateLibOptions, DayPicker } from daypicker/react; import { format } from date-fns; const seasonEmoji: Recordstring, string { winter: ⛄️, spring: , summer: , autumn: , }; const getSeason (month: Date): string { const monthNumber month.getMonth(); if (monthNumber 0 monthNumber 3) return winter; if (monthNumber 3 monthNumber 6) return spring; if (monthNumber 6 monthNumber 9) return summer; else return autumn; }; const formatCaption (month: Date, options: DateLibOptions | undefined) { const season getSeason(month); return ${seasonEmoji[season]} ${format(month, LLLL, { locale: options?.locale })}; }; export function Formatters() { return ( DayPicker startMonth{new Date(2020, 0)} endMonth{new Date(2025, 11)} formatters{{ formatCaption }} / ); }这个示例展示了三个实用技巧直接声明独立函数再传入formatters便于单元测试与复用通过options?.locale把 DayPicker 的 locale 透传给date-fns保证自定义文本与全局本地化一致formatCaption的签名(month, options)恰好匹配内置formatCaption(month, options?, dateLib?)的兼容子集。结合周数与星期名的组合自定义将多个 formatter 组合覆盖同样可行例如同时启用周数、自定义周数表头与窄星期名DayPicker showWeekNumber formatters{{ formatWeekNumberHeader: () Wk, formatWeekdayName: (weekday, options) new DateLib(options).format(weekday, EEEEE), }} /这里formatWeekNumberHeader返回Wk填充周数列表头formatWeekdayName改用EEEEE令牌输出单字符星期名如M。注意formatWeekNumberHeader无参数覆盖时写() ...即可。与 DateLib、Locale 的关系所有 formatter 的底层格式化能力都来自 packages/react-day-picker/src/classes/DateLib.ts 中的DateLib类。从源码可以看到两条调用路径formatCaption/formatDay/formatWeekdayName优先使用传入的dateLib实例否则用new DateLib(options)新建——因此它们能感知options.localeformatMonthDropdown/formatYearDropdown/formatWeekNumber默认使用模块级单例defaultDateLib。DateLib封装了 locale 解析、数字系统转换formatNumber、以及format/formatMonthYear等日期格式化方法。这也解释了为什么在 翻译指南 中建议保持覆盖最小化keep overrides minimal内置 formatter 已经随locale自动切换语言与数字系统过度覆盖反而可能丢失这些本地化能力。当你只想要某种特定格式如中文标题2022年11月时再针对性地覆盖对应 formatter。与 Labels 的区别Formatters常与 Labels 类型混淆二者的分工在 shared.ts 中清晰可见Formatters负责可见文本的排版格式数字、月份名、星期名、标题文案Labels负责ARIA 无障碍标签如labelNext、labelPrevious、labelDayButton主要服务于屏幕阅读器通常不可见。例如formatWeekdayName决定表头显示Mo还是星期一而labelWeekday决定读屏软件如何读出该列。做本地化时通常两者都需要一起定制但它们属于两套独立的 prop。小结Formatters类型把日历的 7 处日期文本渲染抽象为一张可插拔的函数映射表内置实现覆盖了月份标题、日期数字、星期表头、周数、周数表头、月份与年份下拉框标签默认行为全部与当前locale联动通过DayPicker的formattersprop 可按需覆盖任意字段签名由typeof约束保证类型安全类型定义见 shared.ts默认实现见 packages/react-day-picker/src/formatters/可运行示例见 examples/Formatters.tsx官方翻译指南见 translation.mdx。掌握Formatters你就能精确控制日历每一处日期的呈现方式——无论是给标题加上季节 emoji还是让周数、星期名符合特定语言习惯都只需覆盖对应的一个函数即可。赞分享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 Formatters 类型详解用 formatters 定制日历的日期渲染React DayPicker Formatters 类型详解用 formatters 定制日历的日期渲染 导读 在 React DayPicker 中日历UI组件前端react-day-picker 的 Formatters 类型详解用自定义格式化函数掌控日历渲染的每一处文本react day picker 的 Formatters 类型详解用自定义格式化函数掌控日历渲染的每一处文本 本指南以 react day picker vUI组件前端react-day-picker 的 ModifiersClassNames 类型详解为日期单元格按修饰符精准定制 CSS 类名react day picker 的 ModifiersClassNames 类型详解为日期单元格按修饰符精准定制 CSS 类名 ModifiersClassUI组件前端上一篇Jubatus算法原理从线性混合到被动攻击学习的底层技术下一篇QtUnblockNeteaseMusic开发者揭秘Qt框架下的服务器管理与日志监控实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考