コマンドバー

[アーティクル]
06/02/2023

コマンドバーを使うと、ユーザーはアプリの最も一般的なタスクに簡単にアクセスできます。コマンドバーを使うと、アプリレベルまたはページに固有のコマンドにアクセスできます。これは、ナビゲーションパターンと共に使用することもできます。

アイコンを含むコマンドバーの例

これは適切なコントロールですか?

CommandBar コントロールは、汎用的で柔軟、軽量なコントロールです。画像やテキストブロックなどの複雑なコンテンツも、AppBarButton、AppBarToggleButton、AppBarSeparator コントロールなどの単純なコマンドも表示できます。

注意

XAML では、AppBar コントロールと CommandBar コントロールの両方が提供されます。 AppBar を使うユニバーサル Windows 8 アプリをアップグレードする場合にのみ、AppBar を使ってください。また、変更は最小限に抑える必要があります。 Windows 10 の新しいアプリでは、代わりに CommandBar コントロールを使うことをお勧めします。このドキュメントでは、CommandBar コントロールを使うことを前提としています。

構造

既定では、コマンドバーには、一連のアイコンボタンとオプションの [その他] ボタン (省略記号の [...]) が表示されます。後で示すコード例を使って作成されたコマンドバーを次に示します。コマンドバーは、閉じたコンパクトな状態で表示されます。

閉じたコマンドバーを示すスクリーンショット。

コマンドバーは、次のように、閉じた最小の状態で表示することもできます。詳しくは、「開いた状態と閉じた状態」をご覧ください。

閉じた最小状態のコマンドバーを示すスクリーンショット。

同じコマンドバーが開いている状態を次に示します。ラベルは、コントロールのメイン部分を識別します。

開いた状態のコマンドバーを示すスクリーンショット。

コマンドバーは、4 つの主な領域に分かれています。

コンテンツ領域はバーの左側に配置されます。これは、Content プロパティが指定されている場合に表示されます。
基本コマンド領域はバーの右側に配置されます。これは、PrimaryCommands プロパティが指定されている場合に表示されます。
[その他] ([...]) ボタンはバーの右側に表示されます。 [その他] ([...]) ボタンを押すと、プライマリコマンドのラベルが表示され、セカンダリコマンドが存在する場合はオーバーフローメニューが開きます。このボタンは、プライマリコマンドラベルもセカンダリラベルもない場合には表示されません。既定の動作を変更するには、OverflowButtonVisibility プロパティを使います。
オーバーフローメニューは、コマンドバーが開いていて、SecondaryCommands プロパティが指定されている場合にのみ表示されます。スペースが限られている場合に、プライマリコマンドは SecondaryCommands 領域に移動されます。既定の動作を変更するには、IsDynamicOverflowEnabled プロパティを使います。

FlowDirection が RightToLeft のときは、レイアウトが逆になります。

配置

コマンドバーは、Grid.row などのレイアウトコントロールに組み込むことにより、アプリウィンドウの上部、アプリウィンドウの下部、またはインラインに配置できます。

アプリバーの配置の例 1

小型の携帯デバイスでは、コマンドバーを画面の下部に配置して、操作しやすくことをお勧めします。
大きな画面を持つデバイスでは、では、コマンドバーは、ウィンドウの上端近くに配置して、気付きやすくします。

物理的な画面サイズを調べるには、DiagonalSizeInInches API を使います。

コマンドバーは、単一ビュー画面 (左側の例) と複数ビュー画面 (右側の例) の次の画面領域に配置できます。インラインのコマンドバーは、アクション領域の任意の場所に配置できます。

アプリバーの配置の例 2

タッチデバイス:タッチキーボード、つまりソフト入力パネル (SIP) が表示されているときに、コマンドバーをユーザーに対して表示したままにする必要がある場合、コマンドバーをページの BottomAppBar プロパティに割り当てると、SIP の表示中はコマンドバーが移動して表示されたままになります。それ以外の場合は、コマンドバーをインラインおよびアプリのコンテンツに対して相対的に配置します。

UWP と WinUI 2

重要

