timepicker-ui-mcp

timepicker-ui

Web フォーム用のタイムピッカーです。<input> に適用すると、ユーザーは時計盤またはスクロールホイールで時刻を選択できます。

ライブデモ · ドキュメント · 変更履歴 · React ラッパー

timepicker-ui を選ぶ理由

• 依存関係はありません。
• コアは gzip 圧縮後で約 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、...）
• インラインモード（独自のダイアログに埋め込むバリエーションあり）、クリアボタン、モバイルレイアウト
• プラグインによる時間範囲（連動または独立した開始／終了）とタイムゾーン
• 関数を使って時刻を選択不可に設定できます（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.mobile ではなく ui.initialView にするなど、多くのオプションの名前がより分かりやすいものに変更され、update() に代わる setOptions() が追加されます。旧名称は 5.0 まで引き続き使用できます。オプションのページには、すべての新旧名称が記載されています。既存の設定に影響する変更もいくつかあります。値の AM/PM 部分は、labels.am ／ labels.pm の内容にかかわらず、常に AM ／ PM になります。25:00 のように範囲外の clock.disabledTime.ranges の端点はエラーとして報告されます。旧 .tp-ui-ripple クラスは削除され、一部のフォーカスリングと角丸のトークンが変更されます。CHANGELOG の「アップグレード前に確認」の項をご覧ください。

4.3 からは、破壊的な変更はありません。4.4 では、blueprint と blueprint-dark テーマ、スクリーンリーダー用テキストの新しい labels.* 16 個、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 に準拠し、サーバーサイドレンダリング時にも安全にインポートでき、同じテーマ名を使用するため、2 つのピッカーのデザインが揃います。単一の日付、範囲、複数の日付に対応しています。

npm install @pglejzer/datepicker-ui

日付と時刻のガイドでは、1 つのフォームで両方のピッカーを使う方法を説明しています。

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 ゲッター 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 にするとインラインモードでも表示されます
  • behavior.commitOnChange は ui.inline.autoUpdate と wheel.commitOnScroll に置き換わります。選択された値は入力欄に書き込まれ、confirm が発行されます。ピッカーは開いたままになります
  • wheel.ignoreOutsideClick は behavior.ignoreOutsideClick に移動し、クロックモーダルを含むすべてのモードで機能します
  • 分のアナウンスには labels.minute が使用されるため、デフォルト値が Minutes から Minute に変わります
  • ui.cssClass は、2 つではなく 1 つの要素に適用されます
• パッケージと CSS：
  • プラグインには UMD ビルドが含まれなくなります（UMD コアでは PluginRegistry が公開されていなかったため、<script> タグからプラグインを登録できませんでした）。コアの UMD ビルドは引き続き提供されます
  • どのルールからも参照されない CSS カスタムプロパティが約 50 個削除されます。たとえば、--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