Element Plus TimePicker 时间选择器完全指南从基础用法到 API 全解析【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus时间选择器TimePicker是 Element Plus 组件库中用于时间输入的交互组件本文基于官方文档 docs/en-US/component/time-picker.md 并结合仓库源码系统讲解任意时间选择、时间范围限制、区间选择三大核心场景以及 Attributes、Events、Exposes 的完整 API 说明与底层实现原理。阅读完本文你将能够熟练配置disabled-hours/minutes/seconds、arrow-control、is-range等关键属性理解format与value-format的作用边界并掌握在 Vue 3 项目中直接落地的完整示例代码。基础用法任意时间选择TimePicker 最基础的形态是选择一个任意时刻只需引入el-time-picker组件并通过v-model绑定值即可。以下示例来自仓库文档示例 docs/examples/time-picker/basic.vuetemplate div classexample-basic el-time-picker v-modelvalue1 placeholderArbitrary time / el-time-picker v-modelvalue2 arrow-control placeholderArbitrary time / /div /template script langts setup import { ref } from vue const value1 ref() const value2 ref() /script从源码结构看ElTimePicker组件packages/components/time-picker/src/time-picker.tsx内部由三层协作构成外层Pickercommon/picker.vue负责输入框、下拉浮层popper与焦点管理等公共逻辑面板组件TimePickPaneltime-picker-com/panel-time-pick.vue负责单值模式的时间面板核心滚动列表BasicTimeSpinnertime-picker-com/basic-time-spinner.vue渲染时、分、秒三个可滚动列。默认情况下用户可以在面板中滚动鼠标滚轮来快速切换时分秒。当设置了arrow-control属性后面板会切换为箭头按钮模式每个时间列上下各出现一个箭头图标按住可连续增减数值更适合触屏或对鼠标滚轮不友好的场景。这一分支逻辑在basic-time-spinner.vue中以v-if!arrowControl和v-ifarrowControl两个模板分支实现箭头模式还复用了element-plus/directives提供的v-repeat-click指令来支持长按连发。限制时间范围禁用不可选的时间点如果业务要求只能选择某个时间段内的时刻可以通过disabled-hours、disabled-minutes、disabled-seconds三个函数属性来精确禁用小时、分钟、秒。以下示例来自 docs/examples/time-picker/basic-range.vue它把可选项限制在 17:30 到 18:30 之间template div classexample-basic el-time-picker v-modelvalue1 :disabled-hoursdisabledHours :disabled-minutesdisabledMinutes :disabled-secondsdisabledSeconds placeholderArbitrary time / /div /template script langts setup import { ref } from vue const value1 ref(new Date(2016, 9, 10, 18, 30)) const makeRange (start: number, end: number) { const result: number[] [] for (let i start; i end; i) { result.push(i) } return result } const disabledHours () { return makeRange(0, 16).concat(makeRange(19, 23)) } const disabledMinutes (hour: number) { if (hour 17) { return makeRange(0, 29) } if (hour 18) { return makeRange(31, 59) } return [] } const disabledSeconds (hour: number, minute: number) { if (hour 18 minute 30) { return makeRange(1, 59) } return [] } /script三个函数的签名与调用约定如下类型定义见 common/props.ts 与 props/shared.ts属性签名返回说明disabledHours(role: string, comparingDate?: Dayjs) number[]被禁用的小时数组role在区间模式中为start/end用于区分起始/结束面板disabledMinutes(hour: number, role: string, comparingDate?: Dayjs) number[]被禁用的分钟数组根据当前选中的小时动态决定禁用的分钟disabledSeconds(hour: number, minute: number, role: string, comparingDate?: Dayjs) number[]被禁用的秒数组根据小时和分钟组合动态决定禁用的秒从实现上看basic-time-spinner.vue通过getTimeLists定义于 composables/use-time-picker.ts将这些函数转化为每一列的可选项列表被禁用的选项会加上is-disabledclass 且点击无效。上例的效果是17:30 之后、18:30 之前的时间可选其余时刻的时分秒均被置灰。提示在区间模式中comparingDate参数还会携带当前正在比较的对面端点日期可据此实现结束时间不能早于开始时间这类联动限制。区间选择任意时间范围通过is-range属性可以让 TimePicker 切换为区间模式一次选择起止两个时间点输入框会显示为起始时间 - 结束时间的双输入形态。以下示例来自 docs/examples/time-picker/range.vuetemplate div classdemo-range el-time-picker v-modelvalue1 is-range range-separatorTo start-placeholderStart time end-placeholderEnd time / el-time-picker v-modelvalue2 is-range arrow-control range-separatorTo start-placeholderStart time end-placeholderEnd time / /div /template script langts setup import { ref } from vue const value1 ref[Date, Date]([ new Date(2016, 9, 10, 8, 40), new Date(2016, 9, 10, 9, 40), ]) const value2 ref[Date, Date]([ new Date(2016, 9, 10, 8, 40), new Date(2016, 9, 10, 9, 40), ]) /script区间模式下的几个关键点v-model绑定的值必须是长度为 2 的数组例如[Date, Date]、[number, number]或[string, string]分别对应绑定值为 Date 对象、时间戳、格式化字符串三种形态range-separator自定义两个输入框之间的分隔符默认是-start-placeholder与end-placeholder分别设置起始框和结束框的占位文本arrow-control同样支持区间模式。在源码中is-range决定了两件事见 time-picker.tsx内部 type 标记为timerange面板组件切换为TimeRangePaneltime-picker-com/panel-time-range.vue区间触发输入框则由 common/picker-range-trigger.vue 渲染。Attributes 属性总览以下属性表完整继承自官方文档并补充了取值范围说明。除非特别标注版本属性在当前版本中均可用名称说明类型默认值model-value/v-model绑定值若为数组则长度应为 2number/string/Date/[Date, Date]/[number, number]/[string, string]readonly是否只读booleanfalsedisabled是否禁用booleanfalseeditable输入框是否可编辑booleantrueclearable是否显示清除按钮booleantruesize输入框尺寸large \| default \| small—placeholder非区间模式的占位文本stringstart-placeholder区间模式起始框占位文本string—end-placeholder区间模式结束框占位文本string—is-range是否选择时间区间booleanfalsearrow-control是否使用箭头按钮选择时间booleanfalsepopper-class下拉浮层自定义类名stringpopper-style下拉浮层自定义样式string/object—popper-options自定义 popper 配置项基于 Popper.js 的PartialPopperOptionsobject{}fallback-placements2.8.4浮层兜底位置列表Placement[][bottom, top, right, left]placement2.8.4浮层弹出位置Placementbottomrange-separator区间分隔符string-format输入框中显示值的格式参见 date-formatsstring—default-value日历默认日期可选Date/[Date, Date]—value-format绑定值的格式不指定时绑定值为 Date 对象参见 date-formatsstring—id原生 input 的idstring/[string, string]—name原生 input 的namestringaria-labela11y2.7.2原生 input 的aria-labelstring—prefix-icon自定义前缀图标组件string/ComponentClockclear-icon自定义清除图标组件string/ComponentCircleClosedisabled-hours指定不可选的小时数组(role: string, comparingDate?: Dayjs) number[]—disabled-minutes指定不可选的分钟数组(hour: number, role: string, comparingDate?: Dayjs) number[]—disabled-seconds指定不可选的秒数组(hour: number, minute: number, role: string, comparingDate?: Dayjs) number[]—teleported下拉浮层是否传送teleport到 bodybooleantruetabindex输入框 tabindexstring/number0empty-values2.7.0组件的空值集合参见 config-provider 空值配置array—value-on-clear2.7.0清空时的返回值参见 config-provider 空值配置string/number/boolean/Function—save-on-blur2.13.4聚焦时若未选择值失焦是否自动填入当前时间booleantruelabela11y已废弃原生 input 的aria-label已被aria-label取代string—其中几个值得深入说明的属性format与value-format的区别。format只影响输入框的显示文本value-format才决定v-model绑定值的数据形态。默认展示格式为HH:mm:ss常量定义于 constants.ts由DEFAULT_FORMATS_TIME提供。若设置了value-format如HH:mm:ss绑定值将变为字符串若不设置绑定值为Date对象。格式化与解析分别通过formatter与parseDate完成二者位于 utils.ts底层依赖 dayjs 的customParseFormat插件在 time-picker.tsx 中显式dayjs.extend(customParseFormat)。popper-options/popper-class/popper-style/placement/fallback-placements。这些属性共同控制下拉浮层的行为与外观。popperOptions在 time-picker.tsx 中通过provide(PICKER_POPPER_OPTIONS_INJECTION_KEY, props.popperOptions)注入到 Popper 体系placement与fallbackPlacements定义于 common/props.ts其合法值取自 Popper.js 的placements枚举。注意浮层相关链接指向外部文档本文不展开具体行为以 Popper.js 官方规范为准。empty-values与value-on-clear。这两个 2.7.0 新增属性与全局 ConfigProvider 的空值策略联动用于统一哪些值算空值以及清空后回填什么值适用于全项目需要统一空值语义的场景。save-on-blur。2.13.4 新增默认true。它控制一个细节行为聚焦时间面板但未做任何选择时失焦后输入框是否自动填入当前系统时间。若设为false失焦后输入框保持为空。Events 事件名称说明类型change用户确认值时触发(val: number \| string \| Date \| [number, number] \| [string, string] \| [Date, Date]) voidblur输入框失焦时触发(e: FocusEvent) voidfocus输入框聚焦时触发(e: FocusEvent) voidclear2.7.7可清除的 TimePicker 中点击清除图标时触发() voidvisible-change下拉浮层出现/消失时触发(visibility: boolean) voidchange事件的值形态与value-format设置强相关不设置value-format时回调中收到的是Date对象区间模式为[Date, Date]设置后则是格式化字符串或时间戳。visible-change常用于在面板展开/收起时联动其他 UI 逻辑例如收起后同步外部统计或重置状态。Exposes 暴露的方法TimePicker 通过模板引用template ref暴露以下方法可在父组件中通过ref获取组件实例后调用名称说明类型focus聚焦 TimePicker 组件() voidblur使 TimePicker 组件失焦() voidhandleOpen2.2.16打开 TimePicker 浮层() voidhandleClose2.2.16关闭 TimePicker 浮层() void这四个方法在 time-picker.tsx 中通过ctx.expose暴露内部全部委托给公共Picker实例commonPicker的同名方法。典型用法示例template el-time-picker refpickerRef v-modelvalue / el-button clickpickerRef?.handleOpen()打开时间面板/el-button /template script langts setup import { ref } from vue import type { TimePickerInstance } from element-plus const pickerRef refTimePickerInstance() const value ref() /script源码结构解读TimePicker 的分层设计结合前文各部分TimePicker 在仓库中的完整结构如下packages/components/time-pickersrc/ ├── common/ # 公共逻辑 │ ├── picker.vue # 输入框 浮层 焦点管理 │ ├── picker-range-trigger.vue # 区间模式双输入触发框 │ └── props.ts # 组件全部默认属性定义 ├── composables/ # 组合式函数 │ ├── use-common-picker.ts # 公共 picker 逻辑 │ ├── use-time-panel.ts # 面板联动逻辑 │ └── use-time-picker.ts # 时/分/秒禁用列表计算 ├── props/ # 分块属性定义 │ ├── basic-time-spinner.ts │ ├── panel-time-picker.ts │ ├── panel-time-range.ts │ └── shared.ts # disabledTimeListsProps 等共享属性 ├── time-picker-com/ # 面板组件 │ ├── basic-time-spinner.vue # 时/分/秒滚动列核心 │ ├── panel-time-pick.vue # 单值面板 │ └── panel-time-range.vue # 区间面板 ├── constants.ts # 默认格式、注入 key 等常量 ├── time-picker.tsx # ElTimePicker 主组件 └── utils.ts # 格式化/解析/日期比较工具值得注意的设计细节禁用列表的链式计算disabledMinutes接收disabledHours的选中结果disabledSeconds再接收前两者的结果逐级收敛可选范围最终由getTimeLists汇总为三个列的禁用状态数组。滚动与箭头双模式复用同一数据源basic-time-spinner.vue中滚动模式使用el-scrollbar渲染完整列表并支持滚轮箭头模式则通过buildTimeListutils.ts只渲染当前值的前一个/当前/后一个三个候选值配合v-repeat-click实现按住连加连减。属性驱动的组件组合主组件ElTimePicker只做根据is-range选择面板组件这一件事其余全部逻辑下沉到公共Picker这也解释了为何is-range可以在属性表中单独成行而面板切换对用户完全透明。测试保障仓库在 packages/components/time-picker/tests/time-picker.test.tsx 中对该组件的绑定、禁用、区间、事件等行为有完整的单元测试覆盖可作为自定义扩展时的行为参照。总结Element Plus 的 TimePicker 以任意时间选择 → 时间范围限制 → 区间选择三个层次覆盖了绝大多数时间输入场景基础用法配合arrow-control应对滚轮与按钮两种交互习惯disabled-hours/minutes/seconds提供逐级精确的可选区间控制is-range一键切换为起止时间双输入。配合format/value-format控制显示与绑定形态、save-on-blur、empty-values等精细属性以及focus/handleOpen等暴露方法足以支撑表单校验、预约时段、排班配置等各类实战需求。【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考