この記事の情報と例は、Windows アプリ SDKと WinUI 3 を使用するアプリ向けに最適化されていますが、一般に WinUI 2 を使用する UWP アプリに適用されます。プラットフォーム固有の情報と例については、UWP API リファレンスを参照してください。

このセクションには、UWP または WinUI 2 アプリでコントロールを使用するために必要な情報が含まれています。

このコントロールの API は、Windows.UI.Xaml.Controls 名前空間に存在します。

UWP API:CommandBar クラス、 AppBarButton クラス、 AppBarToggleButton クラス、 AppBarSeparator クラス
WinUI 2 ギャラリーアプリを開き、CommandBar の動作を確認します。 WinUI 2 ギャラリー アプリには、ほとんどの WinUI 2 コントロールと機能の対話型の例が含まれています。 Microsoft Store からアプリを入手するか、GitHub でソースコードを取得します。

最新の WinUI 2 を使用して、すべてのコントロールの最新のスタイルとテンプレートを取得することをお勧めします。 WinUI 2.2 以降には、丸い角を使用するこのコントロール用の新しいテンプレートが含まれています。詳しくは、「角の半径」をご覧ください。

CommandBar での SplitButton の自動スタイル設定では、WinUI 2.6 以降の SplitButton コントロールを使用する必要があります。

コマンドバーの作成

重要な API:CommandBar クラス、 AppBarButton クラス、 AppBarToggleButton クラス、 AppBarSeparator クラス

WinUI 3 ギャラリーアプリを開き、CommandBar の動作を確認します。

WinUI 3 ギャラリー アプリには、ほとんどの WinUI 3 コントロールと機能の対話型の例が含まれています。 Microsoft Store からアプリを入手するか、GitHub でソースコードを取得します。

次の例では、上に示したコマンドバーが作成されます。

<CommandBar>
    <AppBarToggleButton Icon="Shuffle" Label="Shuffle" Click="AppBarButton_Click" />
    <AppBarToggleButton Icon="RepeatAll" Label="Repeat" Click="AppBarButton_Click"/>
    <AppBarSeparator/>
    <AppBarButton Icon="Back" Label="Back" Click="AppBarButton_Click"/>
    <AppBarButton Icon="Stop" Label="Stop" Click="AppBarButton_Click"/>
    <AppBarButton Icon="Play" Label="Play" Click="AppBarButton_Click"/>
    <AppBarButton Icon="Forward" Label="Forward" Click="AppBarButton_Click"/>

    <CommandBar.SecondaryCommands>
        <AppBarButton Label="Like" Click="AppBarButton_Click"/>
        <AppBarButton Label="Dislike" Click="AppBarButton_Click"/>
    </CommandBar.SecondaryCommands>

    <CommandBar.Content>
        <TextBlock Text="Now playing..." Margin="12,14"/>
    </CommandBar.Content>
</CommandBar>

コマンドとコンテンツ

CommandBar コントロールには、PrimaryCommands、SecondaryCommands、Content の 3 つのプロパティがあり、コマンドとコンテンツを追加するために使うことができます。

コマンド

既定では、コマンドバーの項目は PrimaryCommands コレクションに追加されます。最も重要なコマンドを常に表示できるように、重要度順にコマンドを追加する必要があります。ユーザーによるアプリウィンドウのサイズ変更などでコマンドバーの幅が変化した場合、プライマリコマンドはブレークポイントを境としてコマンドバーとオーバーフローメニューの間を動的に移動します。この既定の動作を変更するには、IsDynamicOverflowEnabled プロパティを使います。

最小画面 (幅 320 epx) には、最大 4 つのプライマリコマンドを、コマンドバーに配置できます。

SecondaryCommands コレクションにコマンドを追加することもできます。これらは、オーバーフローメニューに表示されます。

[その他] 領域とアイコンがあるコマンドバーの例

必要に応じて、プログラムを使って PrimaryCommands と SecondaryCommands の間でコマンドを移動できます。

