# 셀 표현 바꾸기

셀 렌더러는 데이터의 표시 방법을 바꿉니다. 상태 배지·링크·액션 버튼이 필요한 경우 사용하되 정렬·필터에 사용할 원본 값은 별도로 유지합니다.

Canonical: https://grid.syidax.com/ko/docs/features/custom-cells/

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

## 동작 원리와 선택 기준

단순 숫자 포맷은 valueFormatter가 더 간단합니다. 구조나 상호작용이 필요할 때 cellRenderer를 선택하고 반환값은 text·html·vnode 중 하나의 계약을 지킵니다.

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

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

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

## 예제 1. 안전한 텍스트와 보조 설명

문자열을 HTML로 해석하지 않고 표시합니다.

```javascript
grid.columnDefs = [{
  field: 'status', headerName: '상태',
  cellRenderer: params => ({ kind: 'text', text: String(params.value ?? '-'), title: '주문의 현재 처리 상태' }),
}];
```

결과 확인: 사용자 입력에 꺾쇠가 있어도 실행되는 HTML이 아닌 문자로 표시됩니다.

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

## 예제 2. 표시와 편집 분리

통화 표시에는 valueFormatter, 금액 수정에는 number 편집기를 설정합니다. 렌더러를 붙였다는 이유만으로 편집기를 직접 구현할 필요는 없습니다.

결과 확인: 보기 상태의 통화 기호와 실제 저장 숫자를 분리합니다. 편집 완료 뒤 정렬과 합계가 숫자를 기준으로 동작하는지 확인하세요.

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

## 예제 3. 액션이 있는 셀

프레임워크에서 vnode 렌더러를 사용해 상세 보기 버튼을 만듭니다. 버튼의 accessible name에는 행을 식별할 수 있는 설명을 붙이고, 클릭 시 앱의 상세 화면을 엽니다.

결과 확인: 가상 스크롤로 셀이 재사용될 수 있으므로 현재 params의 행을 참조합니다. 이벤트 리스너와 외부 자원은 렌더러 수명에 맞춰 정리합니다.

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

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

kind: html은 신뢰할 수 있는 정제된 HTML만 사용하세요. Grid가 앱의 임의 HTML을 자동으로 안전하게 바꾼다고 가정하면 안 됩니다.

렌더러 내부에서 매번 서버 요청이나 큰 계산을 실행하면 스크롤이 느려집니다. 데이터 준비 단계에서 값을 계산하거나 캐시합니다.

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

## 이 기능에 사용하는 API

- [components](https://grid.syidax.com/ko/docs/options/components.md) — 이 Grid에서 사용할 사용자 정의 렌더러·편집기·필터 등의 로컬 컴포넌트 정의를 등록합니다.
- [componentTimeoutMs](https://grid.syidax.com/ko/docs/options/componentTimeoutMs.md) — 비동기 사용자 컴포넌트를 준비할 때 기다릴 최대 시간입니다. 지연·실패는 componentError와 함께 처리하세요.
- [cellRenderer](https://grid.syidax.com/ko/docs/columns/cellRenderer.md) — 셀을 text·html·vnode 또는 등록된 사용자 렌더러로 표시합니다.
- [cellRendererMeta](https://grid.syidax.com/ko/docs/columns/cellRendererMeta.md) — 셀 렌더러에 전달할 추가 메타데이터입니다.
- [cellClass](https://grid.syidax.com/ko/docs/columns/cellClass.md) — 셀에 적용할 CSS 클래스 또는 클래스를 반환하는 콜백입니다.
- [cellClassRules](https://grid.syidax.com/ko/docs/columns/cellClassRules.md) — 조건별로 CSS 클래스를 적용하는 규칙입니다.
- [cellStyle](https://grid.syidax.com/ko/docs/columns/cellStyle.md) — 셀에 적용할 인라인 스타일 객체·콜백 또는 이들의 배열입니다.
- [registerCellRenderer](https://grid.syidax.com/ko/docs/methods/registerCellRenderer.md) — 이름으로 셀 렌더러를 등록하고 결과를 반환합니다.
- [listRegisteredCellRenderers](https://grid.syidax.com/ko/docs/methods/listRegisteredCellRenderers.md) — 사용 가능한 등록 셀 렌더러 이름 목록을 읽습니다.
- [unregisterCellRenderer](https://grid.syidax.com/ko/docs/methods/unregisterCellRenderer.md) — 이름으로 등록한 셀 렌더러를 해제합니다.
- [registerGridComponent](https://grid.syidax.com/ko/docs/methods/registerGridComponent.md) — 공개 컴포넌트 계약에 따라 사용자 Grid 컴포넌트를 등록합니다.
- [replaceGridComponent](https://grid.syidax.com/ko/docs/methods/replaceGridComponent.md) — 등록된 사용자 컴포넌트 정의를 교체합니다.
- [unregisterGridComponent](https://grid.syidax.com/ko/docs/methods/unregisterGridComponent.md) — 등록된 사용자 컴포넌트를 해제하고 성공 여부를 반환합니다.
- [getRegisteredGridComponentNames](https://grid.syidax.com/ko/docs/methods/getRegisteredGridComponentNames.md) — 현재 등록된 사용자 Grid 컴포넌트 이름을 읽습니다.
- [getCellRendererInstance](https://grid.syidax.com/ko/docs/methods/getCellRendererInstance.md) — 현재 마운트된 셀 렌더러 인스턴스를 조회합니다. 가상화로 화면 밖 셀은 마운트되지 않을 수 있습니다.
- [destroyCellRendererInstance](https://grid.syidax.com/ko/docs/methods/destroyCellRendererInstance.md) — 지정한 마운트 셀 렌더러 인스턴스를 해제합니다.
- [focusCellRendererInstance](https://grid.syidax.com/ko/docs/methods/focusCellRendererInstance.md) — 지정한 마운트 셀 렌더러 내부로 포커스를 이동하고 결과를 반환합니다.
- [componentError](https://grid.syidax.com/ko/docs/events/componentError.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/custom-cells) — 직접 체험 가능한 범위는 해당 가이드에 안내되어 있습니다.