詳細ガイド
Angular Aria

コンボボックス

概要

テキスト入力とポップアップを連携させ、オートコンプリート、セレクト、マルチセレクトのパターンにプリミティブディレクティブを提供するディレクティブです。

使い方

コンボボックスは、テキスト入力とポップアップを連携させるプリミティブディレクティブです。オートコンプリート、セレクト、マルチセレクトパターンの基盤を提供します。次のような場合には、コンボボックスを直接使用することを検討してください：

  • カスタムオートコンプリートパターンの構築 - 特殊なフィルタリングやサジェスチョンの動作を作成する
  • カスタム選択コンポーネントの作成 - 独自の要件を持つドロップダウンを開発する
  • 入力とポップアップの連携 - テキスト入力をリストボックス、ツリー、またはダイアログコンテンツと組み合わせる
  • 特定のフィルターモードの実装 - 手動、自動選択、またはハイライトの動作を使用する

代わりに、次のような場合はドキュメント化されたパターンを使用してください：

  • フィルタリング付きの標準的なオートコンプリートが必要な場合 - すぐに使える例については、Autocompleteパターンを参照してください
  • 単一選択のドロップダウンが必要な場合 - 完全なドロップダウンの実装については、Selectパターンを参照してください
  • 複数選択のドロップダウンが必要な場合 - コンパクトな表示の複数選択については、Multiselectパターンを参照してください

Note: Autocomplete、Select、Multiselectのガイドでは、このディレクティブを特定のユースケースのためにListboxと組み合わせた、ドキュメント化されたパターンが示されています。

機能

Angularのコンボボックスは、完全にアクセシブルな入力とポップアップの連携システムを以下の機能とともに提供します:

  • ポップアップ付きテキスト入力 - 入力フィールドとポップアップコンテンツを連携させます
  • 3つのフィルターモード - 手動、自動選択、またはハイライトの動作
  • キーボードナビゲーション - 矢印キー、Enter、Escapeキーのハンドリング
  • スクリーンリーダーのサポート - role="combobox"やaria-expandedを含む組み込みのARIA属性
  • ポップアップ管理 - ユーザーインタラクションに基づく自動的な表示/非表示
  • シグナルベースのリアクティビティ - Angularシグナルを使用したリアクティブな状態管理

例

オートコンプリート

ユーザーが入力するにつれてオプションをフィルタリングして提案する、アクセシブルな入力フィールドです。リストから値を見つけて選択するのに役立ちます。

filterMode="manual"設定は、フィルタリングと選択を完全に制御します。入力は、オプションリストをフィルタリングするシグナルを更新します。ユーザーは矢印キーで移動し、Enterキーまたはクリックで選択します。このモードは、カスタムフィルタリングロジックに最も柔軟性を提供します。完全なフィルタリングパターンと例については、オートコンプリートガイドを参照してください。

読み取り専用モード

読み取り専用のコンボボックスとリストボックスを組み合わせて、キーボードナビゲーションとスクリーンリーダーをサポートする単一選択のドロップダウンを作成するパターンです。

readonly属性は、入力フィールドへの入力を防ぎます。ポップアップはクリックまたは矢印キーで開きます。ユーザーはキーボードでオプションを移動し、Enterキーかクリックで選択します。

この設定は、SelectおよびMultiselectパターンの基盤を提供します。トリガーとオーバーレイの位置決めを含む完全なドロップダウンの実装については、これらのガイドを参照してください。

ダイアログポップアップ

ポップアップには、背景とフォーカストラップを備えたモーダルな動作が必要な場合があります。コンボボックスダイアログディレクティブは、特殊なユースケースのためにこのパターンを提供します。

ngComboboxDialogディレクティブは、ネイティブのdialog要素を使用してモーダルポップアップを作成します。これにより、背景の動作とフォーカストラップが提供されます。選択インターフェースがモーダルなインタラクションを必要とする場合や、ポップアップのコンテンツがフルスクリーンのフォーカスを必要とするほど複雑な場合に、ダイアログポップアップを使用します。

API

Comboboxディレクティブ

ngComboboxディレクティブは、テキスト入力とポップアップを連携させます。

入力

プロパティ 型 デフォルト 説明
filterMode 'manual' | 'auto-select' | 'highlight' 'manual' 選択の動作を制御します
disabled boolean false コンボボックスを無効にします
readonly boolean false コンボボックスを読み取り専用にします（Select/Multiselect用）
firstMatch V - 自動選択のために、最初に一致した項目の値
alwaysExpanded boolean false ポップアップを常に開いたままにします

フィルターモード:

  • 'manual' - ユーザーがフィルタリングと選択を明示的に制御します。ポップアップには、あなたのフィルタリングロジックに基づいたオプションが表示されます。ユーザーはEnterキーまたはクリックで選択します。このモードは最も柔軟性があります。
  • 'auto-select' - ユーザーが入力すると、入力値は最初に一致したオプションに自動的に更新されます。連携のためにfirstMatch入力が必要です。例についてはオートコンプリートガイドを参照してください。
  • 'highlight' - 入力値を変更せずに、一致するテキストをハイライトします。ユーザーは矢印キーで移動し、Enterキーで選択します。

シグナル

プロパティ 型 説明
expanded Signal<boolean> ポップアップが現在開いているかどうか

メソッド

メソッド パラメータ 説明
open なし コンボボックスを開きます
close なし コンボボックスを閉じます
expand なし コンボボックスを展開します
collapse なし コンボボックスを折りたたみます

ComboboxInputディレクティブ

ngComboboxInputディレクティブは、入力要素をコンボボックスに接続します。

モデル

プロパティ 型 説明
value string [(value)]を使用した双方向バインディング可能な値

入力要素は、キーボード操作とARIA属性を自動的に受け取ります。

ComboboxPopupディレクティブ

ngComboboxPopupディレクティブ（ホストディレクティブ）は、ポップアップの可視性と連携を管理します。通常、ng-template内のngComboboxPopupContainerまたはCDK Overlayと一緒に使用されます。

ComboboxPopupContainerディレクティブ

ngComboboxPopupContainerディレクティブは、ng-templateをポップアップのコンテンツとしてマークします。

<ng-template ngComboboxPopupContainer>  <div ngListbox>...</div></ng-template>

Popover APIまたはCDK Overlayと一緒に使用して、位置決めします。

ComboboxDialogディレクティブ

ngComboboxDialogディレクティブは、モーダルなコンボボックスポップアップを作成します。

<dialog ngComboboxDialog>  <div ngListbox>...</div></dialog>

背景とフォーカストラップを備えたモーダルポップアップの動作に使用します。

Comboboxは、これらのドキュメント化されたパターンのためのプリミティブディレクティブです:

  • オートコンプリート - フィルタリングと提案のパターン（フィルターモード付きのComboboxを使用）
  • セレクト - 単一選択のドロップダウンパターン（readonly付きのComboboxを使用）
  • マルチセレクト - 複数選択のパターン（readonly + 複数選択が有効なListbox付きのComboboxを使用）

Comboboxは通常、以下と組み合わせて使用されます:

  • Listbox - 最も一般的なポップアップコンテンツ
  • Tree - 階層的なポップアップコンテンツ（例についてはTreeガイドを参照）