명령 모음

명령 모음을 통해 앱에서 가장 많이 수행하는 작업에 쉽게 액세스할 수 있습니다. 명령 모음은 앱 수준의 명령이나 페이지 고유의 명령에 액세스할 수 있도록 해주며, 어떠한 탐색 패턴에서도 사용이 가능합니다.

올바른 컨트롤인가요?

CommandBar 컨트롤은 이미지 또는 텍스트 블록과 같은 복잡한 콘텐츠뿐만 아니라 AppBarButton, AppBarToggleButton 및 AppBarSeparator 컨트롤과 같은 간단한 명령을 모두 표시할 수 있는 범용 유연하고 가벼운 컨트롤입니다.

해부학

기본적으로 명령 모음에는 아이콘 단추 행 및 줄임표 [...]로 표시되는 선택적 "자세히 보기" 단추가 표시됩니다. 다음은 나중에 표시되는 예제 코드에서 만든 명령 모음입니다. 닫힌 압축 상태로 표시됩니다.

명령 모음은 다음과 같이 닫힌 최소 상태로 표시될 수도 있습니다. 자세한 내용은 열기 및 닫힌 상태 섹션을 참조하세요.

열린 상태에서 동일한 명령 모음은 다음과 같습니다. 레이블은 컨트롤의 메인 부분을 식별합니다.

명령 모음은 4개 주 영역으로 나뉩니다.

• 콘텐츠 영역은 막대의 왼쪽에 맞춰집니다. Content 속성이 채워지면 표시됩니다.
• 기본 명령 영역은 툴바의 오른쪽에 맞춰집니다. PrimaryCommands 속성이 채워지면 표시됩니다.
• "자세히 보기"[...] 단추는 모음의 오른쪽에 표시됩니다. "자세히 보기"[...] 단추를 누르면 기본 명령 레이블이 표시되고 보조 명령이 있는 경우 오버플로 메뉴가 열립니다. 이 단추는 기본 명령 레이블이나 보조 레이블이 존재하지 않으면 표시되지 않습니다. 기본 동작을 변경하려면 OverflowButtonVisibility 속성을 사용합니다.
• 오버플로 메뉴는 명령 모음이 열려 있고 SecondaryCommands 속성이 채워진 경우에만 표시됩니다. 공간이 제한된 경우 기본 명령이 SecondaryCommands 영역으로 이동합니다. 기본 동작을 변경하려면 IsDynamicOverflowEnabled 속성을 사용합니다.

FlowDirection이 RightToLeft인 경우 레이아웃이 반전됩니다.

배치

명령 모음을 Grid.row 같은 레이아웃 컨트롤에 포함시켜 앱 창의 맨 위, 앱 창의 맨 아래에 배치하거나 인라인으로 배치할 수 있습니다.

• 손으로 들 수 있는 소형 디바이스의 경우, 연결을 용이하게 하기 위해 화면 아래쪽에 명령 모음을 배치하는 것이 좋습니다.
• 화면이 더 큰 디바이스에서 명령 모음을 창의 위쪽에 배치하면 더 눈에 띄고 찾기가 쉽습니다.

DiagonalSizeInInches API를 사용하여 실제 화면 크기를 확인합니다.

명령 모음은 단일 보기 화면(왼쪽 예) 및 다중 보기 화면(오른쪽 예제)의 다음 화면 영역에 배치할 수 있습니다. 인라인 명령 모음은 작업 공간의 아무 곳에나 배치할 수 있습니다.

터치 장치: 터치 키보드 또는 SIP(소프트 입력 패널)가 나타날 때 명령 모음이 사용자에게 계속 표시되어야 하는 경우 명령 모음을 페이지의 BottomAppBar 속성에 할당할 수 있으며 SIP가 있을 때 계속 표시되도록 이동합니다. 그렇지 않으면 명령 모음을 인라인으로 배치하고 앱 콘텐츠를 기준으로 배치해야 합니다.

명령 모음 만들기

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 컨트롤에는 명령 및 콘텐츠를 추가하는 데 사용할 수 있는 3가지 속성(PrimaryCommands, SecondaryCommands 및 Content)이 있습니다.

명령어

