timepicker-ui-mcp

timepicker-ui

适用于网页表单的时间选择器。将它附加到 <input>，用户即可在表盘或滚动轮上选择时间。

在线演示 · 文档 · 更新日志 · React 封装

为什么选择 timepicker-ui

• 零依赖。
• 核心部分压缩后约为 27 KB。范围插件约为 5 KB，时区插件约为 3 KB，滚轮插件约为 10 KB；只有导入的插件才会打包（打包统计）。
• 提供时钟、滚轮或紧凑滚轮（输入框下方的小型下拉菜单）。
• 提供原生 JS API，因此无论在 React、Vue、Angular、Svelte 中使用，还是不依赖框架，都能以相同方式工作。
• 导入时不会操作 window 或 document，因此可安全用于 Next.js、Nuxt 和其他 SSR 环境。
• 支持键盘和屏幕阅读器。所有文本（包括屏幕阅读器使用的文本）都可以通过 labels 翻译。

功能

• 12 小时制 / 24 小时制、小时和分钟步进、禁用时间
• 可选的秒数（HH:MM:SS），适用于时钟、滚轮和紧凑滚轮
• 12 种主题（Material 2/3、Crane、Dark、Cyberpunk、Blueprint 等）
• 内联模式（包含可嵌入自定义对话框的变体）、清除按钮、移动端布局
• 通过插件支持时间范围（关联或独立的 From/To）和时区
• 使用函数禁用时间（clock.isTimeDisabled）
• 附带 TypeScript 类型定义

安装

npm install timepicker-ui

快速开始

<input id="timepicker" type="text" />

import { TimepickerUI } from "timepicker-ui";
import "timepicker-ui/main.css";

const input = document.querySelector("#timepicker");
const picker = new TimepickerUI(input, {
  clock: { type: "24h" },
  ui: { theme: "dark" },
  callbacks: {
    onConfirm: (data) => console.log("Selected:", data),
  },
});
picker.create();

无需全局 CSS 重置：选择器会为自身元素设置 box-sizing: border-box（详情）。

API

picker.create();               // render the picker and attach it to the input
picker.open();
picker.close();
picker.destroy();
picker.getValue();             // { hour, minutes, seconds, type, time }, seconds only with clock.showSeconds
picker.setValue("14:30");      // "2:30 PM" works too
picker.setValue("14:30:15");   // with clock.showSeconds
picker.setOptions({ ui: { theme: "crane" } });
picker.setRange({ from: "09:00", to: "17:00" });  // needs RangePlugin
picker.getRange();
picker.setActivePart("to");
picker.refreshDisabledTime();  // after the data behind clock.isTimeDisabled changes

const off = picker.on("confirm", (data) => {});  // on() and once() return a function that removes the handler
off();
picker.on("confirm", (data) => {});
picker.on("cancel", (data) => {});
picker.on("open", () => {});
picker.on("update", (data) => {});
picker.on("clear", (data) => {});
picker.on("error", (data) => {});
picker.once("confirm", handler);
picker.off("confirm", handler);

TimepickerUI.getById("my-id");
TimepickerUI.getAllInstances();
TimepickerUI.isAvailable("#timepicker");
TimepickerUI.destroyAll();

文档：方法、事件

选项

按类别分组。只传入所需选项，其余选项均有默认值（完整列表）。

new TimepickerUI(input, {
  clock: {
    type: "12h" | "24h" | "auto", // default "12h"; "auto" follows the browser locale
    incrementHours: 1,
    incrementMinutes: 1,
    showSeconds: false,         // true adds seconds (HH:MM:SS)
    incrementSeconds: 1,
    disabledTime: { hours: [], minutes: [], seconds: [], ranges: "" },
    isTimeDisabled: ({ hour, minutes, seconds }) => false,  // hour is 0-23
    defaultTime: "now" | { time, updateInput },
  },
  ui: {
    theme: "basic" | "dark" | "m3-green" | "crane" | "blueprint" | ...,
    mode: "clock" | "wheel" | "compact-wheel",   // default "clock"
    animation: true,
    backdrop: true,
    initialView: "clock",       // or "keyboard"
    editable: false,
    inline: { enabled: false, container: "#picker" | element, showButtons: false, autoUpdate: false, embedded: false },
    clearButton: false,         // or { clearInput: false } to keep the input value on Clear
    cssClass: "",
  },
  labels: { am, pm, ok, cancel, clear, clockTitle, hour, minute, second, rangeFrom, rangeTo, timezone, ... },
  behavior: { focusTrap: true, returnFocus: false, delayHandler: 0, id: "" },
  callbacks: { onConfirm, onCancel, onOpen, onUpdate, onSelectHour, onSelectMinute, onSelectSecond, onSelectPeriod, onClear, onError, ... },
  wheel: { placement: "auto" | "top" | "bottom", hideFooter: false, commitOnScroll: false, hideDisabled: false, ignoreOutsideClick: false },
  range: { enabled: false, linked: true, minDuration, maxDuration },
  timezone: { enabled: false, default, list },
});

