Metro UI CSS 时间选择器（TimePicker）组件完全指南：滚轮式时分秒选择、API 与样式定制

• 前端
• UI组件

Metro UI CSS 的 TimePicker 组件允许用户通过滚轮式（wheel-based）交互界面选择时间值（时、分、秒），并支持自定义步进值（step）与显示格式。本指南以 source/components/timepicker/README.md 为骨架，结合 timepicker.js 源码、timepicker.less 样式定义与 examples/time-picker.html 实例，完整讲解 TimePicker 的依赖关系、HTML 用法、全部插件参数、API 方法、事件回调、全局配置与 CSS 变量定制，帮助你直接上手并把该组件嵌入自己的表单与业务界面。

组件概述与依赖关系

TimePicker 组件通过滚轮式的选择列表（hours / minutes / seconds 三列）让用户快速选取时间，每个部分（时、分、秒）都可以独立显示或隐藏，并且可以自定义步进值，例如小时按 2 步进、分钟按 5 步进。

依据 README 与源码，该组件依赖以下基础库：

• Metro UI Core：组件框架核心，提供Metro.Component、Metro.getPlugin、Metro.timePickerSetup等基础设施；
• Dom library：提供$（Dom）选择器、事件绑定与动画工具（如$.animate、$.each）。

从源码看，TimePicker 还复用了WheelPicker的视觉结构与滚轮交互逻辑（select-block、select-wrapper、action-block等结构均继承自 source/components/wheelpicker/wheelpicker.less）。在 source/components/timepicker/index.js 中可以看到组件的装配方式：

import "../wheelpicker/index.js"; import "./timepicker.js"; import "./timepicker.less";

该 index.js 还会经由 source/components/index.js（import "./timepicker/index.js";）被打包进 Metro UI CSS 的整体发布产物，因此只要在你的页面中引入lib/metro.js与lib/metro.css，即可直接使用data-role="time-picker"，无需额外加载单独文件。

基本用法

TimePicker 的声明方式非常简洁：给<input>元素添加data-role="time-picker"即可自动初始化：

<!-- 基本用法 --> <input><!-- 带标签 --> <input>// 获取插件实例 const timepicker = Metro.getPlugin('#my-timepicker', 'time-picker'); // 获取当前值（字符串） const currentValue = timepicker.val(); // 设置新值（字符串） timepicker.val("14:30:00"); // 获取时间对象 const timeObj = timepicker.time(); // 返回 {h: 14, m: 30, s: 0} // 从对象设置时间 timepicker.time({h: 15, m: 45, s: 30}); // 获取时间（Date 对象） const dateObj = timepicker.date(); // 从 Date 对象设置时间 const date = new Date(); date.setHours(10); date.setMinutes(20); timepicker.date(date); // 打开 / 关闭选择器 timepicker.open(); timepicker.close(); // 启用 / 禁用选择器 timepicker.enable(); timepicker.disable();

注意：date()在获取时会基于当前内部值构造 Date 对象（datetime().hour(...).minute(...).second(...).ms(0)），而设置时会读取 Date 的getHours/getMinutes/getSeconds，与本地时区相关。

此外，组件支持通过changeAttribute响应属性变化（见 timepicker.js）：data-value属性变化时调用val(newValue)更新值，disabled属性变化时调用toggleState()切换状态。disable()/enable()分别给 input 写入data-disabled标记并为其父容器（.time-picker）添加/移除disabled类。

事件回调

事件回调的触发逻辑可以在源码中找到对应位置：_set()中触发set事件并携带{val, elementVal}（timepicker.js）；open()/close()分别触发open/close事件（timepicker.js 与 timepicker.js）；滚动防抖 150ms 后触发onScroll（timepicker.js）。

事件可通过data-on-set等data-*属性声明，也可在Metro.timePickerSetup全局配置中注入函数。

全局配置

与 Metro UI CSS 其他组件一致，TimePicker 支持通过Metro.timePickerSetup进行全局配置（源码见 timepicker.js）：

Metro.timePickerSetup({ hoursStep: 2, minutesStep: 5, seconds: false, showLabels: true });

全局配置会与默认配置深度合并（$.extend({}, TimePickerDefaultConfig, options)），页面中所有 TimePicker 实例都会以此为基底；单实例的data-*属性与局部 options 优先级更高。此外，源码还支持通过全局变量globalThis.metroTimePickerSetup在脚本加载前预置全局配置（见 timepicker.js）：

<script> window.metroTimePickerSetup = { minutesStep: 5, seconds: false }; </script> <script src="../lib/metro.js"></script>

使用 CSS 变量定制样式

TimePicker 的样式由 Less 编译而来（见 timepicker.less），并大量使用 CSS 变量以便于运行时定制。README 列出的相关变量如下：

结合 wheelpicker.less 还可以看到更多可定制变量：--wheel-picker-color（文字颜色，亮色主题#191919，暗色主题#dbdfe7）、--wheel-picker-selected-background（选中项背景，亮色rgba(175,175,175,.5)，暗色rgba(78,81,88,.5)）、--picker-height（默认var(--control-height, 36px)）等。

定制示例（针对某个容器作用域覆盖）：

.my-custom-timepicker { --wheel-picker-border-radius: 8px; --picker-font-size: 1.2rem; --wheel-picker-selected-background: rgba(0, 123, 255, 0.3); }

应用方式：

<input class="my-custom-timepicker"><input class="large pill-input"><!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <link href="../lib/metro.css" rel="stylesheet"> <title>Timepicker - Metro UI CSS</title> </head> <body> <div class="container"> <h1>Timepicker 示例</h1> <div> <input>赞分享