rsuite DateRangePicker 显示周数（showWeekNumbers）：配置、ISO 周规则与源码实现解析

前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载导读showWeekNumbers是 rsuiteDateRangePicker组件中用于在日历面板左侧显示周数列的开关属性。本文以 show-week-numbers.md 演示片段 为骨架完整讲解其用法、与isoWeek/weekStart的协同关系、周数计算规则普通周w与 ISO 周I并结合 GridRow.tsx 等源码与测试用例说明周数列从属性传入 → 上下文传递 → 表头占位 → 行内渲染 → 样式呈现的完整实现链路。读完本文你将能独立在 rsuite 项目中开启周数显示并理解其周数编号遵循哪套标准、受哪些属性影响。一分钟上手在 DateRangePicker 中开启周数原文档提供的演示片段非常简洁核心用法就是在DateRangePicker上设置一个布尔属性import { DateRangePicker } from rsuite; const App () ( DateRangePicker showWeekNumbers / / ); ReactDOM.render(App /, document.getElementById(root));从 en-US 组件文档的 Props 表 可以看到该属性的官方定义属性类型默认值描述showWeekNumbersboolean—是否显示周数Whether to show week numbers要点属性为可选的布尔开关不传则默认不显示周数列它同时适用于DateRangePicker与DatePicker后者在 show-week-numbers.md 演示片段 中还有w{200}指定宽度本文聚焦DateRangePickershowWeekNumbers只决定周数列是否出现周数的编号标准与每周起始日由isoWeek、weekStart、locale决定三者缺一不可理解。开启后日历面板左侧会出现一列宽度约30px、背景与正文区略有区分的数字列每一行即一周显示该周在一年中的序号。周数列的外观样式层如何呈现周数列的视觉样式在 src/Calendar/styles/index.scss 中定义核心类为rs-calendar-table-cell-week-number.rs-calendar-table-cell-week-number { display: table-cell; min-width: 30px; padding: var(--rs-calendar-table-cell-padding); text-align: center; vertical-align: middle; color: var(--rs-text-secondary); background-color: var(--rs-bg-well); font-size: var(--rs-font-size-xs); }可以归纳出以下实现事实周数列作为table-cell参与日历的表格布局最小宽度30px文字水平居中、垂直居中对齐使用次级文本色--rs-text-secondary与底色--rs-bg-well与日期单元格形成视觉层级区分字号为--rs-font-size-xs小号字体整体呈现为弱化的辅助信息列表格第一行与最后一行即整个面板的第一周与最后一周的周数单元格还会通过 index.scss 中的圆角规则 应用--rs-radius-md圆角保持与面板整体轮廓一致。周数如何计算普通周w与 ISO 周I周数编号并非简单从 1 数到 52它与一周从哪天开始强相关。在 GridRow.tsx 中周数通过 date-fns 的format按两种模式计算const { firstWeekContainsDate } locale?.dateLocale?.options ?? {}; // ISO week starts on Monday const date isoWeek ? addDays(startingDate, 1) : startingDate; const week format(new Date(date.year, date.month - 1, date.day), isoWeek ? I : w, { locale: locale?.dateLocale, firstWeekContainsDate, weekStartsOn: weekStart });关键逻辑说明isoWeek为false默认使用 date-fns 的w格式符计算普通周数weekStartsOn传入weekStart的值firstWeekContainsDate取自 locale 的dateLocale.optionsisoWeek为true使用I格式符计算ISO 8601 周数并且由于 ISO 标准规定每周从星期一开始源码在计算前对日期做了addDays(startingDate, 1)的偏移调整确保周号归属正确也就是说周数列显示的数字会随着isoWeek、weekStart以及 locale 设置的不同而改变同一个日期在不同配置下可能属于不同的周号。起始日如何决定isoWeek 与 weekStart 的优先级每周从哪天开始直接影响周数的划分。在 useCalendar.ts 中有一套明确的计算优先级const weekStart useMemo(() { // If weekStartProp is explicitly provided, use it if (typeof weekStartProp ! undefined) { return weekStartProp; } // If using ISO week, start on Monday (1) else if (isoWeek) { return 1; } // If locale specifies a weekStartsOn option, use it else if (locale?.dateLocale?.options?.weekStartsOn ! undefined) { return locale.dateLocale.options.weekStartsOn; } // Default to Sunday (0) if no other condition is met return 0; }, [weekStartProp, isoWeek, locale?.dateLocale?.options?.weekStartsOn]);优先级从高到低依次是显式传入的weekStart取值0~60为星期日与 Props 表 一致isoWeek为true时强制weekStart 1星期一此时weekStart被忽略文档 Props 表中注明如果设置了isoWeek则忽略此属性locale 中dateLocale.options.weekStartsOn的本地化设置兜底默认0星期日。值得注意的联动关系若只设置showWeekNumbers而不设置任何起始日周数列默认按星期日为一周第一天的规则编号若希望周数与周一为一周开始的 ISO 8601 惯例一致应同时设置isoWeek例如 hover-range.md 演示片段 中选择整周示例就通过hoverRangeweek isoWeek保证按 ISO 标准选周若业务上以星期三为一周开始可设置weekStart{3}周数列会同步按该规则编号。从属性到界面周数列的完整实现链路showWeekNumbers在 rsuite 中的传递链路清晰可以从源码逐一验证1. 属性声明与透传在 DateRangePicker.tsx 中声明showWeekNumbers?: boolean并在渲染弹出面板时DateRangePicker.tsx将其与isoWeek、weekStart等一起组装进calendarProps传入日期范围选择器内部的Calendar。2. 进入日历上下文DateRangePicker/Calendar.tsx 将showWeekNumbers等属性透传给通用日历容器CalendarContainer最终写入CalendarProvider提供的上下文。上下文类型定义见 CalendarProvider.ts其中明确注释该字段含义为是否显示周数。3. 表头留出空列开启后表头行会在每周列标题Su/Mo/Tu/We/Th/Fr/Sa之前渲染一个空的占位列见 GridHeaderRow.tsx{showWeekNumbers div className{prefix(header-cell)} rolecolumnheader /}对应测试 CalendarGridHeaderRow.spec.tsx 验证当showWeekNumbers: true时表头行应包含 8 个子节点1 个空占位列 7 个星期标题列。4. 数据行渲染周数每个数据行在渲染 7 个日期单元格之前先渲染周数单元格见 GridRow.tsx{showWeekNumbers ( div rolerowheader aria-label{Week ${week}} className{prefix(cell-week-number)} {week} /div )}这里同时体现了无障碍设计周数单元格带有rolerowheader与aria-labelWeek N辅助技术可以读取每行的周号。此外整个行结构使用rolerow日期/表头单元格使用rolecolumnheader周数列与星期标题列共享同一表格布局。与其他属性搭配的实战组合结合组件文档与其他演示片段showWeekNumbers常见的搭配方式如下组合意图配置示例说明默认周数周日为起点DateRangePicker showWeekNumbers /使用 locale 默认规则通常为周日起始ISO 周数周一为起点DateRangePicker showWeekNumbers isoWeek /周数与 ISO 8601 标准一致自定义每周起点DateRangePicker showWeekNumbers weekStart{3} /如周三为一周第一天周号随之重排整周选择 周数DateRangePicker showWeekNumbers hoverRangeweek isoWeek ranges{[]} /配合 hover-range 演示按周选择并同步显示 ISO 周号需要注意的边界与前提当isoWeek为true时weekStart会被忽略强制为1因此上述第二、三种组合不应同时生效实际以isoWeek为准showWeekNumbers仅影响日历面板内部不影响DateRangePicker输入框中的格式化文本format属性周数列占用一列表格宽度若同时设置showOneCalendar单日历面板同样会渲染周数列布局由 DateRangePicker.tsx 中的面板样式 统一控制。总结showWeekNumbers是一个轻量但涉及周号语义的开关属性其背后完整依赖 rsuite 日历体系的三个组成部分属性透传层DateRangePicker→Calendar→CalendarContainer→CalendarProvider上下文DateRangePicker.tsx周数计算层基于isoWeek在 date-fns 的w与I格式符之间切换并受weekStart、locale 影响GridRow.tsx呈现层表头空占位列 行内rs-calendar-table-cell-week-number单元格配合rowheader角色保证无障碍GridHeaderRow.tsx、index.scss。若你的业务需要展示第几周信息如排班、报表、项目管理周报直接在DateRangePicker上开启showWeekNumbers即可若要周号符合国际惯例请务必同时开启isoWeek避免周日起始的默认规则带来周号偏差。赞分享前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载相关推荐rsuite DatePicker 周数显示showWeekNumbers实战指南从属性用法到源码实现rsuite DatePicker 周数显示showWeekNumbers实战指南从属性用法到源码实现 导读 showWeekNumbers 是 rsui前端UI组件rsuite DatePicker 的 isoWeek 属性启用 ISO 8601 周历显示与周编号rsuite DatePicker 的 isoWeek 属性启用 ISO 8601 周历显示与周编号 在 rsuite 的日期选择组件体系中 DatePic前端UI组件使用 RSuite Calendar 定制周起始日weekStart、isoWeek 与 showWeekNumbers 详解使用 RSuite Calendar 定制周起始日weekStart、isoWeek 与 showWeekNumbers 详解 本文基于 RSuite 日历组前端UI组件上一篇Gluegun项目开发环境搭建与贡献指南下一篇Godot Voxel 项目中的程序化地形生成技术解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考