日時範囲ピッカー

Temporal API をベースにした日付/時刻の範囲選択コンポーネント。日付のみ・日付+時刻の両モード、タイムゾーン対応、キーボード入力、柔軟なポップアップ配置をサポートします。

インストール

npm install @dayflow/ui-range-picker

すでに Tailwind CSS を使っている場合は、コンポーネント専用バンドルを読み込んでください。

@import '@dayflow/ui-range-picker/dist/styles.components.css';
@import 'tailwindcss';

Tailwind を使っていない場合は、従来どおり完全なスタイルシートを読み込みます。

import { RangePicker } from '@dayflow/ui-range-picker';
import '@dayflow/ui-range-picker/dist/styles.css';

基本的な使い方

import { useState } from 'react';
import { Temporal } from 'temporal-polyfill';
import { RangePicker } from '@dayflow/ui-range-picker';
import type { ZonedRange } from '@dayflow/ui-range-picker';

function MyComponent() {
  const [range, setRange] = useState<ZonedRange>([
    Temporal.Now.zonedDateTimeISO(),
    Temporal.Now.zonedDateTimeISO().add({ hours: 1 }),
  ]);

  return <RangePicker value={range} onChange={value => setRange(value)} />;
}

日付のみモード

showTime={false} を渡すと時刻セレクターを非表示にできます。

<RangePicker
  value={range}
  showTime={false}
  format='YYYY-MM-DD'
  onChange={value => setRange(value)}
/>

タイムゾーン指定

<RangePicker
  value={range}
  timeZone='Asia/Tokyo'
  onChange={(value, dateStrings) => {
    console.log('範囲:', value);
    console.log('フォーマット済み:', dateStrings); // ['2024-10-15 10:00', '2024-10-15 11:00']
  }}
/>

カスタム時刻フォーマット

<RangePicker
  value={range}
  format='YYYY/MM/DD'
  showTime={{ format: 'HH:mm' }}
  onChange={value => setRange(value)}
  onOk={value => saveToBackend(value)}
/>

ポップアップの配置

ポップアップはデフォルトで左下に表示され、ビューポートからはみ出す場合は自動的に位置を調整します。

<RangePicker
  value={range}
  placement='topRight'
  autoAdjustOverflow={true}
  onChange={value => setRange(value)}
/>

ロケール

BCP 47 のロケールコードを渡すと月名・曜日名がローカライズされます。

<RangePicker value={range} locale='ja-JP' onChange={value => setRange(value)} />

ピッカー自体のラベル（移動ボタン、開始/終了の入力欄、時/分のリスト、OK ボタン）を翻訳するには、messages を持つ locale オブジェクトを渡します。無いキーは英語にフォールバックします。カレンダー内蔵のイベントパネルとダイアログでは、カレンダーのロケールから自動的に設定されます。

<RangePicker
  value={range}
  locale={{
    code: 'ja-JP',
    messages: {
      previousYear: '前年',
      previousMonth: '前月',
      nextMonth: '翌月',
      nextYear: '翌年',
      startDate: '開始日',
      endDate: '終了日',
      hour: '時',
      minute: '分',
      ok: 'OK',
    },
  }}
  onChange={value => setRange(value)}
/>

calendarSystem='jalali' を指定すると、ペルシャ暦で日付を表示・入力できます。onChange と onOk が返す値は引き続き ISO の Temporal 値です。

トリガー幅に合わせる

<RangePicker
  value={range}
  matchTriggerWidth
  onChange={value => setRange(value)}
/>

API リファレンス

`RangePicker`

プロパティ	型	デフォルト	説明
`value`	`[Temporal.PlainDate \| PlainDateTime \| ZonedDateTime, ...]`	—	制御された範囲値。任意の Temporal 型の組み合わせを受け付ける
`format`	`string`	`"YYYY-MM-DD"`	日付部分の表示・パースフォーマット
`showTime`	`boolean \| { format?: string }`	`true`	時刻選択を有効にする。オブジェクトで時刻フォーマットを指定できる
`showTimeFormat`	`string`	`"HH:mm"`	`showTime` が `true` のときのデフォルト時刻フォーマット
`onChange`	`(value: ZonedRange, dateString: [string, string]) => void`	—	選択が変わるたびに発火
`onOk`	`(value: ZonedRange, dateString: [string, string]) => void`	—	ユーザーが OK ボタンで確定したときに発火
`timeZone`	`string`	—	IANA タイムゾーン文字列（例：`"Asia/Tokyo"`）。省略時はシステムタイムゾーン
`disabled`	`boolean`	`false`	すべての操作を無効にする
`placement`	`'bottomLeft' \| 'bottomRight' \| 'topLeft' \| 'topRight'`	`'bottomLeft'`	ポップアップの優先表示位置
`autoAdjustOverflow`	`boolean`	`true`	ビューポートからはみ出す場合にポップアップ位置を自動反転する
`getPopupContainer`	`() => HTMLElement`	—	`document.body` の代わりにカスタムコンテナにポップアップをマウントする
`matchTriggerWidth`	`boolean`	`false`	ポップアップの幅をトリガー入力欄の幅に合わせる
`locale`	`string \| { code: string; messages?: Record<string, string> }`	`'en-US'`	BCP 47 ロケールコード。オブジェクトの `messages` でピッカーのラベルを翻訳
`calendarSystem`	`'gregorian' \| 'jalali'`	`'gregorian'`	日付の表示と解析に使う暦

`ZonedRange`

type ZonedRange = [Temporal.ZonedDateTime, Temporal.ZonedDateTime];

onChange と onOk のコールバックは、入力値の型にかかわらず、常に現在のタイムゾーンに正規化された ZonedRange を返します。

目次