# 화면 상태 저장과 복원

화면 상태는 열 너비·순서·정렬·필터·선택 등 사용자의 작업 구성을 저장합니다. 원본 주문 값을 백업하는 데이터 스냅샷과 구분해야 합니다.

Canonical: https://grid.syidax.com/ko/docs/guides/grid-state/

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

## 동작 원리와 선택 기준

getState()는 버전이 포함된 상태 객체를 반환합니다. setState()는 적용한 부분과 문제를 보고하므로 복원 요청이 항상 전부 성공했다고 가정하지 마세요.

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

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

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

## 예제 1. 사용자별 화면 저장

데이터와 열 구성이 준비된 Grid에서 상태를 읽습니다.

```javascript
const state = await grid.getState();
localStorage.setItem('orders-grid-state', JSON.stringify(state));
```

결과 확인: 브라우저에 현재 구성을 저장합니다. 여러 사용자나 다른 표의 상태가 섞이지 않도록 키에 사용자·화면 구분을 넣을 수 있습니다.

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

## 예제 2. 기존 화면에 복원

저장한 JSON의 파싱 실패를 앱에서 처리합니다.

```javascript
const text = localStorage.getItem('orders-grid-state');
if (text) {
  const report = await grid.setState(JSON.parse(text));
  console.log(report);
}
```

결과 확인: 열이 삭제되었거나 지원하지 않는 상태가 있으면 보고서를 읽고 사용자에게 부분 복원 사실을 안내합니다.

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

## 예제 3. 첫 렌더와 열 상태만 저장

처음부터 복원하려면 마운트 전에 initialState를 전달합니다. 열 배치만 필요하면 getColumnState()/applyColumnState()를 사용해 저장 범위를 줄입니다.

결과 확인: 초기 상태는 처음 한 번 적용됩니다. 이미 실행 중인 Grid의 복원은 setState()를 사용합니다. 콜백 함수와 원본 데이터는 JSON 상태에서 다시 만들어지지 않습니다.

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

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

같은 데이터의 안정적인 ID와 열 식별자가 있어야 선택·포커스 복원이 의미 있습니다. 삭제된 행을 억지로 다시 선택하지 마세요.

getStateCaptureReport()와 복원 보고서를 확인해 생략된 정보가 있는지 점검합니다. 원본 값 복원은 snapshots를 사용합니다.

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

## 이 기능에 사용하는 API

공통 설정과 아래 관련 문서를 함께 참고하세요.

- [Grid 속성](https://grid.syidax.com/ko/docs/options.md)
- [열 설정](https://grid.syidax.com/ko/docs/columns.md)
- [메서드](https://grid.syidax.com/ko/docs/methods.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/grid-state) — 직접 체험 가능한 범위는 해당 가이드에 안내되어 있습니다.