複数のページで一貫して表示されるコマンドがある場合は、一貫した場所にそのコマンドを配置することをお勧めします。
また、[Accept] （承諾）、[Yes] （はい）、[OK] （OK）コマンドは、[Reject] （拒否）、[No] （いいえ）、[Cancel] （キャンセル）コマンドの左に配置することをお勧めします。一貫性があることで、ユーザーは安心してシステム内を移動でき、アプリのナビゲーションに関する知識をさまざまなアプリで利用することができます。

アプリバーのボタン

PrimaryCommands と SecondaryCommands には、どちらも AppBarButton、AppBarToggleButton、AppBarSeparator の各コマンド要素を含む、ICommandBarElement インターフェイスを実装する型のみを入力できます。

PrimaryCommands または SecondaryCommands に別の種類の要素を含める場合は、AppBarElementContainer クラスを使用できます。これは、要素のラッパーとして機能し、要素を CommandBar に表示できるようにします。

アプリバーのボタンコントロールは、アイコンとテキストラベルによって特徴付けられます。これらのコントロールは、コマンドバーで使うように最適化されており、コマンドバーとオーバーフローメニューのどちらで使うかに応じて外観が変化します。

アイコン

アイコンのサイズは、基本コマンド領域に表示される場合は 20 x 20 px で、オーバーフローメニューの場合はアイコンは 16 x 16 px で表示されます。 SymbolIcon、FontIcon、または PathIcon を使うと、コマンドがセカンダリコマンド領域に表示されるときに、忠実さを失うことなく、適切なサイズに自動的に調整されます。

アイコンの設定の詳細と例については、AppBarButton クラスのドキュメントを参照してください。

ラベル

AppBarButton IsCompact プロパティはラベルが表示されるかどうかを決定します。 CommandBar コントロールで、コマンドバーの開閉に応じてコマンドバーがボタンの IsCompact プロパティを自動的に上書きします。

アプリバーボタンのラベルを配置するには、CommandBar の DefaultLabelPosition プロパティを使用します。

<CommandBar DefaultLabelPosition="Right">
    <AppBarToggleButton Icon="Edit" Label="Edit"/>
    <AppBarToggleButton Icon="Share" Label="Share"/>
</CommandBar>

ラベルが右に配置されたコマンドバー

比較的大きなウィンドウの場合は、ラベルを見やすくするためにアプリバーのボタンアイコンの右に移動することを検討します。ラベルを下に配置すると、コマンドバーを開かないとラベルが見えませんが、ラベルを右に配置すると、コマンドバーが閉じていてもラベルが見えます。

オーバーフローメニューで、ラベルは既定ではアイコンの右側に配置され、LabelPosition は無視されます。スタイルを調整するには、CommandBarOverflowPresenterStyle プロパティを、CommandBarOverflowPresenter をターゲットにする Style に設定します。

ボタンのラベルは、短く、可能であれば 1 つの単語にすることをお勧めします。アイコンの下の長いラベルは複数の行に折り返されるため、開いたコマンドバーの全体的な高さが増します。ラベルのテキストにソフトハイフン文字 (0x00AD) を含めると、テキストの中で単語を分割する位置を示すことができます。 XAML でこの処理を行うには、次のようなエスケープシーケンスを使います。

<AppBarButton Icon="Back" Label="Areally&#x00AD;longlabel"/>

指定した場所でラベルが折り返されると、次のようになります。

SplitButton

組み込みの SplitButtonCommandBarStyle および AppBarElementContainer クラスを使用して、SplitButton を CommandBar に表示できます。 SplitButtonCommandBarStyle では、SplitButton のビジュアルが AppBarButton のような外観になるようにします。ここで AppBarElementContainer は、SplitButton が AppBarButton のように動作するために必要な機能を提供するラッパークラスです。

SplitButton を AppBarElementContainer にラップし、CommandBar に配置すると、SplitButtonCommandBarStyle リソースが自動的に適用されます。

このサンプルコードでは、CommandBar 内に SplitButton を作成して表示します。

