# 로딩과 빈 결과

로딩과 빈 데이터 안내는 표가 아무것도 보여 주지 않는 이유를 설명합니다. 요청 중·조회 결과 없음·실패는 서로 다른 상태이므로 같은 빈 화면으로 처리하지 않습니다.

Canonical: https://grid.syidax.com/ko/docs/features/overlays/

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

## 동작 원리와 선택 기준

앱이 데이터를 읽는 동안 loading을 켜고 성공·실패와 관계없이 종료 시 해제합니다. 빈 결과 문구는 showEmptyState와 emptyMessage로 준비하고, 요청 오류의 재시도는 앱에서 제공합니다.

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

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

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

## 예제 1. 처음 조회하기

readOrders는 앱에서 구현한 데이터 조회 함수라고 가정합니다.

```javascript
grid.loading = true;
grid.loadingMessage = '주문을 불러오고 있습니다.';
try {
  grid.rowData = await readOrders();
} finally {
  grid.loading = false;
}
```

결과 확인: 성공하면 표가 표시되고 실패해도 로딩 표시가 남지 않습니다. 오류는 호출한 앱에서 안내해야 합니다.

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

## 예제 2. 조회 결과가 없을 때

빈 배열도 정상적인 조회 결과일 수 있습니다.

```javascript
grid.showEmptyState = true;
grid.emptyMessage = '조건에 맞는 주문이 없습니다. 검색 조건을 확인하세요.';
grid.rowData = [];
```

결과 확인: 사용자가 검색 조건을 바꿔야 하는지 알 수 있습니다. 아직 요청 중이라면 빈 상태보다 로딩 상태를 보여 주세요.

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

## 예제 3. 빠른 재조회와 깜박임

짧은 요청이 반복되면 minLoadingDuration으로 표시 시간을 조절하고, 기존 데이터 유지 여부는 앱의 업무 흐름에 맞춥니다.

결과 확인: 필터를 연속 변경할 때 이전 응답이 나중에 도착해 최신 결과를 덮어쓰지 않도록 앱의 취소·요청 순서 처리를 함께 구현합니다.

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

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

빈 데이터와 서버 오류를 같은 문구로 표현하지 마세요. 재시도 가능 여부와 실패 원인을 별도로 안내합니다.

장시간 로딩 화면에만 의존하지 말고 진행 상태·취소·재시도 등 필요한 앱 동작을 준비합니다.

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

## 이 기능에 사용하는 API

- [showEmptyState](https://grid.syidax.com/ko/docs/options/showEmptyState.md) — 데이터가 없을 때 빈 상태 안내를 표시합니다. 요청 실패와 정상적인 빈 결과를 앱에서 구분합니다.
- [emptyMessage](https://grid.syidax.com/ko/docs/options/emptyMessage.md) — 원본 데이터가 비어 있을 때 보여 줄 안내 문구입니다.
- [noMatchesMessage](https://grid.syidax.com/ko/docs/options/noMatchesMessage.md) — 데이터는 있지만 현재 검색·필터에 맞는 행이 없을 때의 문구입니다.
- [clearFiltersLabel](https://grid.syidax.com/ko/docs/options/clearFiltersLabel.md) — 빈 결과 화면에서 필터를 지우는 작업의 버튼 문구입니다.
- [loading](https://grid.syidax.com/ko/docs/options/loading.md) — 앱의 데이터 요청 진행 상태를 표시합니다. 요청이 성공하거나 실패한 뒤 모두 해제하세요.
- [loadingMessage](https://grid.syidax.com/ko/docs/options/loadingMessage.md) — 로딩 중 사용자에게 보여 줄 설명입니다.
- [loadingMode](https://grid.syidax.com/ko/docs/options/loadingMode.md) — Grid의 로딩 표시 방식을 선택합니다. 지원 값은 LoadingMode 타입에서 확인합니다.
- [minLoadingDuration](https://grid.syidax.com/ko/docs/options/minLoadingDuration.md) — 로딩 표시가 너무 짧게 깜박이지 않도록 유지할 최소 시간입니다.
- [emptyStateActionClicked](https://grid.syidax.com/ko/docs/events/emptyStateActionClicked.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/overlays) — 직접 체험 가능한 범위는 해당 가이드에 안내되어 있습니다.