Element Plus TimeSelect 时间选择器完全指南从固定时间点到联动时间范围【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plusTimeSelect 是 Element PlusVue.js 3 UI Library中用于「时间输入」的轻量级组件它不像 TimePicker 那样提供自由输入与滚动面板而是基于start、end、step三个参数自动生成一张固定时间选项列表让用户只能从预设的离散时间点中选择适用于预约、排班、时段筛选等对时间精度有严格约束的场景。本文将以 Element Plus 官方文档 time-select.md 为主线结合仓库内 示例代码 与 组件源码完整讲解固定时间选择、时间格式定制、联动时间范围、全部 Attributes/Events/Exposes API以及底层的选项生成与校验原理。TimeSelect 是什么TimeSelect 提供的是「从固定时间列表里点选」的交互方式。官方文档明确指出其可用时间范围是 00:00 到 23:59。使用场景上它通常用于需要限制用户只能选择整点、半点、每 15 分钟等固定间隔的时间表单中「开始时间 / 结束时间」的联动约束与日期无关、只关心当天时刻的轻量场景。与 TimePicker 相比TimeSelect 不依赖自由滚动的时间面板而是等价于一个「选项由时间规则自动生成的下拉选择框」。从源码看time-select.vue 内部就是基于el-select与el-option组合实现的它把按规则生成的每个时间点渲染为一个el-option从而天然继承了 Select 的过滤、清除、禁用、Popper 主题等能力。固定时间选择Fixed time picker最基础的用法是给用户展示一个固定的时间列表。核心是三个属性属性作用默认值start起始时间09:00end结束时间18:00step时间步长间隔00:30以下为官方文档示例 basic.vue 的完整代码template el-time-select v-modelvalue stylewidth: 240px start08:30 step00:15 end18:30 placeholderSelect time / /template script langts setup import { ref } from vue const value ref() /script这里从08:30开始每隔15分钟一个选项直到18:30因此下拉列表会依次出现08:30、08:45、09:00……18:30。三个属性都以HH:mm形式的字符串传入且step必须能被start到end的区间整除否则最后一个时间点可能落不到end上。选项生成逻辑的源码细节选项列表并不是硬编码的而是由 time-select.vue 中的items计算属性动态生成的核心算法如下let current start.value while (compareTime(current, end.value) 0) { const currentTime dayjs(current, HH:mm) .locale(lang.value) .format(props.format) push(currentTime, current) current nextTime(current, step.value) }从start开始只要当前时间 end就持续推入选项通过nextTime定义在 utils.ts在分钟数上累加step并自动处理分钟满 60 进位到小时每个选项的label与value都使用props.format格式化后的字符串。此外源码中还实现了非法参数回退getValidTimeOrDefault会先用parseTime解析start/end/step若格式非法或step为 00:00会通过debugWarn在控制台给出invalid xxx, fallback to default xxx的警告并回退到默认值见 time-select.ts 中的DEFAULT_START 09:00、DEFAULT_END 18:00、DEFAULT_STEP 00:30。从源码结构看parseTime还支持AM/PM后缀解析例如08:30 PM会被换算为 20:30因此使用 12 小时制format时start、end、min-time、max-time传入带AM/PM的时间字符串也是可以被正确比较的。时间格式定制Time Formats默认情况下时间以HH:mm24 小时制如14:30显示。通过format属性可以控制选项的展示格式例如改成 12 小时制带上下行标记template el-time-select v-modelvalue stylewidth: 240px start00:00 step00:30 end23:59 placeholderSelect time formathh:mm A / /template script langts setup import { ref } from vue const value ref() /script这是官方文档示例 time-formats.vue 的完整代码。format的取值遵循 Day.js 的格式化令牌token体系常用写法包括令牌含义示例HH24 小时制00–2314hh12 小时制01–1202mm分钟00–5930A/aAM / PM大写 / 小写PM/pm官方文档特别给出了一个:::warning提示Pay attention to capitalization——务必注意大小写。HH与hh、A与a代表完全不同的含义写错会导致展示格式错误。在源码层面format的默认值为HH:mm见 time-select.ts 中format: { type: String, default: HH:mm }组件内部通过dayjs的customParseFormat插件来解析和格式化时间见 time-select.vue 顶部的dayjs.extend(customParseFormat)。格式化时还使用了当前语言环境的 localelocale(lang.value)因此在不同lang配置下本地化格式输出会随之变化。注意format只影响展示层的 label 与绑定值格式start、end、step、min-time、max-time这些配置属性在内部统一按HH:mm解析为「小时 分钟」结构进行数值比较见 utils.ts 的parseTime/compareTime。固定时间范围联动Fixed time range当需要「开始时间 结束时间」两个选择器联动时使用min-time与max-time来动态禁用超出范围的选项template div classdemo-time-range flex flex-wrap gap-4 el-time-select v-modelstartTime stylewidth: 240px :max-timeendTime placeholderStart time start08:30 step00:15 end18:30 / el-time-select v-modelendTime stylewidth: 240px :min-timestartTime placeholderEnd time start08:30 step00:15 end18:30 / /div /template script langts setup import { ref } from vue const startTime ref() const endTime ref() /script这是官方文档示例 time-range.vue 的完整代码。联动规则为「开始时间」选择器的max-time绑定endTime一旦结束时间被选中晚于它的所有开始时间选项会被禁用「结束时间」选择器的min-time绑定startTime一旦开始时间被选中早于它的所有结束时间选项会被禁用。官方文档对这段行为的描述是If start (end) time is picked at first, then the status of end (start) times options will change accordingly——先选任何一侧另一侧的选项状态都会随之联动变化。禁用选项的判定源码在 time-select.vue 的items计算属性中每个选项的disabled判定如下disabled: compareTime(rawValue, minTime.value || -1:-1) 0 || compareTime(rawValue, maxTime.value || 100:100) 0,当未设置min-time时用-1:-1兜底任何合法时间都大于它因此不会误禁用当未设置max-time时用100:100兜底任何合法时间都小于它同样不会误禁用compareTime把时间换算成「总分钟数」再比较规则直观可靠见 utils.ts。min-time/max-time的默认值为null不限制。仓库测试 time-select.test.tsx 中专门覆盖了这两个场景set minTime用例断言minTime14:30时14:30选项带.is-disabled类set maxTime用例断言maxTime14:30时同理验证了禁用逻辑的行为。完整 API 参考Attributes以下为官方文档 time-select.md 中 Attributes 表的完整内容带版本标记的属性为后续版本新增当前仓库均已实现对应声明见 time-select.ts名称说明类型默认值model-value / v-model绑定值^[string]—disabled是否禁用 TimeSelect^[boolean]falseeditable输入框是否可编辑可输入过滤^[boolean]trueclearable是否显示清除按钮^[boolean]trueinclude-end-time ^(2.9.3)是否将end作为选项包含进来^[boolean]falsesize输入框尺寸^[enum]large \| default \| smalldefaultplaceholder非范围模式下的占位提示^[string]—name ^(2.13.3)等同于原生 input 的name属性^[string]—effectTooltip 主题内置dark/light^[string] / ^[enum]dark \| lightlightprefix-icon自定义前缀图标组件^[string] / ^[Component]Clockclear-icon自定义清除图标组件^[string] / ^[Component]CircleClosestart开始时间^[string]09:00end结束时间^[string]18:00step时间步长^[string]00:30min-time最小时间早于它的选项会被禁用^[string]—max-time最大时间晚于它的选项会被禁用^[string]—format时间展示格式^[string]见 Day.js formatsHH:mmempty-values ^(2.7.0)组件的空值集合见 config-provider 的 empty-values 配置^[array]—value-on-clear ^(2.7.0)点击清除后返回的值见 config-provider 的 empty-values 配置^[string] / ^[number] / ^[boolean] / ^[Function]—popper-class ^(2.11.4)TimeSelect 下拉面板的自定义类名^[string]popper-style ^(2.11.4)TimeSelect 下拉面板的自定义样式^[string] / ^[object]—几个值得注意的实现细节editable与过滤源码中:filterableeditable即editable为true时下拉框可输入过滤基于default-first-option快速选中第一个匹配项为false时只能点选无法输入。disabled与表单联动源码通过useFormDisabled()接入 Form 的禁用上下文因此放在el-form/el-form-item中时表单级禁用会自动生效无需逐组件配置。empty-values/value-on-clear来自useEmptyValuesProps配合 config-provider 全局配置使用用于定义哪些值视为「空」以及清空后的回填值。include-end-time默认false时若end恰好落在步长序列上它本来就会作为最后一个选项出现设为true则保证即使end不在步长序列上也会被强制追加为一个选项见 time-select.vue 中props.includeEndTime的分支处理。Events名称说明类型change用户确认值时触发^[Function](value: string) voidblur输入框失焦时触发^[Function](event: FocusEvent) voidfocus输入框聚焦时触发^[Function](event: FocusEvent) voidclear ^(2.7.7)可清除的 TimeSelect 点击清除图标时触发^[Function]() void源码层面组件内部声明了defineEmits([CHANGE_EVENT, blur, focus, clear, UPDATE_MODEL_EVENT])并在渲染el-select时将内部事件逐层转发见 time-select.vue。仓库测试中也有用例验证modelValue08:30且clearable时聚焦后会出现CircleClose清除图标点击即可清空值。Exposes组件实例方法方法说明类型focus聚焦 Input 组件^[Function]() voidblur使 Input 组件失焦^[Function]() void通过模板 ref 获取组件实例后可调用例如template el-time-select reftimeSelectRef v-modelvalue / /template script langts setup import { ref } from vue const timeSelectRef ref() const value ref() // 在需要时聚焦/失焦 const handleFocus () timeSelectRef.value?.focus() const handleBlur () timeSelectRef.value?.blur() /script源码中这两个方法通过select.value?.focus?.()与select.value?.blur?.()委托给内部el-select实现并通过defineExpose对外暴露见 time-select.vue。底层实现速览TimeSelect 是 Element Plus 组件体系中「组合复用」的典型它本身不实现下拉逻辑而是完全基于el-selectel-option构建见 index.ts 中的withInstall(TimeSelect)注册方式核心职责只有两个生成选项由start/end/step经 utils.ts 的parseTime、nextTime、compareTime、formatTime等纯函数生成离散时间序列约束选项由min-time/max-time计算每个选项的disabled状态实现范围联动。由于复用了 Select 组件TimeSelect 自动获得过滤、清除、尺寸、Tooltip 主题effect、Popper 样式popper-class/popper-style以及 Form 禁用上下文等能力这也是它代码量小但功能完整的原因。相关测试集中在 time-select.test.tsx覆盖了默认值回显、min/max 禁用、清除按钮、事件触发等关键行为可作为理解组件行为的参考。小结基础用法只需startendstep三个字符串属性即可生成固定时间下拉列表format控制展示格式注意HH/hh、A/a的大小写差异底层统一按 24 小时制数值比较双选择器联动通过min-time/max-time绑定对方值实现先选哪一侧另一侧都会自动禁用越界选项完整 API 覆盖 Attributes含include-end-time、name、popper-class、popper-style、empty-values等新特性、Eventschange/blur/focus/clear与 Exposesfocus/blur想深入理解行为边界可结合 组件源码、类型与默认值定义、时间工具函数 与 单元测试 一起阅读。【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Element Plus TimeSelect 时间选择器完全指南：从固定时间点到联动时间范围
Element Plus TimeSelect 时间选择器完全指南从固定时间点到联动时间范围【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plusTimeSelect 是 Element PlusVue.js 3 UI Library中用于「时间输入」的轻量级组件它不像 TimePicker 那样提供自由输入与滚动面板而是基于start、end、step三个参数自动生成一张固定时间选项列表让用户只能从预设的离散时间点中选择适用于预约、排班、时段筛选等对时间精度有严格约束的场景。本文将以 Element Plus 官方文档 time-select.md 为主线结合仓库内 示例代码 与 组件源码完整讲解固定时间选择、时间格式定制、联动时间范围、全部 Attributes/Events/Exposes API以及底层的选项生成与校验原理。TimeSelect 是什么TimeSelect 提供的是「从固定时间列表里点选」的交互方式。官方文档明确指出其可用时间范围是 00:00 到 23:59。使用场景上它通常用于需要限制用户只能选择整点、半点、每 15 分钟等固定间隔的时间表单中「开始时间 / 结束时间」的联动约束与日期无关、只关心当天时刻的轻量场景。与 TimePicker 相比TimeSelect 不依赖自由滚动的时间面板而是等价于一个「选项由时间规则自动生成的下拉选择框」。从源码看time-select.vue 内部就是基于el-select与el-option组合实现的它把按规则生成的每个时间点渲染为一个el-option从而天然继承了 Select 的过滤、清除、禁用、Popper 主题等能力。固定时间选择Fixed time picker最基础的用法是给用户展示一个固定的时间列表。核心是三个属性属性作用默认值start起始时间09:00end结束时间18:00step时间步长间隔00:30以下为官方文档示例 basic.vue 的完整代码template el-time-select v-modelvalue stylewidth: 240px start08:30 step00:15 end18:30 placeholderSelect time / /template script langts setup import { ref } from vue const value ref() /script这里从08:30开始每隔15分钟一个选项直到18:30因此下拉列表会依次出现08:30、08:45、09:00……18:30。三个属性都以HH:mm形式的字符串传入且step必须能被start到end的区间整除否则最后一个时间点可能落不到end上。选项生成逻辑的源码细节选项列表并不是硬编码的而是由 time-select.vue 中的items计算属性动态生成的核心算法如下let current start.value while (compareTime(current, end.value) 0) { const currentTime dayjs(current, HH:mm) .locale(lang.value) .format(props.format) push(currentTime, current) current nextTime(current, step.value) }从start开始只要当前时间 end就持续推入选项通过nextTime定义在 utils.ts在分钟数上累加step并自动处理分钟满 60 进位到小时每个选项的label与value都使用props.format格式化后的字符串。此外源码中还实现了非法参数回退getValidTimeOrDefault会先用parseTime解析start/end/step若格式非法或step为 00:00会通过debugWarn在控制台给出invalid xxx, fallback to default xxx的警告并回退到默认值见 time-select.ts 中的DEFAULT_START 09:00、DEFAULT_END 18:00、DEFAULT_STEP 00:30。从源码结构看parseTime还支持AM/PM后缀解析例如08:30 PM会被换算为 20:30因此使用 12 小时制format时start、end、min-time、max-time传入带AM/PM的时间字符串也是可以被正确比较的。时间格式定制Time Formats默认情况下时间以HH:mm24 小时制如14:30显示。通过format属性可以控制选项的展示格式例如改成 12 小时制带上下行标记template el-time-select v-modelvalue stylewidth: 240px start00:00 step00:30 end23:59 placeholderSelect time formathh:mm A / /template script langts setup import { ref } from vue const value ref() /script这是官方文档示例 time-formats.vue 的完整代码。format的取值遵循 Day.js 的格式化令牌token体系常用写法包括令牌含义示例HH24 小时制00–2314hh12 小时制01–1202mm分钟00–5930A/aAM / PM大写 / 小写PM/pm官方文档特别给出了一个:::warning提示Pay attention to capitalization——务必注意大小写。HH与hh、A与a代表完全不同的含义写错会导致展示格式错误。在源码层面format的默认值为HH:mm见 time-select.ts 中format: { type: String, default: HH:mm }组件内部通过dayjs的customParseFormat插件来解析和格式化时间见 time-select.vue 顶部的dayjs.extend(customParseFormat)。格式化时还使用了当前语言环境的 localelocale(lang.value)因此在不同lang配置下本地化格式输出会随之变化。注意format只影响展示层的 label 与绑定值格式start、end、step、min-time、max-time这些配置属性在内部统一按HH:mm解析为「小时 分钟」结构进行数值比较见 utils.ts 的parseTime/compareTime。固定时间范围联动Fixed time range当需要「开始时间 结束时间」两个选择器联动时使用min-time与max-time来动态禁用超出范围的选项template div classdemo-time-range flex flex-wrap gap-4 el-time-select v-modelstartTime stylewidth: 240px :max-timeendTime placeholderStart time start08:30 step00:15 end18:30 / el-time-select v-modelendTime stylewidth: 240px :min-timestartTime placeholderEnd time start08:30 step00:15 end18:30 / /div /template script langts setup import { ref } from vue const startTime ref() const endTime ref() /script这是官方文档示例 time-range.vue 的完整代码。联动规则为「开始时间」选择器的max-time绑定endTime一旦结束时间被选中晚于它的所有开始时间选项会被禁用「结束时间」选择器的min-time绑定startTime一旦开始时间被选中早于它的所有结束时间选项会被禁用。官方文档对这段行为的描述是If start (end) time is picked at first, then the status of end (start) times options will change accordingly——先选任何一侧另一侧的选项状态都会随之联动变化。禁用选项的判定源码在 time-select.vue 的items计算属性中每个选项的disabled判定如下disabled: compareTime(rawValue, minTime.value || -1:-1) 0 || compareTime(rawValue, maxTime.value || 100:100) 0,当未设置min-time时用-1:-1兜底任何合法时间都大于它因此不会误禁用当未设置max-time时用100:100兜底任何合法时间都小于它同样不会误禁用compareTime把时间换算成「总分钟数」再比较规则直观可靠见 utils.ts。min-time/max-time的默认值为null不限制。仓库测试 time-select.test.tsx 中专门覆盖了这两个场景set minTime用例断言minTime14:30时14:30选项带.is-disabled类set maxTime用例断言maxTime14:30时同理验证了禁用逻辑的行为。完整 API 参考Attributes以下为官方文档 time-select.md 中 Attributes 表的完整内容带版本标记的属性为后续版本新增当前仓库均已实现对应声明见 time-select.ts名称说明类型默认值model-value / v-model绑定值^[string]—disabled是否禁用 TimeSelect^[boolean]falseeditable输入框是否可编辑可输入过滤^[boolean]trueclearable是否显示清除按钮^[boolean]trueinclude-end-time ^(2.9.3)是否将end作为选项包含进来^[boolean]falsesize输入框尺寸^[enum]large \| default \| smalldefaultplaceholder非范围模式下的占位提示^[string]—name ^(2.13.3)等同于原生 input 的name属性^[string]—effectTooltip 主题内置dark/light^[string] / ^[enum]dark \| lightlightprefix-icon自定义前缀图标组件^[string] / ^[Component]Clockclear-icon自定义清除图标组件^[string] / ^[Component]CircleClosestart开始时间^[string]09:00end结束时间^[string]18:00step时间步长^[string]00:30min-time最小时间早于它的选项会被禁用^[string]—max-time最大时间晚于它的选项会被禁用^[string]—format时间展示格式^[string]见 Day.js formatsHH:mmempty-values ^(2.7.0)组件的空值集合见 config-provider 的 empty-values 配置^[array]—value-on-clear ^(2.7.0)点击清除后返回的值见 config-provider 的 empty-values 配置^[string] / ^[number] / ^[boolean] / ^[Function]—popper-class ^(2.11.4)TimeSelect 下拉面板的自定义类名^[string]popper-style ^(2.11.4)TimeSelect 下拉面板的自定义样式^[string] / ^[object]—几个值得注意的实现细节editable与过滤源码中:filterableeditable即editable为true时下拉框可输入过滤基于default-first-option快速选中第一个匹配项为false时只能点选无法输入。disabled与表单联动源码通过useFormDisabled()接入 Form 的禁用上下文因此放在el-form/el-form-item中时表单级禁用会自动生效无需逐组件配置。empty-values/value-on-clear来自useEmptyValuesProps配合 config-provider 全局配置使用用于定义哪些值视为「空」以及清空后的回填值。include-end-time默认false时若end恰好落在步长序列上它本来就会作为最后一个选项出现设为true则保证即使end不在步长序列上也会被强制追加为一个选项见 time-select.vue 中props.includeEndTime的分支处理。Events名称说明类型change用户确认值时触发^[Function](value: string) voidblur输入框失焦时触发^[Function](event: FocusEvent) voidfocus输入框聚焦时触发^[Function](event: FocusEvent) voidclear ^(2.7.7)可清除的 TimeSelect 点击清除图标时触发^[Function]() void源码层面组件内部声明了defineEmits([CHANGE_EVENT, blur, focus, clear, UPDATE_MODEL_EVENT])并在渲染el-select时将内部事件逐层转发见 time-select.vue。仓库测试中也有用例验证modelValue08:30且clearable时聚焦后会出现CircleClose清除图标点击即可清空值。Exposes组件实例方法方法说明类型focus聚焦 Input 组件^[Function]() voidblur使 Input 组件失焦^[Function]() void通过模板 ref 获取组件实例后可调用例如template el-time-select reftimeSelectRef v-modelvalue / /template script langts setup import { ref } from vue const timeSelectRef ref() const value ref() // 在需要时聚焦/失焦 const handleFocus () timeSelectRef.value?.focus() const handleBlur () timeSelectRef.value?.blur() /script源码中这两个方法通过select.value?.focus?.()与select.value?.blur?.()委托给内部el-select实现并通过defineExpose对外暴露见 time-select.vue。底层实现速览TimeSelect 是 Element Plus 组件体系中「组合复用」的典型它本身不实现下拉逻辑而是完全基于el-selectel-option构建见 index.ts 中的withInstall(TimeSelect)注册方式核心职责只有两个生成选项由start/end/step经 utils.ts 的parseTime、nextTime、compareTime、formatTime等纯函数生成离散时间序列约束选项由min-time/max-time计算每个选项的disabled状态实现范围联动。由于复用了 Select 组件TimeSelect 自动获得过滤、清除、尺寸、Tooltip 主题effect、Popper 样式popper-class/popper-style以及 Form 禁用上下文等能力这也是它代码量小但功能完整的原因。相关测试集中在 time-select.test.tsx覆盖了默认值回显、min/max 禁用、清除按钮、事件触发等关键行为可作为理解组件行为的参考。小结基础用法只需startendstep三个字符串属性即可生成固定时间下拉列表format控制展示格式注意HH/hh、A/a的大小写差异底层统一按 24 小时制数值比较双选择器联动通过min-time/max-time绑定对方值实现先选哪一侧另一侧都会自动禁用越界选项完整 API 覆盖 Attributes含include-end-time、name、popper-class、popper-style、empty-values等新特性、Eventschange/blur/focus/clear与 Exposesfocus/blur想深入理解行为边界可结合 组件源码、类型与默认值定义、时间工具函数 与 单元测试 一起阅读。【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考