<CommandBar>
    <AppBarButton Icon="Copy" ToolTipService.ToolTip="Copy" Label="Copy"/>
    <AppBarElementContainer>
        <muxc:SplitButton ToolTipService.ToolTip="Insert" Content="Insert">
            <muxc:SplitButton.Flyout>
                <MenuFlyout Placement="RightEdgeAlignedTop">
                    <MenuFlyoutItem Text="Insert above"/>
                    <MenuFlyoutItem Text="Insert between"/>
                    <MenuFlyoutItem  Text="Insert below"/>
                </MenuFlyout>
            </muxc:SplitButton.Flyout>
        </muxc:SplitButton>
    </AppBarElementContainer>
    <AppBarButton Label="Select all"/>
    <AppBarButton Label="Delete" Icon="Delete"/>
</CommandBar>

メニューとポップアップ

コマンドは論理的にグループ化することを検討します。たとえば、[返信]、[全員に返信]、[転送] を [応答] メニューに配置します。通常、アプリバーボタンは単一のコマンドをアクティブ化しますが、アプリバーボタンを使用して、カスタムコンテンツを持つ MenuFlyout または Flyout を表示できます。

並べ替えオプションの MenuFlyout の例コマンドバーのポップアップの例

その他のコンテンツ

XAML 要素をコンテンツ領域に追加するには、Content プロパティを設定します。複数の要素を追加する場合は、それらの要素をパネルコンテナーに配置し、パネルを Content プロパティの唯一の子にする必要があります。

動的オーバーフローが有効になっている場合は、プライマリコマンドがオーバーフローメニューに移動するため、コンテンツはクリップされません。それ以外の場合は、プライマリコマンドが優先されるため、コンテンツがクリップされる可能性があります。

ClosedDisplayMode が Compact の場合、コンパクトサイズのコマンドバーよりも大きいコンテンツはクリップされる可能性があります。 UI の一部がクリップされないようにするには、コンテンツ領域で UI の各部分を表示または非表示にするように Opening と Closed の各イベントを処理する必要があります。詳しくは、「開いた状態と閉じた状態」をご覧ください。

開いた状態と閉じた状態

コマンドバーは、開いたり閉じたりできます。開いているときは、テキストラベル付きのプライマリコマンドボタンが表示され、(セカンダリコマンドが存在する場合は) オーバーフローメニューが開きます。コマンドバーはオーバーフローメニューを上方向 (プライマリコマンドの上) または下方向 (プライマリコマンドの下) に開きます。既定の方向は上方向ですが、オーバーフローメニューを開くための十分な領域が上方向にない場合、コマンドバーはこれを下方向に開きます。

ユーザーは、[その他] ([...]) ボタンを押して状態を切り替えることができます。プログラムで切り替えるには、IsOpen プロパティを設定します。

Opening、Opened、Closing、Closed の各イベントを使うと、コマンドバーの開閉に対応できます。

Opening イベントと Closing イベントが発生するのは、切り替えアニメーションの開始前です。
Opened イベントと Closed イベントが発生するのは、切り替えの完了後です。

次の例では、Opening イベントと Closing イベントを使ってコマンドバーの不透明度を変更します。コマンドバーが閉じているときは、アプリの背景が見えるようにコマンドバーが半透明になります。コマンドバーが開いているときは、ユーザーがコマンドに集中できるようにコマンドバーが不透明になります。

<CommandBar Opening="CommandBar_Opening"
            Closing="CommandBar_Closing">
    <AppBarButton Icon="Accept" Label="Accept"/>
    <AppBarButton Icon="Edit" Label="Edit"/>
    <AppBarButton Icon="Save" Label="Save"/>
    <AppBarButton Icon="Cancel" Label="Cancel"/>
</CommandBar>

private void CommandBar_Opening(object sender, object e)
{
    CommandBar cb = sender as CommandBar;
    if (cb != null) cb.Background.Opacity = 1.0;
}

private void CommandBar_Closing(object sender, object e)
{
    CommandBar cb = sender as CommandBar;
    if (cb != null) cb.Background.Opacity = 0.5;
}

IsSticky

コマンドバーが開いているときにユーザーがアプリの他の部分とやり取りすると、コマンドバーは自動的に閉じます。これは簡易非表示と呼ばれます。簡易非表示動作を制御するには、IsSticky プロパティを設定します。 IsSticky="true" の場合、ユーザーが [その他] ([...]) ボタンを押すか、オーバーフローメニューから項目を選ぶまで、バーは開いたままになります。

