GPUI Deck

Dropdown Menu

通常、チェック/混在/ラジオ、ネストしたサブメニューのセマンティクス、ナビゲーション、リーフのディスパッチ、閉じる動作、フォーカスに対応します。

GPUI の Web バックエンドが描画する実際のコンポーネントです。WebGPU 対応のブラウザが必要です。

長いメニューはウィンドウの高さに収まります。矢印キー、Home、End、文字検索で移動すると、選ばれたコマンドまでスクロールします。ContextMenu、Menubar 内のメニュー、サブメニューも同様です。

DropdownMenu と ContextMenu は MenuState、MenuItem、MenuEvent、 MenuOption を共有します。共有されるコマンドの動作は、開閉状態、 閉じる動作、フォーカス移動、フォーカスの復元に Popover を再利用します。固定された順序付きの MenuItem::new(value, label) エントリで MenuState::new(items, cx) を作成します。値は一意でなければなりません。利用できないコマンドには .disabled(true) を使用します。空のコレクションやすべてが無効なコレクションは 開けますが、コマンドを実行できません。

DropdownMenu::new(id, &state) を次のように描画します。

  • .trigger(|button| ...) で、ネイティブのトリガーのアクセシブルな名前と外観を指定します。
  • .accessibility_label(...) で、メニューのアクセシブルな名前を指定します。
  • .content(...) には、項目ごとに 1 つの MenuOption::new(&state, index) を コレクションの順序で含めます。そのテキスト、間隔、色、その他の視覚的な内容を指定してください。
  • .anchor(...) と .offset(...) で、既存のポップアップの配置を設定します。

レンダリングのために State を observe します。アクティブな コマンドのスタイルには highlighted_index() を、ラベルと無効状態には items() を読み取ります。メニューは選択された 値を保持しません。コマンドはアクションを表し、繰り返し実行できます。インタラクティブなフォーム コントロールは、メニューのコマンドの内容の外に置いてください。

チェック付きコマンド

アプリケーションが制御するチェックボックスのコマンドを描画するには、MenuOption::checked(bool) を使用します。 ビルダーを省略すると通常の MenuItem のままで、.checked(false) は 未チェックの MenuItemCheckBox を、.checked(true) はチェック済みのものを公開します。 可視のインジケーターとチェック値は、アプリケーションが描画のたびに指定します。

MenuOption::new(&menu, index)
    .checked(show_cursor)
    .child("Show cursor")

チェック付きコマンドは、通常のコマンドと同じナビゲーション、無効時の動作、 MenuEvent::Action(value) を使用します。アクティブ化するとメニューが閉じ、 イベントを届ける前にフォーカスが復元されます。アプリケーションがそのアクションを処理し、 次のチェック値を描画します。MenuState はチェック値を保存せず、自動的にトグルもしません。指定した値を変更しても アクションはディスパッチされません。 サンプルの Show cursor と Keep toolbar visible コマンドは、Checkbox と Switch が使用する、保持された アプリケーションの真偽値を共有します。DropdownMenu と ContextMenu はどちらも、同じメニューコンテンツの構成を通じてそれらの値を描画します。

共通の操作とライフサイクル

入力動作
トリガーのクリック / Enter / Space / Down最初の有効なコマンドで開きます
トリガーの Up最後の有効なコマンドで開きます
メニューの Up / Downカーソルを移動し、循環して無効なコマンドをスキップします
メニューの Home / End最初 / 最後の有効なコマンドに移動します
印字可能な 1 文字その文字で始まる有効なラベルを、大文字小文字を無視して順に切り替えます
オプションのクリック / メニューの Enter / Spaceコマンドを 1 回実行して閉じます
Escape閉じてトリガーのフォーカスを復元します
Tab / Shift-Tab閉じて、Popover の通常のフォーカス移動で離れます

先頭文字入力は 1 文字ずつ照合します。バッファされた検索やタイマーはありません。 Ctrl、Alt、プラットフォーム、Fn のショートカットはこの検索に入力されません。ポインターのホバーは、 キーボードナビゲーションと同じカーソルを移動させます。無効なコマンドは表示されたままで 無効のメタデータを持ちますが、ナビゲーションではスキップされ、実行できません。

アプリケーションでコマンドを処理するには、MenuEvent::Action(value) を購読します。 メニューは、イベントを届ける前に閉じてトリガーを復元します。そのため、ハンドラーは Dialog を開くことができ、その Dialog を閉じる操作が後でメニューのトリガーに戻ります。サンプルは、コマンドの処理中にウィンドウを受け取るため cx.subscribe_in を使用しています。

State のメソッドには open、close、set_disabled、focus_handle、 content_focus_handle があります。is_open(cx) と is_disabled(cx) は、 合成された Popover の State を読み取るため &App を取ります。ポップアップのライフサイクルの所有者は 1 つです。 オプションは別々の Tab ストップではありません。キーボードフォーカスはメニューのスコープに留まり、 ハイライトされたオプションが active descendant を提供します。それを含む Dialog は引き続き Tab の移動を制限し、外部のポインター押下は通常の動作を保ちます。

閉じている間もメニューホストはマウントしたままにしてください。ホストを削除する場合のフォーカスの契約は Popover と同じです。check_state(CheckboxState::Indeterminate) は混在状態の チェックボックスコマンドを提供し、radio_checked(bool) は MenuItemRadio のセマンティクスを提供します。 互いに排他的なラジオの値、グループ化、その描画はアプリケーションが管理します。

ネイティブのメタデータには、expanded/disabled の状態を持つ Button のトリガー、Menu の スコープ、指定されたチェック状態を持つ名前付きの通常/チェックボックス/ラジオのコマンド、 サブメニューの expanded 状態、active descendant が含まれます。ネイティブの has-popup プロパティや、トリガーからメニューへの controls 関係は出力されません。これらの 契約は実装された動作を説明するものであり、アクセシビリティパターンへの完全な準拠や、 スクリーンリーダーでの検証の完了を主張するものではありません。

サブメニュー

子の MenuState エンティティは、その親より先に作成します。親の項目は .submenu(&child) を宣言します。その項目は MenuSubmenu::new(&parent, index) を使用して描画し、 .trigger(|option| ...) と、子のオプションを含む .content(...) を指定します。 サブメニューホストはポップアップの配置を管理し、子の既存の Popover の ライフサイクルを再利用します。メニューツリーは非循環でなければならず、子は 1 つの親にのみ属します。

サブメニューの行へのネイティブのフォーカスは、親メニューのハイライトされた項目と同期します。 展開の矢印はハイライトされたサブメニューを開きます。反対向きの矢印または Escape は、 サブメニューを 1 つ閉じて親メニューのスコープを復元します。ポインターのホバーは 対応する子を開き、兄弟の枝を閉じます。通常のリーフをアクティブ化するとツリー全体が閉じ、 ルートの State にちょうど 1 つの MenuEvent::Action が通知されます。 Tab/Shift-Tab は、ルートの Popover のフォーカス移動を通じてメニューツリー全体から離れます。 アプリケーションはルートを購読し、リーフのアクションとチェック/ラジオの 値を管理します。閉じている間も、すべてのホストを構成内に保ってください。