React ComboBox Overview

    React ComboBox는 사용자가 제공된 목록에서 다양한 미리 정의된 옵션을 쉽게 선택, 필터링 및 그룹화할 수 있는 가벼운 편집기입니다. 이 구성 요소는 React ComboBox 키보드 탐색, 항목, 헤더 및 푸터가 표시되는 방식을 사용자 정의하는 템플릿에 대한 옵션도 지원합니다.

    Ignite UI for React는 사용자가 선택할 수 있는 옵션 목록을 제공합니다. 모든 옵션을 가상화된 항목 목록에 표시하므로 ComboBox는 동시에 수천 개의 레코드를 표시할 수 있으며, 여기서 하나 이상의 옵션을 선택할 수 있습니다. 또한 이 구성 요소는 대소문자 구분 필터링, 그룹화, 복잡한 데이터 바인딩 등을 제공합니다.

    React ComboBox Example

    Getting Started with React ComboBox

    먼저, 다음 명령을 실행하여 Ignite UI for React 설치해야 합니다.

    npm install igniteui-react

    그 다음 ReactIgrCombo와 필요한 CSS를 가져오세요:

    import { IgrCombo } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

    [!WARNING] The IgrCombo component doesn't work with the standard <form> element. Use Form instead.

    그런 다음 옵션 목록을 작성하는 데 사용되는 콤보 데이터 소스에 개체 배열을 바인딩합니다.

    interface City {
  id: string;
  name: string;
}

const cities: City[] = [
  { name: "London", id: "UK01" },
  { name: "Sofia", id: "BG01" },
  { name: "New York", id: "NY01" },
];

<IgrCombo
    valueKey="id"
    displayKey="name"
    data={cities}
    value={["BG01"]}
></IgrCombo>

    Data value and display properties

    콤보가 복잡한 데이터(예: 개체) 목록에 바인딩된 경우 컨트롤이 항목 선택을 처리하는 데 사용할 속성을 지정해야 합니다. 구성 요소는 다음 속성을 노출합니다.

    • T-필요, 만약 이 생략된 경우valueKey, 이 값은 "object"로 설정해야 하며, 그렇지 않으면 속성 유형valueKey과 일치해야 합니다.
    • valueKey-선택 사항, 복잡한 데이터 객체에 필수- 데이터 소스의 어떤 필드를 선택에 사용할지 결정합니다. 만약 를 생략하면valueKey 선택 API는 객체 참조를 사용하여 항목을 선택합니다.
    • displayKey-선택사항, 복잡한 데이터 객체에 권장 됨 - 데이터 소스에서 어떤 필드를 표시 값으로 사용할지 결정합니다. 만약 에displayKey 대한 값이 지정되어 있지 않으면, 콤보는 지정된valueKey 값을 사용합니다(있다면). 저희 경우에는 콤보가 각 도시의 '를name 표시하고, 아이템 선택과 각 아이템의 기본 값으로 필드를 사용id 하기를 원합니다. 따라서 우리는 각각 와valueKey의 조합displayKey에 이러한 성질을 부여합니다.

    [!Note] When the data source consists of primitive types (e.g. strings, numbers, etc.), do not specify a valueKey and/or displayKey.

    Setting Value

    ComboBox 컴포넌트는 속성(값이라고도 함) 외에 게터와 세터를 노출합니다value. value 속성을 사용해 선택한 항목을 컴포넌트 초기화 시 설정할 수 있습니다.

    값을 읽고 싶다면, 즉 현재 선택된 항목 목록을 읽거나 값을 업데이트하려면 각각 값 게터와 세터를 사용하세요. 가치 획득자는 선택된 모든 항목의 목록을 반환합니다.valueKey 마찬가지로, 값 세터를 사용해 선택한 항목 목록을 업데이트하고 싶다면, 항목valueKey 별 목록을 제공해야 합니다.

    본보기:

    const comboRef = useRef<IgrCombo>(null);

// Given the overview example from above this will return ['BG01']
console.log(comboRef.current.value);

// Change the selected items to New York and London
comboRef.current.value = ['NY01', 'UK01'];

    Selection API

    콤보 구성 요소는 현재 선택한 항목을 변경할 수 있는 API를 노출합니다.

    사용자 상호작용을 통해 옵션 목록에서 항목을 선택하는 것 외에도, 프로그래밍적으로 아이템을 선택할 수 있습니다. 이 과정은 ANDselect 메서드를 통해deselect 이루어집니다. 두 메서드 모두에 항목 배열을 전달할 수 있습니다. 메서드를 인수 없이 호출하면 호출된 메서드에 따라 모든 항목이 선택/해제됩니다. 콤보 컴포넌트에 avalueKey를 지정했다면, 선택하고 제거하고 싶은 항목의 값 키를 전달해야 합니다:

    일부 항목을 선택/해제하세요

    // Select/deselect items by their IDs as valueKey is set to 'id'
