rsuite DateRangePicker hoverRange 详解：悬停预选整周、整月与自定义日期范围

• 前端
• UI组件

本篇技术指南聚焦 rsuiteDateRangePicker组件的hoverRange属性，讲解如何让鼠标悬停即实时预览并一键选中"整周""整月"乃至任意自定义日期范围，并深入源码剖析其内部实现与oneTap、isoWeek、weekStart等属性的联动关系。读完本文，你将掌握hoverRange的三种取值形态、周起始日与 ISO 周历的配置技巧，以及如何用自定义函数实现"前后 N 天"等业务化范围预选。

hoverRange 是什么：悬停即预览、点击即选中

DateRangePicker默认的交互是"点击两次"：先选开始日期，再选结束日期。而hoverRange提供了一种全新的快捷交互——鼠标在日历上移动时，组件会按预设规则实时计算并高亮一段完整范围，用户只需单击一次即可将其作为日期范围选中。

从源码类型定义看，hoverRange支持三种取值（src/DateRangePicker/DateRangePicker.tsx）：

hoverRange?: 'week' | 'month' | ((date: Date) => DateRange);

• 'week'：悬停到某一天时，预选该天所在的一整周；
• 'month'：悬停到某一天时，预选该天所在的整个月；
• (date: Date) => DateRange：传入一个函数，根据悬停日期自行计算返回[开始日期, 结束日期]。

官方文档对该属性的说明为："The date range that will be selected when you click on the date"（点击日期时将被选中的日期范围），见 docs/pages/components/date-range-picker/en-US/index.md。完整的示例代码位于 docs/pages/components/date-range-picker/fragments/hover-range.md。

内置模式一：hoverRange="week" 整周预选

最简单的用法是让悬停位置自动覆盖整个星期：

import { DateRangePicker } from 'rsuite'; import { subDays } from 'date-fns/subDays'; import { addDays } from 'date-fns/addDays'; const App = () => ( <div className="field"> <p>Select Whole Week</p> <DateRangePicker hoverRange="week" ranges={[]} /> </div> );

提示：示例中的ranges={[]}用于清空面板底部的快捷选项（Today、Yesterday、Last 7 days等），让演示聚焦于 hover 交互本身。ranges属性的默认预定义范围说明见 docs/pages/components/date-range-picker/en-US/index.md。

结合 isoWeek 使用 ISO 8601 周历

默认情况下，一周的起始日由weekStart决定（默认0，即周日）。若希望遵循 ISO 8601 标准（每个日历周从周一开始，周日为第七天），则需同时开启isoWeek：

<p> Select Whole Week, <a href="https://en.wikipedia.org/wiki/ISO_week_date" target="_blank"> ISO 8601 standard </a> , each calendar week begins on Monday and Sunday is the seventh day </p> <DateRangePicker hoverRange="week" isoWeek ranges={[]} />

源码对isoWeek的定义与之完全一致（src/DateRangePicker/DateRangePicker.tsx）：

/** * ISO 8601 standard, each calendar week begins on Monday and Sunday on the seventh day */ isoWeek?: boolean;

结合 weekStart 自定义周起始日

若团队业务以周三作为周的第一天，可配合weekStart实现：

<p>Select Whole Week, week start from Wednesday</p> <DateRangePicker hoverRange="week" weekStart={3} ranges={[]} />

weekStart的取值范围是0 | 1 | 2 | 3 | 4 | 5 | 6，其中0代表周日，默认值为0。需要注意：当isoWeek为true时，weekStart的值会被忽略（src/DateRangePicker/DateRangePicker.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;

从源码看，'week'模式正是把这两个配置透传给周范围计算函数getWeekHoverRange（src/DateRangePicker/DateRangePicker.tsx）：

if (hoverRange === 'week') { return (date: Date) => getWeekHoverRange(date, { isoWeek, weekStart, locale: locale?.dateLocale }); }

getWeekHoverRange的核心逻辑（src/DateRangePicker/utils.ts）：

