심화 가이드
접근성 지원

콤보박스

개요

텍스트 입력란, 버튼, div 같은 트리거 엘리먼트와 팝업을 연결하는 디렉티브입니다. 자동 완성, 선택, 다중 선택 패턴의 기반이 됩니다.

사용법

콤보박스는 텍스트 입력란, 버튼, div 같은 상호작용 트리거 엘리먼트와 팝업을 연결하는 기본 디렉티브입니다. 자동 완성, 선택, 다중 선택 패턴의 기반을 제공합니다. 다음과 같은 경우에는 콤보박스를 직접 사용하는 것을 고려하세요.

  • 커스텀 자동 완성 패턴 개발: 특수한 필터링이나 추천 동작을 만들 때
  • 커스텀 선택 컴포넌트 개발: 고유한 요구사항이 있는 드롭다운을 개발할 때
  • 입력란과 팝업 연결: 텍스트 입력란을 리스트박스, 트리, 대화상자 콘텐츠와 연결할 때
  • 커스텀 필터링 구현: 애플리케이션 코드에서 일치하는 옵션을 필터링하고 제어할 때

다음과 같은 경우에는 문서에서 소개하는 패턴을 사용하세요.

  • 필터링을 지원하는 표준 자동 완성이 필요한 경우: 바로 사용할 수 있는 예제는 자동 완성 패턴을 참고하세요.
  • 단일 선택 드롭다운이 필요한 경우: 완전한 드롭다운 구현은 선택 패턴을 참고하세요.
  • 다중 선택 드롭다운이 필요한 경우: 선택 결과를 간결하게 표시하는 다중 선택은 다중 선택 패턴을 참고하세요.

NOTE: 자동 완성, 선택, 다중 선택 가이드는 특정 사용 사례에 맞춰 이 디렉티브를 리스트박스와 결합하는 패턴을 소개합니다.

주요 기능

Angular의 콤보박스는 다음과 같이 접근성을 갖춘 입력란과 팝업의 연결 기능을 제공합니다.

  • 팝업이 연결된 트리거 엘리먼트: 트리거 엘리먼트와 팝업 콘텐츠를 연결합니다.
  • 유연한 연결: 리스트박스, 트리, 그리드, 대화상자와 같은 표준 레이아웃과 자연스럽게 통합합니다.
  • 키보드 탐색: 방향키, Enter, Escape를 처리합니다.
  • 스크린 리더 지원: role="combobox", aria-expanded를 비롯한 ARIA 어트리뷰트를 기본 제공합니다.
  • 팝업 관리: 사용자 조작에 따라 자동으로 표시하거나 숨깁니다.
  • 시그널 기반 반응성: Angular 시그널로 상태를 반응형으로 관리합니다.

예제

자동 완성

사용자가 입력할 때 옵션을 필터링하고 추천해서 목록에서 값을 찾고 선택하도록 돕는 접근성 있는 입력 필드입니다.

필터링은 애플리케이션 코드에서 관리합니다. 시그널을 갱신하면 옵션 목록이 반응형으로 필터링됩니다. 사용자는 방향키로 탐색하고 Enter를 누르거나 클릭해서 선택합니다. 커스텀 선택 로직을 완전히 제어하고 유연하게 구성할 수 있습니다. 전체 필터링 패턴과 예제는 자동 완성 가이드를 참고하세요.

읽기 전용 모드

읽기 전용 콤보박스와 리스트박스를 결합해서 키보드 탐색과 스크린 리더를 지원하는 단일 선택 드롭다운을 만드는 패턴입니다.

텍스트 입력 없이 드롭다운을 열려면 버튼을 호스트 트리거로 사용하거나, 입력 트리거에 네이티브 HTML readonly 어트리뷰트를 적용하면 됩니다. 클릭하거나 방향키를 누르면 팝업이 열립니다.

이 구성은 선택과 다중 선택 패턴의 기반이 됩니다. 트리거와 오버레이 위치 지정을 포함한 완전한 드롭다운 구현은 해당 가이드를 참고하세요.

날짜 선택기 그리드

콤보박스를 2차원 그리드와 연결해서 접근성을 지원하는 날짜 선택기를 만들 수 있습니다. 사용자는 달력 그리드 표 안에서 방향키로 날짜를 탐색하고 클릭하거나 Enter 또는 Spacebar를 눌러 선택을 확정합니다.

대화상자 팝업

대화상자 팝업은 콤보박스 트리거를 표준 대화상자 레이아웃 및 포커스 트랩(CDK의 cdkTrapFocus 등)과 결합합니다. 오버레이에 모달 동작이나 배경막과의 상호작용이 필요할 때 대화상자 팝업을 사용하세요.

테스트

Angular Aria는 콤보박스 컴포넌트를 테스트할 수 있는 ComboboxHarness를 제공합니다. 컴포넌트 테스트에서 하네스를 사용하는 예제는 다음과 같습니다.

import {ComponentFixture, TestBed} from '@angular/core/testing';
import {HarnessLoader} from '@angular/cdk/testing';
import {TestbedHarnessEnvironment} from '@angular/cdk/testing/testbed';
import {ComboboxHarness} from '@angular/aria/combobox/testing';
import {MyComboboxComponent} from './my-combobox'; // 테스트할 컴포넌트

describe('MyComboboxComponent', () => {
  let fixture: ComponentFixture<MyComboboxComponent>;
  let loader: HarnessLoader;

  beforeEach(async () => {
    TestBed.configureTestingModule({
      imports: [MyComboboxComponent],
    });

    fixture = TestBed.createComponent(MyComboboxComponent);
    await fixture.whenStable();
    loader = TestbedHarnessEnvironment.loader(fixture);
  });

  it('should allow opening and closing the popup', async () => {
    const combobox = await loader.getHarness(ComboboxHarness);

    // 초기 상태를 확인합니다.
    expect(await combobox.isOpen()).toBe(false);

    // 팝업을 엽니다.
    await combobox.open();
    expect(await combobox.isOpen()).toBe(true);

    // 팝업을 닫습니다.
    await combobox.close();
    expect(await combobox.isOpen()).toBe(false);
  });
});

API 레퍼런스

자세한 API 문서는 다음 API 레퍼런스를 참고하세요.

관련 패턴과 디렉티브

콤보박스는 다음 문서에서 설명하는 패턴의 기반 디렉티브입니다:

  • 자동 완성 - 필터링 및 추천 패턴 (입력 내용과 옵션 목록을 연결합니다)
  • 단일 선택 - 단일 선택 드롭다운 패턴 (편집할 수 없는 버튼 트리거에 직접 적용합니다)
  • 다중 선택 - 다중 선택 패턴 (편집할 수 없는 트리거에 적용하며, multi가 활성화된 리스트박스와 함께 사용합니다)

콤보박스는 일반적으로 다음 요소와 함께 사용합니다:

  • 리스트박스 - 가장 일반적인 팝업 콘텐츠
  • 트리 - 계층형 팝업 콘텐츠 (예제는 트리 가이드를 참고하세요)