# 실시간 열 API

실시간 열 객체는 현재 Grid와 연결된 참조입니다. 저장 가능한 열 상태 배열과 목적이 다릅니다. 특정 열을 조작하는 앱 UI에는 참조가 유용하고 사용자 설정 저장에는 상태 배열이 적합합니다.

Canonical: https://grid.syidax.com/ko/docs/features/column-api/

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

## 동작 원리와 선택 기준

getColumn은 열의 고유 이름을 받으며 존재하지 않는 이름에는 null이 올 수 있습니다. 열이 교체되거나 화면이 제거된 뒤 이전 참조가 계속 유효하다고 가정하지 마세요.

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

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

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

## 예제 1. 한 열과 전체 열 비교

제품 열 하나를 찾고 전체 열 목록도 조회합니다.

```javascript
const product = await grid.getColumn('product');
const columns = await grid.getColumns();
console.log(product, columns);
```

결과 확인: 하나의 참조와 참조 배열을 얻습니다. title이 아닌 field 또는 colId를 조회 이름으로 사용합니다.

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

## 예제 2. API와 화면 상태 연결

사용자가 드래그한 직후 현재 너비를 앱에 표시합니다.

```javascript
grid.addEventListener('columnResized', async () => {
  console.log(await grid.getColumnWidth('product'));
});
```

결과 확인: 처음 선언한 width가 아니라 현재 적용된 열 너비를 읽습니다. 이벤트 구독은 화면 해제 시 정리합니다.

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

## 예제 3. 저장용 데이터 읽기

실시간 객체를 직렬화하지 않고 전용 상태를 읽습니다.

```javascript
const state = await grid.getColumnState();
const json = JSON.stringify(state);
await grid.applyColumnState(JSON.parse(json));
```

결과 확인: 너비·순서·표시·고정 등의 상태를 저장 가능한 값으로 다룹니다. 전체 필터·선택 상태까지 필요하면 getState를 사용합니다.

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

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

컴포넌트 메서드가 Promise를 반환하므로 const column = grid.getColumn(...)만 쓰면 열이 아니라 Promise를 얻습니다. await를 사용하세요.

다중 Grid 화면에서는 어떤 요소에서 얻은 참조인지 유지하세요. 다른 Grid의 열 ID가 같아도 같은 열 객체가 아닙니다.

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

## 이 기능에 사용하는 API

- [getColumn](https://grid.syidax.com/ko/docs/methods/getColumn.md) — 식별자로 현재 열 객체를 찾습니다. 없는 열은 null이며 초기 columnDefs 복사본이 아닌 현재 상태를 조회합니다.
- [getColumns](https://grid.syidax.com/ko/docs/methods/getColumns.md) — 현재 열 객체 목록을 읽습니다. 열 너비·순서·표시 상태를 앱과 연결할 때 사용합니다.
- [getColumnGroup](https://grid.syidax.com/ko/docs/methods/getColumnGroup.md) — 식별자로 현재 열 그룹 객체를 찾습니다. 없는 그룹은 null입니다.
- [getColumnGroups](https://grid.syidax.com/ko/docs/methods/getColumnGroups.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/column-api) — 직접 체험 가능한 범위는 해당 가이드에 안내되어 있습니다.