主题

预览所有主题：basic、crane、crane-straight、m3-green、m2、dark、glassmorphic、pastel、ai、cyberpunk、blueprint、blueprint-dark。

main.css 是必需文件，且已包含 basic。其余主题为独立文件：

import "timepicker-ui/main.css";
import "timepicker-ui/theme-dark.css";

new TimepickerUI(input, { ui: { theme: "dark" } });

或者导入 timepicker-ui/index.css 以获取所有主题。编写自定义主题：样式指南。

插件

Range、timezone 和 wheel 以独立模块的形式提供。创建选择器前，请先注册一次。使用 wheel 和 compact-wheel 模式时，需要 WheelPlugin。

import { TimepickerUI, PluginRegistry } from "timepicker-ui";
import { RangePlugin } from "timepicker-ui/plugins/range";
import { TimezonePlugin } from "timepicker-ui/plugins/timezone";
import { WheelPlugin } from "timepicker-ui/plugins/wheel";

PluginRegistry.register(RangePlugin);
PluginRegistry.register(TimezonePlugin);
PluginRegistry.register(WheelPlugin);

new TimepickerUI(input, { range: { enabled: true } });

升级

从 4.5 升级不会有任何破坏性变更。4.6 新增了 ui.inline.embedded、range.linked、clock.isTimeDisabled 和 refreshDisabledTime()，以及 setRange() / getRange() / setActivePart() 方法，并为 on() / once() 返回移除函数。详情请参阅 CHANGELOG。

从 4.4 升级时，4.5 新增了可选秒数（clock.showSeconds），并修复了许多错误。此外，它还将许多选项重命名为更清晰的名称，例如用 ui.initialView 替代 ui.mobile，并新增了 setOptions()，用于替代 update()。旧名称会继续有效，直到 5.0，选项页面列出了所有名称对应关系。有几项变更可能会影响现有配置：无论 labels.am / labels.pm 的值是什么，值中的 AM/PM 部分始终为 AM / PM；超出范围的 clock.disabledTime.ranges 边界（例如 25:00）会报错；旧的 .tp-ui-ripple 类已移除；部分焦点环和圆角 token 已更改。CHANGELOG 中的 "Check before upgrading" 一节列出了这些变更。

从 4.3 升级不会有任何破坏性变更。4.4 新增了 blueprint 和 blueprint-dark 主题、16 个用于屏幕阅读器文本的新 labels.*，以及 Home/End/PageUp/PageDown 键。详情请参阅 CHANGELOG。

从 3.x 升级时，选项现在按类别分组（clock、ui、labels 等），事件通过 picker.on() 处理，CSS 类名也已更改。请参阅迁移指南。

从 2.x 升级时，必须自行导入 CSS，部分事件名称也已更改（旧版迁移指南）。

框架

React：

import { useEffect, useRef } from "react";
import { TimepickerUI } from "timepicker-ui";
import "timepicker-ui/main.css";

function TimePicker() {
  const ref = useRef<HTMLInputElement>(null);
  useEffect(() => {
    if (!ref.current) return;
    const picker = new TimepickerUI(ref.current);
    picker.create();
    return () => picker.destroy();
  }, []);
  return <input ref={ref} />;
}

此外还有一个 React 封装（文档）。Vue 和 Angular 示例见快速入门文档。

需要日期选择器？

datepicker-ui 是同一作者开发的配套日历。它没有依赖项，遵循 Material Design 3，可安全地在服务器渲染期间导入，并使用相同的主题名称，因此两个选择器的样式相匹配。它支持单个日期、日期范围和多个日期。

npm install @pglejzer/datepicker-ui

日期和时间指南介绍了如何在同一表单中同时使用这两个选择器。

5.0 计划

5.0.0 已列入计划，但尚未确定发布日期。4.5.0 为此做了准备。计划中的变更：

