Duration Field
年、月、日、時間、分、秒を含む設定可能な粒度で期間を収集するDuration Field APIフィールドを作成します。
duration_field
インストール
composer require 'drupal/duration_field:8.x-2.2'
composer require 'drupal/duration_field:8.x-2.1'
概要
Duration Fieldモジュールは、Drupalで期間を収集・表示するための包括的なソリューションを提供します。'duration'タイプのForm API要素とField APIフィールドの両方を作成します。durationは設定可能な粒度を持つ期間を表し、年、月、日、時間、分、秒の任意の組み合わせを収集できます。
Duration値は内部的にISO 8601形式の期間文字列（例：P1Y2M3DT4H5M6S）として保存され、時間間隔を表す標準化されたフォーマットを提供します。さらに、データベースでの数学的比較クエリを可能にするため、秒数としても保存されます。
このモジュールは、ユーザーが収集する必要のある時間単位について何も仮定せず、完全な柔軟性を提供します。例えば、勤務シフトの期間には時間と分のみを、契約期間には年と月のみを収集するようにフィールドを設定できます。また、週ベースの計算が必要なユースケース向けにオプションの週フィールドもサポートしています。
Features
- 設定可能な時間単位粒度（年、月、日、時間、分、秒）を持つエンティティ用の'duration'フィールドタイプを提供
- 標準化のためにISO 8601形式で、データベース比較クエリのために秒数として期間を保存
- 3つの表示フォーマッタを提供：Human Friendly（例：'2 years 3 months'）、Duration String（ISO 8601）、Time Format（YY/MM/DD HH:MM:SS）
- 期間入力と粒度設定の両方のためのForm API要素を含む
- 標準のISO 8601期間コンポーネントに加えてオプションの週フィールドをサポート
- データベースクエリでISO 8601文字列を使用して期間を比較するための'duration_string'クエリタグを提供
- 期間フォーマット間の変換、ISO 8601文字列の検証、間隔からの秒数計算のためのサービスを含む
- hook_duration_field_separators()とhook_duration_field_labels()による拡張可能なフォーマッタセパレータ
- すべてのdurationフィールドデータを削除してモジュールのアンインストールを安全に準備するDrushコマンド
- durationフォーム要素でのAJAXと#statesの完全サポート
- 期間入力の設定可能な増分ステップ（例：15分間隔）
- DateIntervalDataノーマライザーによるJSON APIとシリアライゼーションのサポート
Use Cases
従業員の勤務シフト時間
勤務シフトの長さを収集するために、時間と分（h:i）に粒度を設定したdurationフィールドを作成します。Human Friendlyフォーマッタを使用して、従業員スケジュールに'8 hours 30 minutes'のような値を表示します。
レシピの調理時間
時間と分の粒度でRecipeコンテンツタイプにdurationフィールドを追加します。短いテキスト長とカンマセパレータでフォーマッタを設定し、レシピの合計調理時間として'1 hr, 30 min'を表示します。
プロジェクトタイムラインの見積もり
プロジェクト管理用に、週を有効にし、月/週/日の粒度でdurationフィールドを作成します。週フィールドにより、ISO 8601互換性を維持しながら、より自然なプロジェクト計画が可能になります。
ビデオ/オーディオコンテンツの長さ
メディアコンテンツには時間、分、秒の粒度（h:i:s）を使用します。Time Formatフォーマッタは'01:45:30'のような値を表示し、メディア再生時間としてユーザーに馴染みやすい形式です。
サブスクリプション期間の設定
サブスクリプションサービス用に年と月の粒度でdurationフィールドを設定します。ISO 8601文字列保存（例：'P1Y6M'）はプログラム処理のための標準化されたフォーマットを提供します。
データベースクエリを使用したイベント期間
期間でフィルタリングするイベント一覧を作成します。'duration_string'クエリタグを使用して、'PT2H'のようなISO 8601条件を使用して2時間より長いイベントを検索します。これは保存された秒数値と自動的に比較されます。
Tips
- durationフォーム要素の#date_incrementプロパティを使用して、入力を特定の間隔に制限します（例：15分間隔の場合は900、1時間間隔の場合は3600）
- 'duration' Form API要素はカスタムフォームで独立して使用できます - オプションの#granularityと#required_elementsプロパティを持つ'#type' => 'duration'を追加するだけです
- プログラムでのアクセスには、duration_field.serviceを使用してISO 8601文字列、PHP DateIntervalオブジェクト、秒数間を必要に応じて変換します
- 期間をクエリする際は、生の秒数ではなく人間が読みやすいISO 8601値を使用して比較するために、クエリに'duration_string'タグを付けます
- Human Friendlyフォーマッタ用のカスタムセパレータは、モジュールでhook_duration_field_separators()とhook_duration_field_labels()の両方を実装することで追加できます
Technical Details
Hooks 3
hook_duration_field_separators
Human Friendlyフォーマッタで時間値間にカスタムセパレータを追加できるようにします。hook_duration_field_labels()と一緒に実装する必要があります。
hook_duration_field_labels
hook_duration_field_separators()で追加したカスタムセパレータの翻訳されたラベルを提供します。カスタムセパレータを追加する際は実装が必要です。
hook_query_duration_string_alter
ISO 8601文字列を秒数に変換して比較することで、durationフィールドをISO 8601文字列を使用してクエリできるようにする内部フック実装。この動作を有効にするにはクエリに'duration_string'タグを付けます。
Drush Commands 1
drush duration_field:prepare_uninstall
すべてのdurationフィールドデータとフィールド設定を削除してDuration Fieldモジュールのアンインストールを準備します。これは確認プロンプト付きの破壊的な操作です。
Troubleshooting 4
古い'value'カラムから新しい'duration'と'seconds'カラムへの移行を処理し、粒度設定を配列形式から文字列形式に変換するアップデートフック（drush updatedb）を実行してください。
モジュールのアンインストールを試みる前に、Drushコマンド'drush duration_field:prepare_uninstall'（またはエイリアス'drush df-pu'）を使用してすべてのdurationフィールド設定とデータを削除してください。
ISO 8601期間条件を秒ベースの比較に自動変換するために、クエリに'duration_string'タグが付けられていることを確認してください。モジュールは数学的操作に'seconds'カラムを使用します。
フィールド設定で'Include weeks'を有効にしてください。週はISO 8601期間文字列（週をサポートしていない）とは別に保存され、フィールドごとに明示的に有効にする必要があります。