기본적으로 명령 모음 항목은 PrimaryCommands 컬렉션에 추가됩니다. 가장 중요한 명령이 항상 표시되도록 하려면 중요도 순서로 명령을 추가해야 합니다. 사용자가 앱 창의 크기를 조정해서 명령 모음 너비가 변경되면 기본 명령이 명령 모음과 중단점의 오버플로 메뉴 간에 동적으로 이동합니다. 이 기본 동작을 변경하려면 IsDynamicOverflowEnabled 속성을 사용합니다.

가장 작은 화면(320epx 너비)에서는 최대 4개의 기본 명령이 명령 모음에 들어갑니다.

오버플로 메뉴에 표시되는 SecondaryCommands 컬렉션에 명령을 추가할 수도 있습니다.

필요에 따라 PrimaryCommands와 SecondaryCommands 간에 명령을 프로그래밍 방식으로 이동할 수 있습니다.

• 여러 페이지에서 일관되게 표시되는 명령이 있는 경우 해당 명령을 일관된 위치에 유지하는 것이 가장 좋습니다.
• 수락, 예 및 확인 명령은 거부, 아니요, 취소 명령 왼쪽에 배치하는 것이 좋습니다. 일관성은 사용자에게 신뢰감을 주어 시스템을 둘러보도록 유도하며, 앱 탐색과 관련된 지식을 앱 간에 적용하는 데 도움이 됩니다.

앱 바 버튼

PrimaryCommands 및 SecondaryCommands는 모두 AppBarButton, AppBarToggleButton 및 AppBarSeparator 명령 요소를 포함하는 ICommandBarElement 인터페이스를 구현하는 형식으로만 채울 수 있습니다.

PrimaryCommands 또는 SecondaryCommands에 다른 유형의 요소를 포함하려는 경우 AppBarElementContainer 클래스를 사용할 수 있습니다. 이는 요소에 대한 래퍼 역할을 하며, 해당 요소가 CommandBar에 표시될 수 있도록 합니다.

앱 바 단추 컨트롤은 아이콘 및 텍스트 레이블에 따라 구분됩니다. 이러한 컨트롤은 명령 모음에서의 사용에 최적화되어 있으며, 컨트롤이 명령 모음에서 사용되는지 또는 오버플로 메뉴에서 사용되는지에 따라 모양이 변경됩니다.

아이콘

기본 명령 영역에 표시되는 아이콘의 크기는 20x20px입니다. 오버플로 메뉴에서 아이콘은 16x16px로 표시됩니다. 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으로 설정하여 스타일을 조정할 수 있습니다.

단추 레이블은 짧아야 하며, 가급적이면 한 단어여야 합니다. 아이콘 아래의 더 긴 레이블은 여러 줄로 줄바꿈되어 열리는 명령 모음의 전체 높이가 늘어납니다. 레이블의 텍스트에 소프트 하이픈 문자(0x00AD)를 포함하면 단어 분리가 발생하는 문자 경계를 암시할 수 있습니다. XAML에서는 다음과 같이 이스케이프 시퀀스를 사용하여 이를 표현합니다.

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

레이블이 암시된 위치에서 래핑되면 다음과 같습니다.

분할 버튼

와 SplitButtonCommandBarStyle 클래스를 사용하여 CommandBar에 SplitButton을 표시할 수 있습니다. SplitButtonCommandBarStyle은 AppBarButton과 같은 모양과 느낌을 주기 위해 SplitButton에 대한 시각적 개체를 제공하는 반면 AppBarElementContainer는 SplitButton이 AppBarButton처럼 작동하는 데 필요한 기능을 제공하는 래퍼 클래스입니다.

AppBarElementContainer에서 SplitButton를 래핑하고 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 또는 플라이아웃 을 표시할 수 있습니다.

기타 콘텐츠

Content 속성을 설정하여 콘텐츠 영역에 XAML 요소를 추가할 수 있습니다. 둘 이상의 요소를 추가하려면 먼저 패널 컨테이너에 배치하고, 패널을 Content 속성의 단일 자식으로 만들어야 합니다.

동적 오버플로가 활성화되면 기본 명령이 오버플로 메뉴로 이동할 수 있으므로 콘텐츠가 잘리지 않게 됩니다. 그렇지 않은 경우 기본 명령이 우선 적용되어 콘텐츠 잘림이 야기될 수 있습니다.

