radix-vue MonthRangePicker 月份范围选择器完全指南月粒度区间选择、键盘导航与无障碍实现【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vue本指南基于 radix-vue原 Radix Vue开源组件库中MonthRangePicker组件的官方文档并结合packages/core/src/MonthRangePicker源码与测试用例展开。MonthRangePicker 是一个以月份为粒度的范围选择器它以年为单位进行页面翻页Prev/Next 每次前进或后退一年用户通过点选两个月份来确定一个连续月份区间。读完本文你将掌握该组件的完整组件结构与装配方式、全部 Props/插槽/事件与 Data Attribute 的语义、底层区间状态机高亮、最大跨度、固定端点的实现原理以及完整的键盘交互与无障碍约定能够直接在 Vue 3 项目中组合出可用、可访问、可本地化的月份范围选择界面。一、组件概览与核心特性MonthRangePicker在库中属于日历类组件家族与MonthPicker、RangeCalendar等共用底层日期工具它的职责是呈现一个专为选择月份范围定制的月历视图。文档将其标记为Alpha状态意味着 API 仍在演进使用时建议锁定版本。官方文档列出的特性包括完整的键盘导航Full keyboard navigation受控与非受控双模式Can be controlled or uncontrolled焦点完全托管Focus is fully managed本地化支持Localization support高度可组合Highly composable高度可组合是该库的一贯设计哲学组件被拆分成Root、Header、Prev、Next、Heading、Grid、GridBody、GridRow、Cell、CellTrigger十个部件由用户自行决定渲染结构和样式库只负责行为与状态。二、前置依赖internationalized/dateMonthRangePicker 依赖 Adobe 开源的internationalized/date包。官方文档强调这个包解决了 JavaScript 处理日期和时间的大量痛点——它提供日历体系抽象CalendarDate、CalendarDateTime、ZonedDateTime、历法/时区换算与日期运算能力是整个日期组件家族的类型基础。在源码中可以看到这一依赖贯穿始终MonthRangePickerRoot.vue顶部import type { DateValue } from internationalized/date组件内部大量使用isSameYearMonth、compareYearMonth、add({ months })等来自/date即packages/core/src/date的封装工具函数。测试用例 MonthRangePicker.test.ts 也证明modelValue/defaultValue可以接受三种日期类型// CalendarDate纯日期无时间、无时区 const calendarDateRange { start: new CalendarDate(1980, 1, 20), end: new CalendarDate(1980, 3, 25), } // CalendarDateTime带时间的日期 const calendarDateTimeRange { start: new CalendarDateTime(1980, 1, 20, 12, 30, 0, 0), end: new CalendarDateTime(1980, 3, 25, 12, 30, 0, 0), } // ZonedDateTime带时区的日期 const zonedDateTimeRange { start: toZoned(calendarDateTimeRange.start, America/New_York), end: toZoned(calendarDateTimeRange.end, America/New_York), }因此官方建议在开始使用日期类组件前先通读internationalized/date包的文档理解DateValue类型体系才能正确构造默认值、占位符与匹配器函数。三、安装先安装日期工具包所有日期组件共享的依赖npm install internationalized/date # 或 pnpm add internationalized/date再从命令行安装组件库本身本项目当前文档与示例均以reka-ui名称导入组件npm install reka-ui # 或 pnpm add reka-ui安装完成后即可从reka-ui导入 MonthRangePicker 的全部部件如官方文档 Anatomy 所示。四、Anatomy装配全部部件MonthRangePicker 由 10 个部件拼装而成官方给出的最小完整结构如下script setup import { MonthRangePickerCell, MonthRangePickerCellTrigger, MonthRangePickerGrid, MonthRangePickerGridBody, MonthRangePickerGridRow, MonthRangePickerHeader, MonthRangePickerHeading, MonthRangePickerNext, MonthRangePickerPrev, MonthRangePickerRoot, } from reka-ui /script template MonthRangePickerRoot MonthRangePickerHeader MonthRangePickerPrev / MonthRangePickerHeading / MonthRangePickerNext / /MonthRangePickerHeader MonthRangePickerGrid MonthRangePickerGridBody MonthRangePickerGridRow MonthRangePickerCell MonthRangePickerCellTrigger / /MonthRangePickerCell /MonthRangePickerGridRow /MonthRangePickerGridBody /MonthRangePickerGrid /MonthRangePickerRoot /template各部件职责一览默认渲染元素见 index.ts 与对应 meta 文件部件职责默认渲染元素MonthRangePickerRoot持有全部状态与上下文包含选择器所有部分divMonthRangePickerHeader承载导航按钮与标题段divMonthRangePickerPrev导航按钮将日历向前翻一年buttonMonthRangePickerNext导航按钮将日历向后翻一年buttonMonthRangePickerHeading标题显示当前年份divMonthRangePickerGrid包裹月份网格的容器tableMonthRangePickerGridBody包裹网格主体tbodyMonthRangePickerGridRow包裹网格行trMonthRangePickerCell包裹单个月份单元格tdMonthRangePickerCellTrigger可交互的月份展示容器点击它选择月份div注意 Prev/Next 的翻页粒度是年而非月——因为该组件的页面视图是一整年的 12 个月这与MonthPicker一致与按日期的RangeCalendar逐月翻页不同。五、API Reference 详解5.1 Root状态与行为中枢官方文档对 Root 的描述是包含月份范围选择器的所有部分。它通过createContext向子部件提供状态见 MonthRangePickerRoot.vue子部件通过injectMonthRangePickerRootContext取用。Props详见 MonthRangePickerRoot.md名称说明类型必填默认值allowNonContiguousRanges与isMonthUnavailable组合使用决定是否允许选择非连续区间boolean否falseas渲染为的元素或组件可被asChild覆盖AsTag \| Component否divasChild将默认渲染元素替换为传入的子元素并合并其 props 与行为boolean否—calendarLabel日历的可访问标签string否—defaultPlaceholder默认占位日期DateValue否—defaultValue日历的默认值DateRange否{ start: undefined, end: undefined }dir日历的阅读方向ltr \| rtl否—disabled是否禁用整个日历boolean否falsefixedDate固定区间的哪一端start \| end否—initialFocus为true时挂载即聚焦已选中的月份boolean否falseisMonthDisabled判断某个月份是否被禁用的函数Matcher否—isMonthUnavailable判断某个月份是否不可用的函数Matcher否—locale用于格式化日期的区域设置string否—maximumMonths一个区间最多可选中的月份数number否—maxValue可选中的最大日期DateValue否—minValue可选中的最小日期DateValue否—modelValue受控的选中月份区间可绑定v-modelDateRange \| null否—nextPage返回日历下一页的函数(placeholder: DateValue) DateValue否—placeholder占位日期用于在无选中值时决定显示哪一年DateValue否—preventDeselect是否阻止用户在不先选择其他日期的情况下取消选中boolean否falseprevPage返回日历上一页的函数(placeholder: DateValue) DateValue否—Events名称说明类型update:modelValue每当 model 值变化时触发[date: DateRange]update:placeholder每当占位日期变化时触发[date: DateValue]update:startValue每当开始值变化时触发[date: DateValue]Slots默认插槽作用域名称说明类型date当前占位日期DateValuegrid月份网格GridDateValuelocale日历的 localestringmodelValue当前日期区间DateRangeRoot 的 Data Attributes官方文档数据表属性取值[data-readonly]只读时出现[data-disabled]禁用时出现[data-invalid]无效时出现从源码可见这三个属性与readonly、disabled、isInvalid状态一一对应其中isInvalid由useRangeMonthPickerState计算得出见下文源码原理章节。Root 还会渲染一个aria-label值为fullCalendarLabel以及一个视觉隐藏的roleheading aria-level2标题块用于无障碍朗读同时把dir属性透传到根元素上。5.2 Header / Prev / Next / HeadingHeader容器承载导航按钮与标题段。Props 仅as默认div与asChild。Prev Button向前翻一年的导航按钮。Props 除as/asChild外还有prevPage——可覆盖 Root 上设置的prevPage函数类型为(placeholder: DateValue) DateValue。Data Attribute[data-disabled]禁用时出现。插槽暴露disabled: boolean作用域。Next Button向后翻一年结构同上对应nextPage覆盖函数与[data-disabled]。Heading显示当前年份的标题。Props 仅as默认div与asChild。插槽暴露headingValue: string当前年份文本。5.3 Grid / GridBody / GridRow / CellGrid包裹月份网格的容器默认渲染tableProps 仅as/asChild。Data Attributes[data-readonly]、[data-disabled]。GridBody包裹网格主体默认tbody。GridRow包裹网格行默认tr。Cell包裹单元格默认td。Props 除as/asChild外还有必填的date: DateValue该单元格的日期值。Data Attribute[data-disabled]。5.4 Cell Trigger交互核心Cell Trigger是可交互的月份展示容器点击它选择月份。Props 仅三个名称说明类型必填默认值as渲染元素AsTag \| Component否divasChild合并子元素 props 与行为boolean否—month提供给单元格触发器的日期值DateValue是—其默认插槽暴露的作用域见 MonthRangePickerCellTrigger.md插槽名说明类型monthValue当前月份值短名称如Janstringdisabled当前禁用状态booleanselected当前选中状态booleantoday当前月份是否为今天所在月份booleanunavailable当前不可用状态booleanhighlighted当前高亮状态用户选择区间时booleanhighlightedStart是否为用户高亮区间的起点booleanhighlightedEnd是否为用户高亮区间的终点booleanselectionStart是否为已选区间的起点booleanselectionEnd是否为已选区间的终点booleanCell Trigger 的 Data Attributes官方文档数据表属性取值[data-selected]选中时出现[data-value]日期的 ISO 字符串值[data-disabled]禁用时出现[data-unavailable]不可用时出现[data-today]该月为当前月份时出现[data-selection-start]该月为选中区间起点时出现[data-selection-end]该月为选中区间终点时出现[data-highlighted]用户选择区间时被高亮时出现[data-highlighted-start]为用户高亮区间起点时出现[data-highlighted-end]为用户高亮区间终点时出现[data-focused]获得焦点时出现从 MonthRangePickerCellTrigger.vue 的模板可以看到这些属性的落地方式data-value使用month.toString()即 ISO 字符串同时组件还渲染rolebutton、aria-label值为长月份 年份如 January 2024、aria-pressed与aria-disabled并将tabindex在聚焦月份0、禁用不出现与其他月份-1之间切换以实现焦点完全托管的 roving tabindex 模式。六、源码级原理区间状态机与边界控制6.1 useRangeMonthPickerState 的核心逻辑Root 将区间相关的计算委托给useRangeMonthPickerState见 useRangeMonthPicker.ts它输出了isInvalid、isSelected、isSelectionStart/End、isHighlightedStart/End、highlightedRange以及经过区间逻辑包装的isMonthDisabled。关键点无效判定isInvalid当起点或终点命中isMonthDisabled或终点早于起点compareYearMonth(end, start) 0时整体视为无效Root 据此渲染[data-invalid]。选中判定isSelected起点月、终点月以及二者之间的所有月份都被视为已选中这保证了区间在视觉上的连续性。高亮区间highlightedRange用户已选定起点但尚未确定终点时以起点 ↔ 当前焦点月份为边界计算高亮范围且必须通过areAllMonthsBetweenValid校验中间月份全部有效未禁用、不可用否则不产生高亮。当allowNonContiguousRanges为true时跳过不可用校验从而允许跨过不可用月份的非连续选择。6.2 maximumMonths 与 fixedDate 的配合maximumMonths限制区间最大跨度fixedDate决定固定哪一端start或end。源码中rangeIsMonthDisabled展示了二者的协作逻辑区间两端都未确定时以起点为锚点计算[start - (max-1), start (max-1)]的可选范围fixedDate指定时若用户反向越过固定端会移动固定端而不是另一端同时以固定端为锚点裁剪可选范围区间已满时若未指定fixedDate新点击会重置整个区间重新选择对应测试用例 resets range on select when a range is already selected见 MonthRangePicker.test.ts。6.3 Escape 回滚与受控/非受控Root 中维护validModelValue作为上一次有效区间的备份当用户正在编辑isEditing时按下Escape会通过useEventListener(parentElement, keydown, ...)监听并将startValue/endValue还原为有效值这正是官方键盘表中取消当前区间选择恢复上一次有效区间的实现。同时useVModel让modelValue与placeholder都支持受控绑定v-model与非受控defaultValue/defaultPlaceholder两种模式测试用例还验证了modelValue传null不会崩溃见 MonthRangePicker.test.ts。七、无障碍与键盘交互该库对无障碍的重视体现在测试中MonthRangePicker.test.ts首条用例即运行axe检查并断言toHaveNoViolations()见 MonthRangePicker.test.ts。组件在 DOM 层面提供可访问的calendarLabel、视觉隐藏的 heading 朗读区、每个 CellTrigger 的aria-label、aria-pressed、aria-disabled以及完整的data-*状态钩子供样式系统消费。官方文档给出的完整键盘交互约定如下按键行为Tab焦点移入组件时聚焦第一个导航按钮Space焦点在MonthRangePickerNext/MonthRangePickerPrev上时翻页否则选择月份Enter同SpaceArrowLeft/ArrowRight/ArrowUp/ArrowDown焦点在MonthRangePickerCellTrigger上时在月份间导航必要时跨年PageUp焦点在 CellTrigger 上时跳转到上一年的同一月份PageDown焦点在 CellTrigger 上时跳转到下一年的同一月份Escape取消当前区间选择恢复上一次有效区间从 MonthRangePickerCellTrigger.vue 可以看到方向键导航的源码实现左右箭头按±1个月平移上下箭头按±4个月12 个月网格按 3 列 × 4 行排布且全部考虑dirrtl时左右键方向取反若目标月份不在当前页会先调用nextPage/prevPage翻页再在nextTick后重新查找目标单元格并focus()目标不可达超出minValue/maxValue、按钮被禁用时静默停止。PageUp/PageDown则通过add({ years: ±1 })跨年导航同样需要翻页后重试且递归深度上限为 48 次以防死循环。八、完整实战示例结合官方 Demodocs/components/demo/MonthRangePicker/tailwind/index.vue一个带默认值、完整样式与状态反馈的月份范围选择器如下script setup import { Icon } from iconify/vue import { CalendarDate } from internationalized/date import { MonthRangePickerCell, MonthRangePickerCellTrigger, MonthRangePickerGrid, MonthRangePickerGridBody, MonthRangePickerGridRow, MonthRangePickerHeader, MonthRangePickerHeading, MonthRangePickerNext, MonthRangePickerPrev, MonthRangePickerRoot, } from reka-ui const defaultValue { start: new CalendarDate(2024, 3, 1), end: new CalendarDate(2024, 6, 1), } /script template MonthRangePickerRoot v-slot{ grid } :default-valuedefaultValue classmt-6 rounded-xl bg-white p-4 shadow-sm border MonthRangePickerHeader classflex items-center justify-between MonthRangePickerPrev classsize-8 ... Icon iconradix-icons:chevron-left classsize-4 / /MonthRangePickerPrev MonthRangePickerHeading classtext-sm font-medium / MonthRangePickerNext classsize-8 ... Icon iconradix-icons:chevron-right classsize-4 / /MonthRangePickerNext /MonthRangePickerHeader div classpt-4 MonthRangePickerGrid classw-full border-collapse select-none MonthRangePickerGridBody classgrid gap-y-1 MonthRangePickerGridRow v-for(months, index) in grid.rows :keymonth-${index} classgrid grid-cols-4 gap-x-1 MonthRangePickerCell v-formonth in months :keymonth.toString() :datemonth classrelative text-center text-sm MonthRangePickerCellTrigger :monthmonth classrelative flex size-12 items-center justify-center rounded-lg outline-none contenteditable="false">【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考