comboRef.current.select(["UK01", "UK02", "UK03", "UK04", "UK05"]);
comboRef.current.deselect(["UK01", "UK02", "UK03", "UK04", "UK05"]);

    모든 항목을 선택/해제하세요

    // Select/deselect all items
comboRef.current.select([]);
comboRef.current.deselect([]);

    이 속성이valueKey 생략된 경우, 선택/해제하고 싶은 항목을 객체 참조로 지정해야 합니다:

    // Select/deselect values by object references when no valueKey is provided
comboRef.current.select([cities[1], cities[5]]);
comboRef.current.deselect([cities[1], cities[5]]);

    Validation

    Ignite UI for React 콤보 컴포넌트는 대부분의IgrInput 속성, 예를 들어required​disabled​autofocus​invalid 지원합니다. 이 컴포넌트는 또한 검증에 묶인 두 가지 메서드를 노출합니다:

    • reportValidity- 유효성을 검사하고 구성 요소가 검증 제약 조건을 만족하면 참을 반환합니다.
    • checkValidity- 네이티브 입력 API를 준수하는 랩퍼를 포함하는 reportValidity.

    Keyboard Navigation

    콤보 구성요소에 초점이 맞춰져 있고 옵션 목록이 표시되지 않는 경우:

    • ​Down/Alt + Down 키를 사용하여 옵션 목록을 엽니다.

    콤보 구성요소에 초점이 맞춰져 있고 옵션 목록이 표시되는 경우:

    • ​아래쪽 키를 사용하면 목록의 다음 항목이 활성화됩니다.
    • ​위쪽 키를 사용하면 목록의 이전 항목이 활성화됩니다. 첫 번째 항목이 이미 활성화되어 있으면 입력에 초점을 맞춥니다.
    • 또는 END 키를 사용하면 HOME 목록의 첫 번째 또는 마지막 항목이 활성화됩니다.
    • 키를 사용하면 SPACE 활성 항목이 선택됩니다.
    • 키를 사용하면 ENTER 활성 항목이 선택되고 옵션 목록이 닫힙니다.
    • or TAB/SHIFT + TAB 키를 사용하면 ESC 옵션 목록이 닫힙니다.

    Styling

    아래에 나열된 노출된 CSS 부품을 사용하여 컴포넌트IgrCombo와 그 항목의 외관을 변경할 수 있습니다:

    부품명 설명
    label 캡슐화된 텍스트 레이블입니다.
    input 기본 입력 필드입니다.
    native-input 기본 입력 필드의 기본 입력입니다.
    prefix 접두사 래퍼.
    suffix 접미사 래퍼.
    toggle-icon 토글 아이콘 래퍼.
    clear-icon 명확한 아이콘 래퍼.
    case-icon 필터 입력의 접미사 내부에 콘텐츠를 렌더링하는 케이스 아이콘 래퍼입니다.
    helper-text 도우미 텍스트 래퍼입니다.
    search-input 검색 입력 필드입니다.
    list-wrapper 옵션 래퍼 목록입니다.
    list 옵션 상자 목록입니다.
    item 옵션 목록의 각 항목을 나타냅니다.
    group-header 옵션 목록의 각 헤더를 나타냅니다.
    active 항목이 활성화되면 항목 부품 목록에 추가됩니다.
    selected 항목을 선택하면 항목 부품 목록에 추가됩니다.
    checkbox 각 목록 항목의 각 확인란을 나타냅니다.
    checkbox-indicator 각 목록 항목의 확인란 표시를 나타냅니다.
    checked 확인란을 선택하면 확인란 부품 목록에 추가됩니다.
    header 헤더 내용을 담고 있는 컨테이너입니다.
    footer 바닥글 콘텐츠를 담는 컨테이너입니다.
    empty 빈 콘텐츠를 담는 컨테이너입니다.

    CSS 부분을 사용하여 콤보 스타일을 완전히 제어할 수 있습니다.

    igc-combo::part(search-input) {
  background-color: var(--ig-gray-100);
  border-radius: 2px;
}

igc-combo::part(input) {
  background-color: var(--ig-gray-100);
}

igc-combo::part(prefix) {
  background-color: var(--ig-secondary-50);
  color: var(--ig-primary-500);
}

igc-combo::part(toggle-icon) {
  color: var(--ig-primary-500);
}

    API Reference

    Additional Resources