export const getWeekHoverRange = ( date: Date, options: { isoWeek: boolean; weekStart?: 0 | 1 | 2 | 3 | 4 | 5 | 6; locale?: Locale; } ): DateRange => { const { isoWeek, weekStart = 0, locale } = options; if (isoWeek) { // set to the first day of this week according to ISO 8601, 12:00 am return [startOfISOWeek(date), endOfISOWeek(date)]; } return [ startOfWeek(date, { weekStartsOn: weekStart, locale }), endOfWeek(date, { weekStartsOn: weekStart, locale }) ]; };

可以看到：开启isoWeek时直接使用startOfISOWeek/endOfISOWeek计算周一至周日；未开启时则通过date-fns的startOfWeek/endOfWeek配合weekStartsOn确定周边界。此外还传入了locale，意味着周起始规则会跟随locale的地区习惯（如美国习惯周日为第一天）。

内置模式二：hoverRange="month" 整月预选

与整周类似，'month'模式让悬停日期自动覆盖整个自然月：

<p>Select Whole Month</p> <DateRangePicker hoverRange="month" ranges={[]} />

其底层实现非常简洁，直接取悬停日期的月初与月末（src/DateRangePicker/utils.ts）：

export const getMonthHoverRange = (date: Date): DateRange => [startOfMonth(date), endOfMonth(date)];

在组件内部，'month'分支直接引用该函数（src/DateRangePicker/DateRangePicker.tsx）：

} else if (hoverRange === 'month') { return getMonthHoverRange; } return hoverRange;

自定义模式：hoverRange 接收函数，实现任意范围预选

hoverRange还可以是一个函数(date: Date) => DateRange，由你在悬停日期的基础上自由计算返回范围。官方示例实现了"以悬停日期为中心，前后各一天"的预选：

<p>Custom Select</p> <DateRangePicker ranges={[]} hoverRange={date => [subDays(date, 1), addDays(date, 1)]} />

这里使用了date-fns的subDays与addDays对悬停日期做偏移，返回[前一天, 后一天]。你可以基于这一范式扩展出更多业务规则，例如：

// 预选悬停日期所在工作周（周一至周五） hoverRange={date => { const day = date.getDay(); // 0=周日, 6=周六 const offsetToMonday = day === 0 ? -6 : 1 - day; const offsetToFriday = day === 0 ? 4 : 5 - day; return [addDays(date, offsetToMonday), addDays(date, offsetToFriday)]; }}

自定义函数与内置模式的优先级关系

组件内部的getHoverRangeValue展示了三种取值如何被统一处理（src/DateRangePicker/DateRangePicker.tsx）：

const getHoverRangeValue = (date: Date): DateRange | null => { function getHoverRangeFunc(): ((date: Date) => DateRange) | undefined { if (hoverRange === 'week') { return (date: Date) => getWeekHoverRange(date, { isoWeek, weekStart, locale: locale?.dateLocale }); } else if (hoverRange === 'month') { return getMonthHoverRange; } return hoverRange; // 自定义函数直接返回 } const hoverRangeFunc = getHoverRangeFunc(); if (isNil(hoverRangeFunc)) { return null; } let hoverValues: DateRange = hoverRangeFunc(date); const isHoverRangeValid = hoverValues instanceof Array && hoverValues.length === 2; if (!isHoverRangeValid) { return null; } if (isAfter(hoverValues[0], hoverValues[1])) { hoverValues = reverseDateRangeOmitTime(hoverValues); } return hoverValues; };

两点值得注意的实现细节：

1. 返回值校验：自定义函数必须返回长度为 2 的Date数组，否则 hover 范围视为无效（返回null）；
2. 自动排序：如果计算出的开始日期晚于结束日期，组件会通过reverseDateRangeOmitTime自动反转，保证范围始终以较早日期开头。

与 oneTap 配合：单击完成整段范围选中

hoverRange通常与oneTap搭配使用。oneTap的定义是"是否单击一次即完成日期范围选择，可与hoverRange配合使用"（src/DateRangePicker/DateRangePicker.tsx）：

/** * Whether to click once on selected date range，Can be used with hoverRange */ oneTap?: boolean;

在oneTap模式下，点击事件直接采用 hover 计算出的范围（src/DateRangePicker/DateRangePicker.tsx）：

// in `oneTap` mode if (oneTap) { setDateRange( event, noHoverRangeValid ? [startOfDay(date), endOfDay(date)] : hoverRangeValue ); onSelect?.(date, event); return; }

逻辑清晰：若 hover 范围有效则选中hoverRangeValue；若无效（未设置hoverRange），则回退为选中当天[startOfDay(date), endOfDay(date)]。关于oneTap的独立演示可见同目录下的 docs/pages/components/date-range-picker/fragments/one-tap.md。

源码级原理：悬停范围是如何实时刷新与落定的

理解hoverRange的交互本质，关键在于onMouseMove与handleSelectDate两个回调。

悬停刷新（onMouseMove）

鼠标在日历网格上移动时触发onMouseMove（src/DateRangePicker/DateRangePicker.tsx），其行为分为两个阶段：

• 第一次点击之前（isSelectedIdle为 true）：直接调用getHoverRangeValue(date)并把结果写入hoverDateRange，实现"悬停即高亮整段范围"的预览效果；
• 第一次点击之后、第二次点击之前（等待选择结束日期）：以selectRangeValueRef.current中暂存的首选日期为基准，用 hover 范围动态拼接新的待选范围——如果 hover 范围的开始日期早于已选开始日期，则取[hover 开始, 已选结束]，否则取[已选开始, hover 结束]。

源码注释也特别解释了为何需要selectRangeValueRef（src/DateRangePicker/DateRangePicker.tsx）：

When hoverRange is set,selectValuewill be updated during the hover process, which will cause theselectValueto be updated after the first click, so declare a Ref to temporarily store theselectValueof the first click.

即：设置hoverRange后，悬停过程会不断改写选中值，为避免第一次点击后该值丢失，需用 Ref 暂存首选的日期范围。

点击落定（handleSelectDate）

点击日期时进入handleSelectDate（src/DateRangePicker/DateRangePicker.tsx），在非oneTap模式下：

• 无有效 hover 范围：按传统"两次点击"逻辑，先记开始日期，再补结束日期；
• 有有效 hover 范围：第一次点击即把整个 hover 范围写入nextSelectDates并存入selectRangeValueRef；第二次点击时恢复selectedDates并清空 Ref，完成整段范围的选择。

选中完成后，如果范围内存在"时间"部分（has('time')），还会从左右两个日历面板分别复制对应的时间到起止日期上，保持时分秒一致；若起止顺序颠倒，则再次调用reverseDateRangeOmitTime排序。

测试验证

仓库测试用例对上述行为做了充分覆盖（src/DateRangePicker/test/DateRangePicker.spec.tsx）：

• 测试hoverRange="week"下通过 hover 选择一周（第 323 行起）；
• 测试hoverRange="week"下通过两次点击选择一周（第 344 行起）；
• 测试hoverRange="week"/hoverRange="month"与oneTap组合、配合format="yyyy-MM-dd"时的单击选值（第 719、741 行起）。

这些用例可作为你在实际项目中验证交互行为的参考模板。

小结：hoverRange 的三种形态与适用场景

使用建议：

1. 需要整周或整月快捷选择时，直接使用内置的'week'/'month'，无需手写日期计算；
2. 业务周不同于自然周时，优先用weekStart调整起始日；需要严格遵循 ISO 8601 时开启isoWeek（此时weekStart失效）；
3. 复杂业务范围（如"前 1 天到后 1 天"）使用函数形态，注意必须返回长度为 2 的Date数组，起止顺序颠倒会被组件自动纠正；
4. 希望"单击即完成选择"时，与oneTap组合使用，可显著减少用户点击次数、提升表单填写效率。

• 前端
• UI组件