rsuite DatePicker 的 isoWeek 属性:启用 ISO 8601 周历显示与周编号
rsuite DatePicker 的 isoWeek 属性:启用 ISO 8601 周历显示与周编号
在 rsuite 的日期选择组件体系中,DatePicker 默认的日历以周日(Sunday)作为每周的第一天,这与欧美习惯相符,但与 ISO 8601 国际标准(每周从周一开始)并不一致。本指南围绕 rsuite 为 DatePicker 提供的 isoWeek 属性展开,说明如何一键切换到 ISO 周历布局,并结合仓库源码剖析其底层实现、与 weekStart 的优先级关系以及周编号(Week Number)的生成逻辑。读完本文,你将能够在国际化业务场景中准确配置 ISO 周历,并理解 rsuite 日历组件关于"每周第一天"的完整决策链。
一、官方示例:一行代码启用 ISO 周历
在 rsuite 官方文档的 DatePicker 页面中,isoWeek 的演示片段如下(原文位于 docs/pages/components/date-picker/fragments/iso-week.md):
import { DatePicker } from 'rsuite';
const App = () => (
<>
<DatePicker isoWeek w={200} />
</>
);
ReactDOM.render(<App />, document.getElementById('root'));
要点说明:
isoWeek是一个布尔属性,传入后日历面板的每周布局即切换为"周一起始、周日收尾"的 ISO 8601 周历;w={200}是 rsuite 通用尺寸属性,用于设定组件宽度(200px),与周历逻辑本身无关;- 该片段同时兼容 React 18 之前的
ReactDOM.render写法,在现行 rsuite 项目中可简化为函数组件配合createRoot渲染。
二、isoWeek 属性定义与语义
isoWeek 定义在 DatePicker 的属性接口 DatePickerProps 中,源码位于 src/DatePicker/DatePicker.tsx:
/**
* ISO 8601 standard, each calendar week begins on Monday and Sunday on the seventh day
*
* @see https://en.wikipedia.org/wiki/ISO_week_date
*/
isoWeek?: boolean;
其语义在 rsuite 中表述为:遵循 ISO 8601 标准,每个日历周从周一(Monday)开始,周日(Sunday)是第七天。启用后,日历第一列不再是"周日",而是"周一"。
同时,DatePicker 还提供 weekStart 属性用于自定义每周起始日,见 src/DatePicker/DatePicker.tsx:
/**
* The index of the first day of the week (0 - Sunday)
* If `isoWeek` is `true`, the value of `weekStart` is ignored.
*
* @default 0
*/
weekStart?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
这里明确了一个关键规则:当 isoWeek 为 true 时,weekStart 的取值会被忽略。也就是说,isoWeek 与 weekStart 属于互斥配置,ISO 周历固定以周一为起点,不允许再通过 weekStart 覆盖。
三、底层实现:isoWeek 如何驱动日历渲染
isoWeek 并不只在 DatePicker 中存在,而是贯穿整个 rsuite 日历体系(DatePicker、DateRangePicker、独立的 Calendar 组件共用一套日历内核)。理解这条链路,有助于排查周历相关的显示问题。
3.1 属性透传:DatePicker → CalendarContainer
在 src/DatePicker/DatePicker.tsx 中,DatePicker 渲染弹出层时会把自己接收到的 isoWeek 与 weekStart 原样透传给日历容器 CalendarContainer:
<CalendarContainer
...
isoWeek={isoWeek}
weekStart={weekStart}
...
/>
CalendarContainer 对 isoWeek 的默认值为 false(见 src/Calendar/CalendarContainer.tsx),即默认采用非 ISO 布局,这保证了不传任何属性时的行为与旧版本一致。
3.2 上下文注入:CalendarContainer → CalendarProvider
CalendarContainer 将 isoWeek、weekStart 与 locale 等信息写入 CalendarProvider 提供的 Context,见 src/Calendar/CalendarContainer.tsx。Context 的结构定义在 src/Calendar/CalendarProvider.ts,其中 isoWeek 被声明为必填的 boolean,weekStart 为可选的 0 | 1 | ... | 6。
3.3 周起始日的决策链:useCalendar hook
真正把"每周从哪天开始"确定下来的逻辑在 useCalendar 钩子中,源码位于 src/Calendar/hooks/useCalendar.ts。其决策优先级如下:
- 显式传入
weekStart:优先使用用户自定义的周起始日; isoWeek为true:固定返回1(周一);- locale 的
dateLocale中配置了weekStartsOn:跟随地区化配置; - 兜底默认值:返回
0(周日)。
const weekStart = useMemo(() => {
if (typeof weekStartProp !== 'undefined') {
return weekStartProp;
} else if (isoWeek) {
return 1;
} else if (locale?.dateLocale?.options?.weekStartsOn !== undefined) {
return locale.dateLocale.options.weekStartsOn;
}
return 0;
}, [weekStartProp, isoWeek, locale?.dateLocale?.options?.weekStartsOn]);
注意一个实现细节:第 1 条"显式 weekStart"的优先级高于 isoWeek。虽然属性文档声明"isoWeek 为 true 时 weekStart 被忽略",但这是针对组件 API 使用层面的约定;若同时传入两者,hook 中实际上会先命中 weekStartProp。因此在实际使用中应避免同时设置二者,以免产生与文档描述不符的行为。
3.4 周网格渲染:GridRow 中的 ISO 周编号
周起始日确定后,日历体的每一行(即一个"周")由 GridRow 渲染,源码位于 src/Calendar/Grid/GridRow.tsx。这里同时处理了 isoWeek 与 showWeekNumbers 的联动:
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
});
return (
...
{showWeekNumbers && (
<div role="rowheader" aria-label={`Week ${week}`} className={prefix('cell-week-number')}>
{week}
</div>
)}
...
);
关键点:
- 周编号格式化:
isoWeek为true时使用 date-fns 的'I'格式符(ISO 周编号,范围为 1–53);否则使用'w'(普通周编号)。ISO 周编号遵循 ISO 8601 规则,即"包含当年第一个星期四的那一周为第 1 周",因此跨年日期可能归属上一年的周编号; firstWeekContainsDate:取自 locale 的dateLocale.options,用于配合'w'格式化时定义"第 1 周"的判定基准(常见值为 1 或 4);- 周起始偏移:
isoWeek ? addDays(startingDate, 1) : startingDate是配合周首格对齐的偏移处理; - 无障碍语义:周编号格带
role="rowheader"与aria-label="Week N",方便屏幕阅读器识别。
此外,每个月的周起始行集合由 src/internals/utils/date/getWeekStartDates.ts 计算,其内部调用 date-fns 的 startOfWeek,并把 weekStartsOn 与 locale 一并传入,从而保证月首对齐到正确的周起始日。
四、组合用法:isoWeek + showWeekNumbers
isoWeek 常常与 showWeekNumbers 搭配使用——启用 ISO 周历后,在每行左侧显示 ISO 周编号,对涉及"第几周"排期的业务(如生产排程、教学周历、周报统计)非常实用:
import { DatePicker } from 'rsuite';
const App = () => (
<DatePicker
isoWeek
showWeekNumbers
format="yyyy-MM-dd"
style={{ width: 240 }}
/>
);
行为说明:
showWeekNumbers属性同样定义于 src/DatePicker/DatePicker.tsx,仅控制"是否显示周编号列";- 是否使用 ISO 周编号由
isoWeek决定:isoWeek={true}时编号遵循 ISO 8601(周一为一周之首、含周四的周为第 1 周),否则使用普通周编号; - 启用
showWeekNumbers后,日历容器会追加show-week-numbers样式类(见 src/Calendar/CalendarContainer.tsx),周编号格使用calendar-table-cell-week-number类名。
五、测试验证:ISO 周历的确定性行为
rsuite 为 isoWeek 提供了专门的单元测试,位于 src/DatePicker/test/DatePicker.spec.tsx:
it('Should render the correct week start with `isoWeek`', () => {
render(<DatePicker defaultOpen value={new Date('2024-05-21')} isoWeek />);
const weeks = ['Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa', 'Su'];
const rows = screen.getAllByRole('columnheader');
const gridcells = screen.getAllByRole('gridcell');
rows.forEach((row, index) => {
expect(row).to.have.text(weeks[index]);
});
expect(gridcells[0]).to.have.attribute('aria-label', '29 Apr 2024');
});
该测试以 2024-05-21(周二)为选中日期验证:
- 表头序列:星期表头依次为
Mo Tu We Th Fr Sa Su,确认周一成为第一列; - 单元格对齐:首个单元格的
aria-label为29 Apr 2024——2024 年 5 月的第一天(5 月 1 日,周三)所在周的周一恰为 4 月 29 日,证明月首对齐逻辑正确跨月回退到了 ISO 周首。
这一测试同时印证了 aria-label 中日期格式遵循 locale(默认英文环境为 dd MMM yyyy)。
六、适用场景与注意事项
推荐使用场景:
- 面向欧洲、俄罗斯等以 ISO 8601 为主要周历标准的用户群体;
- 需要展示 ISO 周编号(
isoWeek+showWeekNumbers)的周报、排期类界面; - 希望日历与后端数据层的周粒度统计口径(通常也遵循 ISO 8601)保持一致。
注意事项:
- 不要同时设置
isoWeek与weekStart:文档约定后者会被忽略,但源码决策链中显式weekStart优先级更高,混用会造成行为与文档不符,建议只取其一; - i18n 联动:若不设置
isoWeek也不设置weekStart,周起始日会跟随CustomProvider中 locale 的dateLocale.options.weekStartsOn,因此在多语言站点中"默认周首"可能随语言切换而改变; - 周编号口径:
isoWeek同时改变周编号算法('I'格式符),跨年场景下某年 1 月初的日期可能显示为上一年第 52/53 周,这是 ISO 8601 的正常行为,不是 bug; - 作用范围:
isoWeek是日历内核通用属性,DateRangePicker同样支持(见 src/DateRangePicker/DateRangePicker.tsx 中的透传),日期范围选择场景下可放心使用。
七、小结
isoWeek 是 rsuite 日期组件在国际化周历处理上的关键开关:属性层面一行代码即可切换周首,实现层面则由 DatePicker → CalendarContainer → CalendarProvider → useCalendar → GridRow 的完整链路协同完成,周编号格式与 locale 配置深度融合。结合 showWeekNumbers,它可以构建出符合 ISO 8601 标准的完整周历交互,为跨时区、跨文化的排期类业务提供稳定的日历基础。