ClosedDisplayMode가 Compact일 때, 명령 모음의 압축 크기보다 콘텐츠가 더 크면 잘릴 수 있습니다. 콘텐츠 영역에서 UI의 일부를 표시하거나 숨기려면 열기 및 닫힌 이벤트를 처리하여 잘리지 않도록 해야 합니다. 자세한 내용은 열기 및 닫힌 상태 섹션을 참조하세요.

열린 상태 및 닫힌 상태

명령 모음을 열거나 닫을 수 있습니다. 열리면 텍스트 레이블이 있는 기본 명령 단추가 표시되고 오버플로 메뉴가 열립니다(보조 명령이 있는 경우). 명령 모음은 오버플로 메뉴를 위쪽(기본 명령 위) 또는 아래쪽(기본 명령 아래)으로 엽니다. 기본 방향은 위쪽이지만 오버플로 메뉴를 위쪽으로 열 수 있는 공간이 충분하지 않으면 명령 모음이 아래쪽으로 열립니다.

사용자가 "자세히 보기"[...] 단추를 눌러 이러한 상태 간을 전환할 수 있습니다. IsOpen 속성을 설정하여 프로그래밍 방식으로 전환할 수 있습니다.

열기, 열기, 닫기 및 닫기 이벤트를 사용하여 열리거나 닫히는 명령 모음에 응답할 수 있습니다.

• 열기 및 닫기 이벤트는 전환 애니메이션이 시작되기 전에 발생합니다.
• 열린 이벤트 및 닫힌 이벤트는 전환이 완료된 후에 발생합니다.

이 예제에서는 열기 이벤트 및 닫기 이벤트를 사용하여 명령 모음의 불투명도를 변경합니다. 명령 모음이 닫혀 있으면 반투명하므로 앱 배경이 표시됩니다. 명령 모음이 열리면 사용자가 명령에 집중할 수 있도록 명령 모음이 불투명하게 됩니다.

<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가지 있습니다.

• 압축: 기본 모드입니다. 콘텐츠, 레이블이 없는 기본 명령 아이콘 및 "자세히 보기"[...] 단추를 표시합니다.
• 최소: "자세히 보기" [...] 단추 역할을 하는 얇은 막대만 표시합니다. 사용자는 막대의 아무 곳이나 눌러 열 수 있습니다.
• 숨김: 명령 모음이 닫히면 표시되지 않습니다. 인라인 명령 모음을 사용하여 상황에 맞는 명령을 표시하는 데 유용할 수 있습니다. 이 경우 IsOpen 속성을 설정하거나 ClosedDisplayMode를 최소 또는 압축으로 변경하여 프로그래밍 방식으로 명령 모음을 열어야 합니다.

여기서 명령 모음은 RichEditBox에 대한 간단한 서식 지정 명령을 유지하는 데 사용됩니다. 편집 상자에 포커스가 없으면 서식 지정 명령이 방해가 될 수 있으므로 숨겨집니다. 편집 상자를 사용하는 경우 서식 지정 명령이 표시되도록 명령 모음의 ClosedDisplayMode가 압축으로 변경됩니다.

<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;
}

최소 모드 및 숨김 모드는 경우에 따라 유용하지만, 모든 작업을 숨기면 사용자에게 혼란을 줄 수 있습니다.

사용자에게 힌트를 더 많게 혹은 적게 제공하도록 ClosedDisplayMode를 변경하면 주변 요소의 레이아웃에 영향이 갑니다. 반면, CommandBar가 닫힌 상태와 열린 상태 사이에서 전환되는 경우, 다른 요소의 레이아웃에는 영향을 주지 않습니다.

UWP 및 WinUI 2

이 컨트롤에 대한 API는 Windows.UI.Xaml.Controls 네임스페이스에 있습니다.

최신 WinUI 2 를 사용하여 모든 컨트롤에 대한 최신 스타일과 템플릿을 가져오는 것이 좋습니다. WinUI 2.2 이상에는 둥근 모서리를 사용하는 이 컨트롤의 새 템플릿이 포함되어 있습니다. 자세한 내용은 모서리 반경을 참조하세요.

CommandBar에서 SplitButton의 자동 스타일을 지정하려면 WinUI 2.6 이상의 SplitButton 컨트롤을 사용해야 합니다.

관련된 문서

• Windows 앱에 대한 명령 디자인 기본 사항
• 명령줄 확장
• 메뉴 플라이아웃 및 메뉴 모음
• MenuFlyout 클래스
• CommandBar 클래스