固定のコマンドバーは、簡易非表示およびキーボードフォーカスというユーザーが期待する動作と一致しないため、使わないようにすることをお勧めします。

表示モード

コマンドバーが閉じた状態でどのように表示されるか制御するには、ClosedDisplayMode プロパティを設定します。 3 つのクローズド表示モードから選ぶことができます。

コンパクト:既定のモード。コンテンツ、プライマリコマンドのアイコン (ラベルなし)、[その他] ([...]) ボタンが表示されます。
Minimal: [その他] ([...]) ボタンとして機能する細いバーのみが表示されます。ユーザーはバーの任意の場所を押してバーを開くことができます。
非表示:コマンドバーを閉じたとき、コマンドバーは表示されません。このモードは、インラインコマンドバーでコンテキスト依存コマンドを表示するときに便利な場合があります。この場合は、コマンドバーをプログラムで開く必要があります。この操作を行うには、IsOpen プロパティを設定するか、ClosedDisplayMode を Minimal または Compact に変更します。

以下では、コマンドバーを使って RichEditBox に単純な書式設定コマンドを保持しています。編集ボックスにフォーカスがないときには、書式設定コマンドが煩わしくないように非表示にします。編集ボックスを使っているときは、コマンドバーの ClosedDisplayMode を Compact に変更して書式設定コマンドを表示します。

<StackPanel Width="300"
            GotFocus="EditStackPanel_GotFocus"
            LostFocus="EditStackPanel_LostFocus">
    <CommandBar x:Name="FormattingCommandBar" ClosedDisplayMode="Hidden">
        <AppBarButton Icon="Bold" Label="Bold" ToolTipService.ToolTip="Bold"/>
        <AppBarButton Icon="Italic" Label="Italic" ToolTipService.ToolTip="Italic"/>
        <AppBarButton Icon="Underline" Label="Underline" ToolTipService.ToolTip="Underline"/>
    </CommandBar>
    <RichEditBox Height="200"/>
</StackPanel>

private void EditStackPanel_GotFocus(object sender, RoutedEventArgs e)
{
    FormattingCommandBar.ClosedDisplayMode = AppBarClosedDisplayMode.Compact;
}

private void EditStackPanel_LostFocus(object sender, RoutedEventArgs e)
{
    FormattingCommandBar.ClosedDisplayMode = AppBarClosedDisplayMode.Hidden;
}

注意

編集コマンドの実装は、この例の範囲外です。詳しくは、「RichEditBox」をご覧ください。

Minimal モードと Hidden モードが役に立つ場合もありますが、すべてのアクションを非表示にするとユーザーが混乱する可能性があることに注意してください。

ClosedDisplayMode を変更してユーザーにヒントを表示すると、周囲にある要素のレイアウトが影響を受けます。これに対し、CommandBar の開閉を切り替えても他の要素のレイアウトには影響しません。

サンプルコードを入手する

WinUI ギャラリーのサンプル - すべての XAML コントロールを対話型形式で表示します。
XAML コマンド実行のサンプル

コマンドバー

これは適切なコントロールですか?

構造

配置

UWP と WinUI 2

コマンドバーの作成

コマンドとコンテンツ

コマンド

アプリバーのボタン

アイコン

ラベル

SplitButton

メニューとポップアップ

その他のコンテンツ

開いた状態と閉じた状態

IsSticky

表示モード

サンプルコードを入手する

フィードバック

その他のリソース

コマンド バー

これは適切なコントロールですか?

構造

配置

UWP と WinUI 2

コマンド バーの作成

コマンドとコンテンツ

コマンド

アプリ バーのボタン

アイコン

ラベル

SplitButton

メニューとポップアップ

その他のコンテンツ

開いた状態と閉じた状態

IsSticky

表示モード

サンプル コードを入手する

関連記事

フィードバック

その他のリソース

コマンドバー

コマンドバーの作成

アプリバーのボタン

サンプルコードを入手する