# 목록에서 값 선택

지역·상태처럼 반복되는 고유 값에서 포함할 항목을 고르게 하는 필터입니다. 이름 일부를 입력하는 Text filter보다 가능한 선택지를 한눈에 보여 주기 좋습니다.

Canonical: https://grid.syidax.com/ko/docs/features/set-filter/

<a id="understand"></a>

## 동작 원리와 선택 기준

필터의 고유 값 목록과 필터가 적용될 전체 데이터 범위는 별개입니다. 원격 데이터에서는 로드되지 않은 값까지 목록에 포함할지 데이터 공급 설계에서 정해야 합니다.

이 기능을 제품에서 사용하려면 Pro 패키지와 유효한 라이선스가 필요합니다. 설정 이름이 같더라도 Community에서 Pro 기능이 활성화되는 것은 아닙니다.

코드의 grid는 설치와 연결 장에서 준비한 Grid 요소입니다. 예제마다 필요한 데이터·설정을 확인하고, 코드에서 소개하는 앱 함수와 서버 주소는 프로젝트에 맞게 구현하세요.

- [설치와 연결 · 공통 예제 데이터](https://grid.syidax.com/ko/docs/guides/getting-started.md)

<a id="example-1"></a>

## 예제 1. 지역 선택 목록

지역 열을 Set filter로 선언하고 필터 UI를 표시합니다.

```javascript
grid.headerFilterRow = true;
grid.columnDefs = grid.columnDefs.map(col => col.field === 'region' ? { ...col, filter: 'set' } : col);
```

결과 확인: 지역별 값을 선택할 수 있습니다. 빈 값과 문자열 공백도 같은 값으로 취급할지 확인하세요.

<a id="example-2"></a>

## 예제 2. 즐겨 쓰는 선택 복원

사용자가 APAC과 EMEA를 선택한 모델을 보관했다가 복원합니다.

```javascript
const saved = await grid.getFilterModel();
console.log(saved);
await grid.setFilterModel(saved);
```

결과 확인: 다시 같은 열과 데이터 구성을 준비하면 선택 조건을 복원할 수 있습니다. 전체 선택과 아무것도 선택하지 않음은 의미가 다를 수 있습니다.

<a id="example-3"></a>

## 예제 3. 목록 값이 바뀌는 데이터

새 지역이 추가되거나 기존 지역이 없어지면 저장된 선택 조건과 현재 값 목록의 교집합을 확인합니다. 없는 값을 선택한 모델 때문에 결과가 비어 있는지 살펴봅니다.

결과 확인: 사용자가 왜 결과를 못 보는지 설명할 수 있습니다. 데이터 갱신 후 선택 상태를 자동 해제할지 유지할지도 앱에서 일관되게 정하세요.

<a id="pitfalls"></a>

## 조합할 때와 문제를 해결할 때

Set filter와 rowSelection의 체크박스는 별개입니다. 필터 체크는 표시 대상을 고르고 행 체크는 업무 처리 대상을 고릅니다.

서버 필터는 클라이언트의 조건을 서버가 같은 문자열·빈 값 규칙으로 해석해야 결과 수가 일치합니다.

<a id="related-api"></a>

## 이 기능에 사용하는 API

- [filter](https://grid.syidax.com/ko/docs/columns/filter.md) — 이 열에 사용할 기본 필터 종류 또는 사용자 필터 정의입니다.

<a id="next"></a>

## 함께 읽기

- [행·열·ID의 관계](https://grid.syidax.com/ko/docs/guides/concepts.md)
- [결과와 이벤트 연결](https://grid.syidax.com/ko/docs/guides/data-event-access.md)
- [Features에서 살펴보기](https://grid.syidax.com/grid/set-filter) — 직접 체험 가능한 범위는 해당 가이드에 안내되어 있습니다.