時間入力

TimeInput コンポーネントは、ラベルと、時間の各単位（例：時間、分、秒）を表すセグメントのグループで構成されています。各セグメントは個別にフォーカス可能で、ユーザーがキーボードで入力したり、矢印キーを使用して値を増減させたりすることで編集できます。このアプローチにより、ロケールや時間形式に関係なく、値を正しくフォーマットおよび解析することができ、キーボードを使用して時間を簡単かつエラーなく編集する方法を提供します。

インストール

npx nextui-cli@latest add date-input

上記のコマンドは、個別のインストール専用です。もし、 @nextui-org/react がグローバルにインストール済みの場合は、このステップをスキップしても構いません。

インポート

使い方

TimeInput は、デフォルトでプレースホルダーを表示します。初期の、非制御の値は、defaultValue prop を使用して TimeField に提供できます。あるいは、value prop を使用して、制御された値を提供することもできます。

時間の値は、@internationalized/date パッケージのオブジェクトを使用して提供されます。このライブラリは、カレンダー、タイムゾーン、その他のローカライズに関する考慮事項全体で、正しい国際日付と時間の操作を処理します。

TimeInput は時間の選択のみをサポートしますが、日付コンポーネントを持つ値も受け入れられます。デフォルトでは、TimeInput は、onChange イベントで Time オブジェクトを排出しますが、CalendarDateTime または ZonedDateTime オブジェクトが value または defaultValue として渡されると、そのタイプの値が排出され、時間のみが変更され、日付コンポーネントは保持されます。

必須

TimeInput は、ユーザーが値を入力することを保証するために、isRequired prop をサポートしており、最小値と最大値、およびカスタムクライアントとサーバー側の検証もサポートします。

無効

isDisabled ブール値 prop は、TimeInput を無効にします。入力はフォーカスしたり選択したりできません。

読み取り専用

isReadOnlyブール値プロパティは、TimeInputの値を不変にします。isDisabledとは異なり、TimeInputはフォーカス可能です。

ラベルなし

TimeInputは、ラベルを表示するかどうかを制御するlabelプロパティをサポートしています。

説明付き

フィールドの説明。選択に関する特定の要件など、ヒントを提供します。

エラーメッセージ付き

isInvalidとerrorMessageプロパティを組み合わせて、無効な入力を表示できます。

関数としてエラーメッセージを渡すこともできます。これにより、ValidationResultに基づいて動的なエラーメッセージ処理が可能になります。

ラベルの配置

ラベル付けする要素に対するラベルの全体的な位置。

開始コンテンツ

時間入力の前にコンテンツを表示する場合は、startContentプロパティを設定できます。

終了コンテンツ

時間入力の後にコンテンツを表示する場合は、endContentプロパティを設定できます。

制御された状態

初期の、制御されていない値をTimeInputにdefaultValueプロパティを使用して渡すことができます。制御された値は、valueプロパティを使用して渡すことができます。

タイムゾーン

TimeInputは、ZonedDateTimeオブジェクトが値として渡されると、タイムゾーンを認識します。この場合、タイムゾーンの略称が表示され、値が操作される際に、夏時間などのタイムゾーンに関する考慮事項が考慮されます。

ほとんどの場合、データはサーバーからISO 8601形式の文字列として送受信されます。@internationalized/dateには、複数の形式の文字列をZonedDateTimeオブジェクトに解析するための関数が含まれています。使用する形式は、保存する必要がある情報によって異なります。

• parseZonedDateTime – この関数は、明示的なタイムゾーンとオプションのUTCオフセットが添付された日付を解析します（例：2021-11-07T00:45[America/Los_Angeles]または2021-11-07T00:45-07:00[America/Los_Angeles]）。この形式は、最大限の情報を保持します。ユーザーが選択した正確な現地時間とタイムゾーンが重要な場合は、この形式を使用します。UTCに変換せずに、選択されたタイムゾーンとオフセットを保存することで、夏時間のルール変更（例：ロケールが夏時間を廃止した場合）に関係なく、現地時間が正確であることが保証されます。これが適用される例としては、カレンダーイベント、リマインダー、および特定の場所で発生するその他の時間が挙げられます。
• parseAbsolute – この関数は、地球上のすべての場所で同じ瞬間に発生する絶対的な日時を解析します。UTCで表現することも（例：2021-11-07T07:45:00Z）、特定のオフセットで保存することもできます（例：2021-11-07T07:45:00-07:00）。タイムゾーン識別子（例：America/Los_Angeles）を渡す必要があり、結果はそのタイムゾーンに変換されます。絶対時間は、過去に発生したイベントや、タイムゾーンに関係なく正確な時間が必要な将来のイベントを表すのに最適な方法です。
• parseAbsoluteToLocal – この関数は、絶対的な日時を現在のユーザーの現地タイムゾーンに解析します。parseAbsoluteのショートカットであり、同じ形式を受け入れます。

