ARTICLE DETAIL

资讯详情

深耕编程入门与网站建设的一线实战洞察。

Element Time Picker 时间选择器完全指南:el-time-picker 与 el-time-select 配置、源码与实战

Element Time Picker 时间选择器完全指南:el-time-picker 与 el-time-select 配置、源码与实战 Element Time Picker 时间选择器完全指南el-time-picker 与 el-time-select 配置、源码与实战【免费下载链接】elementA Vue.js 2.0 UI Toolkit for Web项目地址: https://gitcode.com/gh_mirrors/eleme/element本指南围绕 ElementA Vue.js 2.0 UI Toolkit for Web中的时间选择器展开系统讲解el-time-select固定时间列表与el-time-picker任意时间选择两类组件的全部用法从基础示例、范围选择、picker-options各配置项到属性/事件/方法参考表并结合仓库源码剖析其底层实现原理帮助你在 Vue 2 项目中快速、正确地落地时间输入场景。一、时间选择器概述两种形态各自适用在 Element 中时间输入需求由两个组件分别承担它们的定位完全不同el-time-select提供一份固定、离散的时间列表供用户点选。它适用于预约、班次、营业时段等只能选整点/半点/15 分钟的场景。底层实现在 packages/date-picker/src/panel/time-select.vue由start、end、step三个参数按固定步长生成选项列表。el-time-picker提供连续任意时间的选择能力通过滚动式spinner面板或箭头按键精确定位到时、分、秒并支持is-range范围模式。其面板实现在 packages/date-picker/src/panel/time.vue 与 packages/date-picker/src/panel/time-range.vue。两个组件的入口分别在 packages/time-picker/index.js 与 packages/time-select/index.js且都注册为全局组件ElTimePicker/ElTimeSelect。其中el-time-picker与el-time-select的实现都复用了 packages/date-picker/src/picker.vue 这一通用 Picker 外壳负责 input 渲染、弹层、事件派发面板则通过panel注入二者共享同一套输入与交互骨架。二、固定时间列表el-time-select2.1 基础用法使用el-time-select通过picker-options中的start起始时间、end结束时间、step步长即可生成一份固定时间列表el-time-select v-modelvalue :picker-options{ start: 08:30, step: 00:15, end: 18:30 } placeholderSelect time /el-time-select script export default { data() { return { value: }; } } /script上面的配置会生成从08:30到18:30、每隔 15 分钟一个可选值的列表08:30、08:45、09:00……。2.2 选项生成原理从源码看选项列表是由 packages/date-picker/src/panel/time-select.vue 中的items计算属性生成的computed: { items() { const start this.start; const end this.end; const step this.step; const result []; if (start end step) { let current start; while (compareTime(current, end) 0) { result.push({ value: current, disabled: compareTime(current, this.minTime || -1:-1) 0 || compareTime(current, this.maxTime || 100:100) 0 }); current nextTime(current, step); } } return result; } }其中compareTime将HH:mm解析为分钟数后比较大小nextTime负责在当前时间上叠加step并处理分钟进位next.hours Math.floor(next.minutes / 60); next.minutes next.minutes % 60;。由此可见列表严格从start开始每步累加step直到超过end为止每个选项的disabled状态由minTime/maxTime决定早于minTime或晚于maxTime的选项会被禁用组件在data()中为start、end、step提供了默认值09:00、18:00、00:30见同文件data()定义不传picker-options时也会渲染出默认列表。el-time-select还支持键盘上下键切换选项handleKeydown中监听keyCode 38/40调用scrollDown并会在展开时自动将当前选中项滚动到可视区域handleMenuEnter/scrollToOption。三、任意时间选择el-time-picker3.1 基础用法与可选项范围使用el-time-picker可以选择任意时间精确到秒。通过picker-options.selectableRange可以限制可选的连续时间区间template el-time-picker v-modelvalue1 :picker-options{ selectableRange: 18:30:00 - 20:30:00 } placeholderArbitrary time /el-time-picker el-time-picker arrow-control v-modelvalue2 :picker-options{ selectableRange: 18:30:00 - 20:30:00 } placeholderArbitrary time /el-time-picker /template script export default { data() { return { value1: new Date(2016, 9, 10, 18, 40), value2: new Date(2016, 9, 10, 18, 40) }; } } /scriptselectableRange支持单个区间字符串如18:30:00 - 20:30:00也支持多段区间数组如[09:30:00 - 12:00:00, 14:30:00 - 18:30:00]详见下文picker-options 选项表默认交互是鼠标滚轮滚动选值当设置arrow-control属性后改为上下箭头按键控制按住可连续步进底层使用了repeat-click指令见 src/directives/repeat-click.js。arrow-control仅对el-time-picker生效这一约束在 packages/date-picker/src/picker/time-picker.js 中体现ElTimePicker组件声明了isRange、arrowControl两个 prop并在created()中根据isRange动态选择TimePanel或TimeRangePanel作为面板。3.2 滚轮与箭头两种交互的源码实现滚动模式下el-time-picker的面板由 packages/date-picker/src/basic/time-spinner.vue 渲染为三列时 / 分 / 秒秒列仅在format含ss时出现可滚动列表bindScrollEvent()为时、分、秒三个滚动容器绑定onscrollhandleScroll根据scrollTop反算出当前值并调用modifyDateField更新日期箭头模式下渲染为is-arrow结构上下两个箭头图标通过v-repeat-click反复触发increase/decrease内部最终调用scrollDown(±1)步进并自动跳过被禁用的小时if (hoursList[now]) continue;可选项范围的限制由getRangeHours/getRangeMinutes计算得到见 src/utils/date-util.js例如在某个范围内超出selectableRange的小时/分钟会被标记为disabled点击无效。面板的确认/取消逻辑在 packages/date-picker/src/panel/time.vue 中handleConfirm会对日期调用limitTimeRange做范围钳制后 emitpickhandleCancel则恢复打开面板前的oldValue。四、范围选择固定列表与任意时间4.1 固定列表联动范围el-time-select选择起始时间后通过minTime让结束时间的可选列表自动禁用起始时间之前的所有选项template el-time-select placeholderStart time v-modelstartTime :picker-options{ start: 08:30, step: 00:15, end: 18:30 } /el-time-select el-time-select placeholderEnd time v-modelendTime :picker-options{ start: 08:30, step: 00:15, end: 18:30, minTime: startTime } /el-time-select /template script export default { data() { return { startTime: , endTime: }; } } /script关键在minTime: startTime把起始时间作为结束选择器的minTime则所有早于它的选项都会被标记为disabled见 2.2 节items计算逻辑中的compareTime(current, this.minTime || -1:-1) 0判断从而保证endTime永远不小于startTime。4.2 任意时间范围el-time-picker is-rangeel-time-picker添加is-range属性即可选择开始时间 - 结束时间范围且同样支持arrow-controltemplate el-time-picker is-range v-modelvalue1 range-separatorTo start-placeholderStart time end-placeholderEnd time /el-time-picker el-time-picker is-range arrow-control v-modelvalue2 range-separatorTo start-placeholderStart time end-placeholderEnd time /el-time-picker /template script export default { data() { return { value1: [new Date(2016, 9, 10, 8, 40), new Date(2016, 9, 10, 9, 40)], value2: [new Date(2016, 9, 10, 8, 40), new Date(2016, 9, 10, 9, 40)] }; } } /script范围模式下v-model绑定的值是一个包含两个 Date 的数组。从源码看packages/date-picker/src/picker/time-picker.jsisRange变化时组件会动态卸载并重建面板this.type isRange ? timerange : time; this.panel isRange ? TimeRangePanel : TimePanel;面板 packages/date-picker/src/panel/time-range.vue 渲染开始时间 / 结束时间两个并排 spinner 单元格handleChange会把结束时间动态设置为开始 spinner 的selectableRange上限this.$refs.minSpinner.selectableRange [[minTimeOfDay(this.minDate), this.maxDate]]反之亦然保证范围合法确认按钮的禁用条件为minDate maxDatebtnDisabled计算属性。五、属性参考表Attributes以下属性对el-time-picker与el-time-select通用除特别注明外属性说明类型可选值默认值value / v-model绑定值dateTimePicker/ stringTimeSelect——readonly是否只读boolean—falsedisabled是否禁用boolean—falseeditable是否可编辑输入框boolean—trueclearable是否显示清除按钮boolean—truesize输入框尺寸stringmedium / small / mini—placeholder非范围模式下的占位文本string——start-placeholder范围模式下开始时间的占位文本string——end-placeholder范围模式下结束时间的占位文本string——is-range是否可选择时间范围仅对el-time-picker生效boolean—falsearrow-control是否使用箭头按钮选择时间仅对el-time-picker生效boolean—falsealign对齐方式left / center / right—leftpopper-class时间选择器下拉面板的自定义类名string——picker-options附加选项见下方两张选项表object—{}range-separator范围分隔符string—-default-value可选日历默认日期DateTimePicker/ stringTimeSelectTimePicker 接受任何new Date()可解析的值TimeSelect 接受其列表中可选项的值—value-format可选仅对 Time Picker绑定值的格式不指定时绑定值为 Date 对象string见 date formats—name原生 input 的 namestring——prefix-icon自定义前缀图标类名string—el-icon-timeclear-icon自定义清除图标类名string—el-icon-circle-close补充说明value-format该属性在 packages/date-picker/src/picker.vue 中处理——parseDate/formatDate依赖fecha库见 src/utils/date.js支持的 token 与 DatePicker 一致如yyyy-MM-dd、HH:mm:ss、timestamp等详见 examples/docs/es/date-picker.md 中的date formats一节。不指定时el-time-picker绑定的是Date对象el-time-select绑定的是HH:mm字符串。readonly与editable的联动从 packages/date-picker/src/picker.vue 模板可见输入框的只读条件为!editable || readonly——两者任一为真时用户便无法直接键盘输入只能通过面板选择。六、picker-options 选项表6.1 Time Select 选项属性说明类型可选值默认值start开始时间string—09:00end结束时间string—18:00step步长string—00:30minTime最小时间早于此时间的选项将被禁用string—00:00maxTime最大时间晚于此时间的选项将被禁用string——6.2 Time Picker 选项属性说明类型可选值默认值selectableRange可用的时间范围如18:30:00 - 20:30:00或[09:30:00 - 12:00:00, 14:30:00 - 18:30:00]string / array——format选择器的显示格式string时HH分mm秒ssHH:mm:ss关于format的补充面板是否显示秒列由format是否包含ss决定packages/date-picker/src/panel/time.vue 中的showSeconds()计算属性因此设置formatHH:mm即可隐藏秒列format中含a/A时还会启用 am/pm 上下行模式amPmMode计算属性spinner 中小时会显示AM/PM后缀该行为同时被 test/unit/specs/time-picker.spec.js 中的 am/pm 用例所验证。七、事件与方法7.1 事件事件名说明参数change用户确认值时触发组件绑定值blurinput 失去焦点时触发组件实例focusinput 获得焦点时触发组件实例7.2 方法方法名说明参数focus使 input 获取焦点—八、底层实现要点与测试验证8.1 调用链一览两个组件的完整调用链可以归纳为el-time-select / el-time-picker └─ packages/date-picker/src/picker.vue 输入框、弹层、聚焦/失焦、v-clickoutside └─ paneltime-select.vue / time.vue / time-range.vue └─ basic/time-spinner.vue 滚动列 / 箭头列 └─ src/utils/date-util.js getRangeHours、getRangeMinutes、limitTimeRange 等通用外壳 packages/date-picker/src/picker.vue 定义了DEFAULT_FORMATS其中time: HH:mm:ss、timerange: HH:mm:ss这是时间选择器的默认显示与解析格式时间范围钳制由 src/utils/date-util.js 的limitTimeRange完成若当前值落在某个selectableRange区间内则原样返回否则钳制到最近区间边界并保留原日期的年/月/日timeWithinRange则用于面板中判断选中值是否合法。8.2 测试用例佐证仓库自带的单元测试 test/unit/specs/time-picker.spec.js 覆盖了以下关键行为可作为功能契约参考默认无format情况下秒列可见共三列 spinnerel-time-spinner__wrapper数量为 3设置formatHH:mm后秒列隐藏第 3 个 wrapper 的style.display noneam/pm 模式下首项显示12 AM、次项01 AM第 13 项为12 PM点击面板取消按钮后change不触发、绑定值还原为旧值点击确认按钮后change触发且值为所选时间点击具体的小时选项如第 18 项可以完成选值。九、实践建议离散时刻选值如预约时段、营业时间优先用el-time-select只需配置start/end/step三件套交互最轻量精确到秒或需要自由滚动选值用el-time-picker可通过selectableRange收紧可选区间或用arrow-control切换为箭头步进模式以提升键盘操作精度范围场景el-time-select用minTime联动禁用实现el-time-picker直接加is-range并配合start-placeholder/end-placeholder/range-separator完善 UI 提示数据格式需要提交字符串而非 Date 时给el-time-picker配置value-format如HH:mm:ssel-time-select的绑定值本身即HH:mm字符串无需额外转换。掌握以上配置与原理后你可以根据业务需要在 Element 的 Vue 2 项目中自由组合时间选择器的单值、范围、步进、区间限制与格式输出能力。【免费下载链接】elementA Vue.js 2.0 UI Toolkit for Web项目地址: https://gitcode.com/gh_mirrors/eleme/element创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表