radix-vueReka UIYearRangePickerRoot 组件完全指南年份区间选择器的 Props、事件与插槽深度解析【免费下载链接】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-vueYearRangePickerRoot 是 radix-vue 组件库现更名为 Reka UI中用于构建年份区间选择器的根组件适合需要按年份批量选择连续区间的场景例如筛选 2018-2023 年度数据、生成多年期的统计报表等。读完本文你将掌握该根组件的全部 23 个 Props、3 个自定义事件与 4 个作用域插槽的准确语义并能结合子组件组合出一个可无障碍键盘操作的年份范围选择器。组件定位与整体架构YearRangePickerRoot 是整个 YearRangePicker年份范围选择器的唯一状态中枢。它本身不渲染任何可见的年份网格而是通过provide/inject上下文机制向YearRangePickerGrid、YearRangePickerCell、YearRangePickerHeader、YearRangePickerNext、YearRangePickerPrev等子组件下发共享状态与回调这与仓库内RangeCalendar、MonthRangePicker、YearPicker等日期组件共享同一套设计模式。从源码看Root 组件内部组合了两个核心状态逻辑useYearPicker由YearRangePickerRoot.vue第 216 行引入负责年份网格生成grid、翻页nextPage/prevPage、标题文本headingValue与格式化器formatteruseRangeYearPickerState负责区间合法性校验isInvalid、选中态判定isSelected、区间高亮highlightedRange以及maximumYears/fixedDate的边界约束。组件通过 index.ts 统一导出 9 个子组件所有组件均以YearRangePicker前缀命名便于在 IDE 中自动补全与全局注册。基础用法示例首先引入组件与日期工具类import { CalendarDate } from internationalized/date import { YearRangePickerCell, YearRangePickerCellTrigger, YearRangePickerGrid, YearRangePickerGridBody, YearRangePickerGridRow, YearRangePickerHeader, YearRangePickerHeading, YearRangePickerNext, YearRangePickerPrev, YearRangePickerRoot, } from reka-ui默认选中一个 2020 至 2024 年的区间默认每页显示 12 年按 4 列 × 3 行布局script setup langts const defaultValue { start: new CalendarDate(2020, 1, 1), end: new CalendarDate(2024, 1, 1), } /script template YearRangePickerRoot v-slot{ grid } :default-valuedefaultValue YearRangePickerHeader YearRangePickerPrev‹/YearRangePickerPrev YearRangePickerHeading / YearRangePickerNext›/YearRangePickerNext /YearRangePickerHeader YearRangePickerGrid YearRangePickerGridBody YearRangePickerGridRow v-for(years, index) in grid.rows :keyyear-${index} YearRangePickerCell v-foryear in years :keyyear.toString() :dateyear YearRangePickerCellTrigger :yearyear / /YearRangePickerCell /YearRangePickerGridRow /YearRangePickerGridBody /YearRangePickerGrid /YearRangePickerRoot /template上述结构在官方文档示例中均有完整可运行的实现分别位于 tailwind 版示例 与 css 版示例可直接参考其样式写法。Props 全量解析YearRangePickerRoot 共暴露 23 个 Props。下表为完整清单Name说明类型必填默认值allowNonContiguousRanges与isYearUnavailable配合决定是否允许选择不连续区间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否falseisYearDisabled判断某一年是否被禁用的函数Matcher否-isYearUnavailable判断某一年是否不可用的函数Matcher否-locale用于日期格式化的语言环境string否-maximumYears区间最多可选多少个年份number否-maxValue可选择的最大日期DateValue否-minValue可选择的最小日期DateValue否-modelValue受控的已选年份区间可绑定v-modelDateRange \| null否-nextPage返回下一页下一个年份页的函数(placeholder: DateValue) DateValue否-placeholder占位日期用于在未选择时决定显示哪一页DateValue否-preventDeselect是否阻止用户在未选择新日期前取消选择boolean否falseprevPage返回上一页上一个年份页的函数(placeholder: DateValue) DateValue否-readonly日历是否只读boolean否falseyearsPerPage每页显示的年份数量number否12受控与非受控modelValue、defaultValue 与 placeholdermodelValue是受控值通过v-model双向绑定当存在modelValue时defaultValue不再生效。Root 内部使用useVModel同步并在外部值变化时通过watch自动同步startValue/endValue见 YearRangePickerRoot.vue。defaultValue为非受控初始值类型为DateRange其结构为{ start: DateValue | undefined, end: DateValue | undefined }。placeholder决定当前展示的是哪一页——当用户尚未选择任何年份时以占位日期所在年份对应的页作为展示页选中起始年后placeholder会自动跟随起始年源码中watch(startValue)会同步更新 placeholder。区间约束minValue / maxValue 与 maximumYears / fixedDateminValue/maxValue是绝对日期边界任何超出该范围的年份既不可选中也不会被聚焦键盘导航时shiftFocus会先判断候选年份是否越界见 YearRangePickerCellTrigger.vue。maximumYears限制区间跨度的最大年份数。在 useRangeYearPicker.ts 中可以看到当start与end都确定后超出start ± (maximumYears - 1)范围的年份会被判为禁用当只选中start时focusedValue的预览高亮也会被anchor.add({ years: maximumYears - 1 })封顶避免预览出超长区间。fixedDate与maximumYears配合固定起始年后end只能在start (maximumYears - 1)范围内向后延伸固定结束年则相反。交互上选中完整区间后再次点击时fixedDate决定重开哪个端点详见 CellTrigger 中changeYear的分支逻辑。禁用与不可用isYearDisabled / isYearUnavailableisYearDisabled表示硬禁用禁用年份不可点击、不可聚焦、键盘导航会跳过。isYearUnavailable表示软不可用通常用于表达业务上暂时不可选的年份如尚未发生的未来年度。二者对区间有效性的影响不同若选中的起点或终点命中isYearDisabled区间会被判为isInvalidRoot 会渲染data-invalid属性而isYearUnavailable只影响区间中段——当区间内任意年份不可用时highlightedRange返回null即不可提交该区间除非开启allowNonContiguousRanges。判断逻辑见 useRangeYearPicker.tsareAllYearsBetweenValid(start, end, allowNonContiguousRanges ? () false : isYearUnavailable, rangeIsYearDisabled)。交互行为preventDeselect、allowNonContiguousRanges、readonly、disabledpreventDeselect为true时点击已选中的起点年份不会将其取消必须先选新年份见changeYear中!rootContext.preventDeselect.value的守卫条件。allowNonContiguousRanges开启后即使区间中间存在isYearUnavailable的年份也允许该区间通过预览高亮与选中前提是端点本身有效。readonly只读模式下所有选择操作被拦截changeYear第一步即检查readonly但仍可展示数据disabled则禁用整个交互且视觉上呈现禁用态。渲染控制as / asChild 与 yearsPerPage / nextPage / prevPageas默认渲染为div可通过as覆盖或asChild将根节点替换为任意子元素用于与组件库组合Composition 模式。yearsPerPage控制每页年份数量默认 12网格行数由子组件按 4 列排布得出nextPage/prevPage允许自定义翻页算法例如跳过某些年份段返回值为新的DateValue。无障碍与国际化calendarLabel、locale、dircalendarLabel作为日历整体可访问标签Root 会在渲染时把它写入aria-label同时内部还维护一个视觉隐藏的roleheading标题用于屏幕阅读器朗读当前页见模板中fullCalendarLabel的用法。locale决定年份文本的本地化格式如中文二〇二四年、英文2024未指定时跟随全局ConfigProvider或浏览器默认。dir支持ltr/rtl影响键盘方向键导航的语义RTL 下左右箭头方向翻转见handleArrowKey中sign的计算。事件Emits事件名说明回调参数update:modelValue每当模型值选中区间变化时触发[date: DateRange]update:placeholder每当占位日期变化时触发[date: DateValue]update:startValue每当起始值变化时触发[date: DateValue]update:modelValue由v-model自动监听通常无需手动处理在源码中该事件由内部watch([startValue, endValue])驱动当start/end都确定时会按年份先后自动规整为{ start: 较小年, end: 较大年 }保证区间始终正向有序。update:placeholder用于受控占位日期结合:placeholder.sync可在组件外部控制当前页码。update:startValue是一个便捷事件方便在仅关心区间起点例如级联联动到其他组件时避免解构整个DateRange。交互中途按 ESC 会回滚到上一次合法的modelValueRoot 的keydown监听基于isEditing状态实现避免半成品区间污染受控值。作用域插槽Slots插槽名说明插槽 propsdate当前占位日期DateValuegrid年份网格GridDateValuelocale日历语言环境stringmodelValue当前日期区间DateRange在官方示例中最常用的是grid插槽通过v-slot{ grid }解构出grid.rows外层用v-for渲染YearRangePickerGridRow内层再遍历每行的年份数组渲染YearRangePickerCell。grid.rows的数据结构为二维数组每行包含若干个DateValue其分页与每页行数由yearsPerPage决定。数据属性Data Attributes与键盘交互尽管 Root 自身只渲染data-readonly、data-disabled、data-invalid三个状态属性但其子组件YearRangePickerCellTrigger会依据 Root 上下文输出完整的状态属性用于样式定制见 YearRangePickerCellTrigger.vuedata-selected/data-selection-start/data-selection-end选中态与区间端点data-highlighted/data-highlighted-start/data-highlighted-end悬停预览高亮态配合focusedValuedata-disabled/data-unavailable禁用与不可用态data-today当前年份年份选择器中指今年data-focused当前占位年份同时对应tabindex0的可聚焦项。键盘交互同样由 CellTrigger 完成包括方向键逐格移动、PageUp/PageDown整页翻动、Enter/Space选中、越界自动翻页与跳过禁用项等整套行为与无障碍规范保持一致。Root 提供headingId、fullCalendarLabel等上下文保证屏幕阅读器可朗读当前页标题。完整可运行示例带约束的年份区间筛选器综合以上能力实现一个近十年可选、最长 5 年、禁止未来年度的筛选器script setup langts import { CalendarDate, today, getLocalTimeZone } from internationalized/date const currentYear today(getLocalTimeZone()).year // 禁用未来年份isYearUnavailable 命中未来年度 const isYearUnavailable (date: CalendarDate) date.year currentYear // 硬性边界最早 2010 年 const minValue new CalendarDate(2010, 1, 1) /script template YearRangePickerRoot v-slot{ grid } :min-valueminValue :is-year-unavailableisYearUnavailable :maximum-years5 years-per-page16 localezh-CN YearRangePickerHeader YearRangePickerPrev‹/YearRangePickerPrev YearRangePickerHeading / YearRangePickerNext›/YearRangePickerNext /YearRangePickerHeader YearRangePickerGrid YearRangePickerGridBody YearRangePickerGridRow v-for(years, index) in grid.rows :keyyear-${index} YearRangePickerCell v-foryear in years :keyyear.toString() :dateyear YearRangePickerCellTrigger :yearyear / /YearRangePickerCell /YearRangePickerGridRow /YearRangePickerGridBody /YearRangePickerGrid /YearRangePickerRoot /template该示例中maximum-years5会阻止用户选择跨度超过 5 年的区间is-year-unavailable会让未来年份显示删除线且不可点选minValue则把最早可选年份限制在 2010 年。小结YearRangePickerRoot 是 radix-vue / Reka UI 年份区间选择能力的入口与状态核心通过modelValue/defaultValue管理受控与非受控值通过isYearDisabled/isYearUnavailable/maximumYears/fixedDate/minValue/maxValue组合出精细的可选区间约束再借助grid作用域插槽与 9 个配套子组件完成完整的网格渲染与无障碍键盘交互。掌握其 Props、事件与插槽语义后即可在任意 Vue 3 项目中快速构建专业、可访问的年份范围选择界面。【免费下载链接】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），仅供参考