粒度

granularity プロパティを使用すると、TimeInput によって表示される最小単位を制御できます。デフォルトでは、時刻は「分」の粒度で表示されます。より細かい時刻値を表示するには、granularity プロパティを "second" に設定します。

最小時刻値

minValue プロパティを使用すると、特定の時刻より前の時刻値を検証できます。

最大時刻値

maxValue プロパティを使用すると、特定の時刻より後の時刻値を検証できます。

プレースホルダー値

値が設定されていない場合、プレースホルダーが表示されます。プレースホルダーの形式は、granularity プロパティと placeholderValue プロパティによって影響を受けます。placeholderValue は、ユーザーが最初に操作したとき（例：上下矢印キーを使用）の各セグメントのデフォルト値も制御します。デフォルトでは、placeholderValue は真夜中ですが、必要に応じてより適切な値に設定できます。

タイムゾーンを非表示

ZonedDateTime オブジェクトが TimeInput の値として提供されると、タイムゾーンの略語がデフォルトで表示されます。ただし、これが別の場所に表示されている場合や、ユースケースに基づいて暗黙的な場合は、hideTimeZone オプションを使用して非表示にできます。

時間サイクル

デフォルトでは、TimeInput はユーザーのロケールに応じて 12 時間形式または 24 時間形式で時刻を表示します。ただし、特定のユースケースで必要な場合は、hourCycle プロパティを使用して上書きできます。この例では、ロケールに関係なく、TimeInput に 24 時間形式を使用するように強制します。

スロット

• base: 入力ラッパー。配置、配置、および一般的な外観を処理します。
• label: 時刻入力のラベル。時刻入力の上、内部、または左に表示されるものです。
• inputWrapper: label （内部にある場合）と innerWrapper をラップします。
• input: 時刻入力要素。
• innerWrapper: セグメント、startContent、および endContent をラップします。
• segment: 入力要素のセグメント。
• helperWrapper: ヘルパーテキストのラッパー。ヘルパーテキストとエラーメッセージをラップします。
• description: 時刻入力の説明。
• errorMessage: 時刻入力のエラーメッセージ。

データ属性

TimeInput には、base 要素に次の属性があります。

• data-has-helper: 時刻入力に説明またはエラーメッセージがある場合。description プロパティまたは errorMessage プロパティに基づきます。
• data-required: 時刻入力が必須の場合。isRequired プロパティに基づきます。
• data-disabled: 時刻入力が無効になっている場合。isDisabled プロパティに基づきます。
• data-readonly: 時刻入力が読み取り専用の場合。isReadOnly プロパティに基づきます。
• data-invalid: 時刻入力が無効な場合。isInvalid プロパティに基づきます。
• data-has-start-content: 時刻入力に開始コンテンツがある場合。startContent プロパティに基づきます。
• data-has-end-content: 時刻入力に終了コンテンツがある場合。endContent プロパティに基づきます。

アクセシビリティ

• ロケール固有の書式設定、数値システム、時間サイクル、および右から左へのレイアウトのサポート。
• 時刻には、オプションでタイムゾーンを含めることができます。すべての変更は、夏時間などのタイムゾーンルールに従います。
• 各時刻単位は、個別にフォーカス可能で編集可能なセグメントとして表示されるため、ユーザーはキーボードを使用して、任意の形式とロケールで時刻を簡単に編集できます。
• 時間セグメントは、使いやすい数値キーパッドを使用して編集でき、すべての操作はタッチベースのスクリーンリーダーを使用してアクセスできます。

API

TimeInputのプロパティ

時間入力イベント