명령 모음

아티클
07/04/2024

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

아이콘이 있는 명령 모음의 예

올바른 컨트롤인가요?

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

참고 항목

XAML은 AppBar 컨트롤과 CommandBar 컨트롤을 모두 제공합니다. AppBar를 사용하는 유니버설 Windows 8 앱을 업그레이드하고 변경 내용을 최소화해야 하는 경우에만 AppBar를 사용해야 합니다. Windows 10의 새 앱의 경우, CommandBar 컨트롤을 대신 사용하는 것이 좋습니다. 이 문서에서는 사용자가 CommandBar 컨트롤을 사용하고 있다고 가정합니다.

구조

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

닫힌 명령 모음을 보여주는 스크린샷.

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

닫힌 최소 상태의 명령 모음을 보여주는 스크린샷.

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

열린 상태의 명령 모음을 보여주는 스크린샷.

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

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

레이아웃이 반전되는 경우는 FlowDirection 이 RightToLeft인 경우입니다.

배치

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

앱 바 배치의 예제 1

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

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

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

앱 바 배치의 예제 2

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

UWP 및 WinUI 2

Important

이 문서의 정보 및 예제는 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 이상에는 둥근 모서리를 사용하는 이 컨트롤의 새 템플릿이 포함되어 있습니다. 자세한 내용은 모서리 반경을 참조하세요.

SplitButton의 자동 스타일 을 CommandBar에서 지정하려면 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 컨트롤에는 명령과 콘텐츠를 추가하는 데 사용할 수 있는 속성이 3가지가 있습니다: PrimaryCommands, SecondaryCommands, 및 콘텐츠입니다.

명령

기본적으로 명령 모음 항목은 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"/>

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

SplitButton

기본 제공 SplitButtonCommandBarStyle 및 AppBarElementContainer 클래스를 사용하여 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 또는 플라이아웃 을 표시할 수 있습니다.

정렬 옵션에 대한 MenuFlyout의 예 명령 모음의 플라이아웃 예

기타 콘텐츠

XAML 요소를 콘텐츠 영역에 추가하려면 Content 속성을 설정하면 됩니다. 둘 이상의 요소를 추가하려면 먼저 패널 컨테이너에 배치하고, 패널을 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;
}

참고 항목

편집 명령 구현은 이 예제의 범위를 벗어납니다. 자세한 내용은 RichEditBox 를 참조하세요.

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

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

샘플 코드 가져오기

WinUI 갤러리 샘플 - 대화형 형식으로 모든 XAML 컨트롤 표시
XAML 명령 샘플

다음을 통해 공유

명령 모음

올바른 컨트롤인가요?

구조

배치

UWP 및 WinUI 2

명령 모음 만들기

명령 및 콘텐츠

명령

앱 바 버튼

아이콘

레이블

SplitButton

메뉴 및 플라이아웃

기타 콘텐츠

열린 상태 및 닫힌 상태

IsSticky

디스플레이 모드

샘플 코드 가져오기

추가 리소스

다음을 통해 공유

명령 모음

올바른 컨트롤인가요?

구조

배치

UWP 및 WinUI 2

명령 모음 만들기

명령 및 콘텐츠

명령

앱 바 버튼

아이콘

레이블

SplitButton

메뉴 및 플라이아웃

기타 콘텐츠

열린 상태 및 닫힌 상태

IsSticky

디스플레이 모드

샘플 코드 가져오기

관련된 문서

추가 리소스