Radix Vue Date Field 组件全解析构建可访问、支持本地化的分段式日期输入框【免费下载链接】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现 reka-ui组件库中 Date Field 组件DateFieldRoot/DateFieldInput的完整技术指南。Date Field 将日期输入拆分为年、月、日乃至时分秒、上午/下午等多个可独立聚焦与编辑的分段segment支持完整键盘导航、受控/非受控双模式、多种地区locale与日历体系Gregorian、Japanese、Persian、Buddhist 等并原生提供 ARIA 语义。阅读完本文你将掌握该组件的安装方式、组件结构Anatomy、全部 API 与 data 属性以及其分段编辑与键盘交互的底层实现原理。功能特性Features官方文档为 Date Field 定义了以下核心能力详见 date-field.md完整键盘导航Full keyboard navigationTab 进入、方向键在分段间移动、上下键增减数值全程无需鼠标可受控亦可非受控Controlled or uncontrolled既可通过v-model受控绑定也可只传defaultValue让组件内部管理状态焦点完全托管Focus is fully managed组件内部维护当前聚焦的分段并在输入完成、数值溢出时自动推进焦点本地化支持Localization support通过locale属性切换显示格式并支持 RTL 阅读方向高度可组合Highly composableRoot 提供默认插槽数据segments等由开发者自行渲染每个分段默认可访问Accessible by default每个分段自动获得rolespinbutton及aria-valuemin/max/now/text等属性同时支持日期与日期时间格式Date and date-time formats由granularity控制渲染到天 / 小时 / 分钟 / 秒哪一级精度。前置依赖internationalized/dateDate Field 依赖 Adobe React Spectrum 团队的internationalized/date包。该包解决了 JavaScript 原生Date在处理时区、日历体系、日期运算上的大量历史问题——例如它提供了CalendarDate、CalendarDateTime、ZonedDateTime等不可变日期值类型以及跨历法Gregorian、Japanese、Persian、Buddhist、Islamic 等的日期转换能力。官方文档强烈建议先通读该包的文档理解DateValue类型体系后再使用本组件库中的日期相关组件。从源码看DateFieldRoot.vue顶部直接引入该包的DateValue类型useDateField.ts位于 useDateField.ts则基于internationalized/date的DateFormatter、DateValue.set/cycle等 API 实现分段值的增减与格式化这也是组件内部分段运算的正确性基石。安装需要安装两个包日期基础包所有日期相关组件的前置依赖pnpm add internationalized/date组件库本体pnpm add reka-ui若你使用 npm 或 yarn将pnpm add替换为对应的npm install/yarn add即可。组件的导入路径统一为reka-ui参见文档 Anatomy 示例与 docs 组件示例。组件结构AnatomyDate Field 由两个部分组合而成DateFieldRoot容器持有全部状态与上下文与DateFieldInput单个分段通过part属性声明渲染哪种分段。最小可用结构script setup import { DateFieldInput, DateFieldRoot, } from reka-ui /script template DateFieldRoot DateFieldInput / /DateFieldRoot /template在实际项目中通常利用 Root 的默认插槽数据segments遍历渲染所有分段。官方文档 demo见 docs/components/demo/DateField/tailwind/index.vue给出了完整写法script setup langts import { DateFieldInput, DateFieldRoot, Label } from reka-ui /script template div classflex flex-col gap-2 Label classtext-sm text-stone-700 dark:text-white forbirthday Birthday /Label DateFieldRoot idbirthday v-slot{ segments } :is-date-unavailabledate date.day 19 classw-36 flex select-none bg-white items-center rounded-lg shadow-sm text-center text-green10 border p-1>DateFieldRoot defaultValue2024-01-01 !-- segments 渲染略 -- /DateFieldRoot受控配合v-modelscript setup langts import { ref } from vue import type { DateValue } from internationalized/date import { getLocalTimeZone, today } from internationalized/date const value refDateValue(today(getLocalTimeZone())) /script template DateFieldRoot v-modelvalue !-- segments 渲染略 -- /DateFieldRoot /templatemodelValue的类型是DateValue即CalendarDate/CalendarDateTime/ZonedDateTime的联合因此建议直接使用internationalized/date提供的值构造与工具函数如today()、parseDate()而非原生Date对象。实战粒度、本地化与无效日期仓库的 Story 文件提供了丰富的可验证示例目录 packages/core/src/DateField/story1. 粒度控制GranularityDateFieldGranular.story.vue展示了granularityday | hour | minute | second四种形态——精度越高渲染的分段越多如second会包含 时:分:秒 及 AM/PM 段适合出生日期day、会议时间minute等不同业务场景。2. 本地化LocalesDateFieldLocales.story.vue通过设置locale属性展示了 Gregorian默认、Japaneseja、Persianfa-IR、台湾zh-TW、Hebrewhe、Buddhistth六种历法/地区下分段顺序与分隔符的差异。这一点得益于底层internationalized/date的多历法支持组件渲染分段时按 locale 的格式模板createContent生成段序列与 literal 分隔符。3. 无效日期InvalidDateFieldInvalid.story.vue展示了:is-date-unavailabledate date.day 19配合插槽isInvalid输出错误提示文案的用法——当用户输入 19 日时Root 计算出的isInvalid为true分段与容器都会带上data-invalid属性可据此渲染红色边框或错误消息。可访问性与键盘交互AccessibilityDate Field 的键盘交互遵循官方的无障碍设计完整交互表如下见 date-field.md按键行为Tab焦点进入日期字段时聚焦第一个分段ArrowLeft/ArrowRight在日期字段的分段之间导航ArrowUp/ArrowDown递增/改变当前分段的值0-9当焦点位于数字分段时输入数字若下一次输入将导致无效值则自动聚焦下一分段Backspace删除聚焦的数字分段中的一位数字A/P焦点位于上午/下午段时将其设置为 AM 或 PM这些行为的源码级印证见 useDateField.ts分段导航DateFieldRoot的handleKeydown处理左右方向键依据dir方向计算下一个/上一个可聚焦分段RTL 下方向反转并额外检查e.isComposing以兼容 IME 输入法组合状态见 DateFieldRoot.vue数字输入与自动推进updateDayOrMonth、updateMinuteOrSecond、updateHour、updateYear实现了连击数字逻辑——例如日段先输入3再输入1会合并为31若输入9大于该段最大起始位则立即提交并推进到下一分段focusNext()负责推进焦点上下键增减dateTimeValueIncrementation与minuteSecondIncrementation通过DateValue.cycle实现循环增减秒/分在 059 之间循环小时在 12/24 制边界内循环且日段增减会按当月天数吸附边界例如 1 月 31 日加一天自动进位为 2 月 1 日源码中对day分段做了月份未填时默认按 31 天计算的边界处理Backspace 删除deleteValue删除末位数字删除到空时清空字段值AM/PM 快捷键handleDayPeriodSegmentKeydown响应a/p含大写同时换算内部 24 小时制小时值方向键则切换 AM/PM 并同步 ±12 小时。总结Date Field 是 Radix Vue 日期组件族Calendar、DatePicker、DateRangePicker、MonthPicker 等的基础单元其分段编辑 上下文共享 ARIA spinbutton的模式贯穿整套日期体系。落地使用时的三个要点一是务必安装并理解internationalized/date的值模型二是善用 Root 插槽的segments与isInvalid数据自定义视觉呈现三是依赖data-placeholder、data-invalid、data-disabled、data-readonly属性实现无脚本的样式状态管理。深入研读 DateFieldRoot.vue、DateFieldInput.vue 与 useDateField.ts可帮助你基于该模式扩展出符合自己业务需求的日期输入控件。【免费下载链接】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），仅供参考