rsuite DatePicker 的 isoWeek 属性:启用 ISO 8601 周历显示与周编号

原创2026-09-25 23:39:571,377 阅读
文章标签:前端UI组件

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。其决策优先级如下:

  1. 显式传入 weekStart:优先使用用户自定义的周起始日;
  2. isoWeek 为 true:固定返回 1(周一);
  3. locale 的 dateLocale 中配置了 weekStartsOn:跟随地区化配置;
  4. 兜底默认值:返回 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)保持一致。

注意事项:

  1. 不要同时设置 isoWeek 与 weekStart:文档约定后者会被忽略,但源码决策链中显式 weekStart 优先级更高,混用会造成行为与文档不符,建议只取其一;
  2. i18n 联动:若不设置 isoWeek 也不设置 weekStart,周起始日会跟随 CustomProvider 中 locale 的 dateLocale.options.weekStartsOn,因此在多语言站点中"默认周首"可能随语言切换而改变;
  3. 周编号口径:isoWeek 同时改变周编号算法('I' 格式符),跨年场景下某年 1 月初的日期可能显示为上一年第 52/53 周,这是 ISO 8601 的正常行为,不是 bug;
  4. 作用范围:isoWeek 是日历内核通用属性,DateRangePicker 同样支持(见 src/DateRangePicker/DateRangePicker.tsx 中的透传),日期范围选择场景下可放心使用。

七、小结

isoWeek 是 rsuite 日期组件在国际化周历处理上的关键开关:属性层面一行代码即可切换周首,实现层面则由 DatePicker → CalendarContainer → CalendarProvider → useCalendar → GridRow 的完整链路协同完成,周编号格式与 locale 配置深度融合。结合 showWeekNumbers,它可以构建出符合 ISO 8601 标准的完整周历交互,为跨时区、跨文化的排期类业务提供稳定的日历基础。

登录后查看全文
rsuite