• 插件的构建和注册方式将会改变。PluginRegistry.register(...) 以及导出的插件类型（PluginRegistry、Plugin、PluginManager、PluginFactory、TemplateProvider、ClearHandler、CoreState、EventEmitter）都将变更。内置的 range、timezone 和 wheel 插件将保留。5.0 将随附迁移指南。
• CSS 类名仍保留 tp-ui- 前缀，但前缀后的部分将重新设计，以遵循 Material Design 组件命名规范。针对这些类名的自定义 CSS 需要更新。5.0 将附上新旧名称对照表。
• 4.5.0 中重命名的选项将不再支持旧名称，例如 ui.mobile（现为 ui.initialView）和 clock.smoothHourSnap（现为 clock.discreteHourJump）。选项页面列出了所有名称对。select:am / select:pm 事件也将移除（请改用 select:period），update() 也将移除（请改用 setOptions()）。
• behavior.returnFocus 默认值将变为 true：关闭时，焦点会返回输入框，或返回打开选择器的 data-open 元素。现在即可设置 behavior.returnFocus: true，让焦点返回输入框。
• 不再需要的代码将被移除，包括已弃用项目的向后兼容代码路径和死代码。这会减小核心和各插件的包体积及加载开销。目前尚未设定体积目标。4.5.0 已移除不会影响公共 API 或标记的内部死代码。5.0 将与下列项目一并移除其余代码。
• 4.5.0 中弃用的项目将被移除：
  • OptionTypes（请改用 TimepickerOptions）
  • clock.currentTime.locales
  • getValue().degreesHours 和 getValue().degreesMinutes
  • labels.toggleLabel、labels.format24Label、labels.timezoneSelectorLabel
  • 旧版 focusInputAfterCloseModal 选项（请改用 behavior.returnFocus）
  • hide 事件和 HideEventData（从未触发）
  • range:get-disabled-time 和 range:update-disabled 事件（从未触发）
  • ErrorEventData.rejectedHour 和 ErrorEventData.rejectedMinute（始终为 undefined）
• 以下项目也将被移除，因为它们不起作用或容易引起误解：
  • 公共 TimepickerEventMap 中的内部事件（range:minute:commit、animation:*）及其兜底索引签名，因此 on('typo') 将成为类型错误
  • behavior.delayHandler（它只会延迟关闭，不会对按钮进行防抖）
  • TimepickerUI.isAvailable()（与 document.querySelector(...) !== null 等效）
  • 未记录的 DOM getter：hour、minutes、okButton、cancelButton、clockHand
  • open(cb) 的回调参数，以及两种形式的 destroy() 回调参数：destroy(cb) 和 destroy({ callback })（请使用 once('open')，或在调用后运行代码）
  • 从插件入口点导出的 RangeManager、TimezoneManager 和 WheelManager（目前无法获取其实例，且新的插件 API 将取代它们）
• 变更的事件和选项：
  • 在任何模式下，选择对应单位的值时，select:hour、select:minute 和 select:second 都只触发一次。目前在时钟模式下，它们会在字段激活时触发，因此选择小时会触发 select:minute。要跟踪表盘切换，请使用 4.5.0 已经会触发的 switch:face
  • ui.footer 将取代 ui.inline.showButtons 和 wheel.hideFooter：设为 false 时，会在所有模式下隐藏 OK、Cancel 和 Clear；设为 true 时，也会在 inline 模式下显示它们
  • behavior.commitOnChange 将取代 ui.inline.autoUpdate 和 wheel.commitOnScroll：每次选择的值都会写入输入框并触发 confirm，且选择器保持打开
  • wheel.ignoreOutsideClick 将移至 behavior.ignoreOutsideClick，并在所有模式下生效，包括时钟模态框
  • 分钟提示将读取 labels.minute，因此其默认值会从 Minutes 变为 Minute
  • ui.cssClass 将只应用于一个元素，而不是两个
• 包和 CSS：
  • 插件将不再附带 UMD 构建版本（UMD 核心从未公开 PluginRegistry，因此无法通过 <script> 标签注册插件）。核心 UMD 构建版本将保留
  • 大约 50 个没有被任何规则读取的 CSS 自定义属性将被移除，例如 --tp-tertiary-container、--tp-on-tertiary-container、--tp-radius、--tp-hover-bg，以及 34 个 --tp-size-* 标记中的 18 个。5.0 将列出全部属性
  • package.json 的 exports 中将移除 ./plugins/* 通配符，但 ./plugins/range、./plugins/timezone 和 ./plugins/wheel 将保留
  • crane-straight 将成为 crane 的一个方角变体（选项名称尚未确定）
  • ui.keyboardIcon / ui.clockIcon 将接收元素或工厂函数，而不是 HTML 字符串 详情请参阅路线图。

开发

请参阅app/README.md。

参与贡献

欢迎在 GitHub 提交问题和 PR。

许可证

MIT © Piotr Glejzer