DataGrid 계층
DataGrid를 목적별로 빠르게 적용할 수 있도록 기능/활용 시나리오를 분리한 문서 모음입니다.
reopt design업데이트
편집형 그리드, 성능 튜닝, 원격 연동 계약, 컬럼/selection 모델처럼 DataGrid 고유 문제를 담당합니다.
Package boundary: @reopt-ai/opt-datagrid는 root export 하나로 DataGrid, remote datasource hooks, column hooks, AI invalidation helpers를 제공합니다. 별도 CSS import는 없고, 런타임 peer dependency는 React/React DOM입니다. 대규모 데이터에서는 getRowId, valueCache, rowBufferPx, maxRenderedRows를 먼저 결정한 뒤 remote protocol을 붙이는 순서가 안전합니다.
DataGrid의 전체 기능을 한 화면에서 실험하려면 Fullscreen Playground를 사용하세요.
Playground 열기1. 변형 기반 빠른 미리보기
하나의 엔진으로 편집형, 운영형, 대용량형 UX를 구성할 수 있습니다. 아래 탭으로 빠르게 체험한 뒤 세부 문서로 들어가서 구현 패턴을 확인하세요.
스프레드시트 스타일로 즉시 편집 가능한 기본 데이터그리드. 셀 커밋 로그를 확인할 수 있습니다.
Last commit: -
2. 기능별/활용별 문서
시작하기
설치, .npmrc 설정, 첫 DataGrid 렌더링까지의 빠른 시작 가이드
핵심 개념
컬럼 정의, 셀 편집 파이프라인, 가상화 모델, 선택/클립보드 아키텍처
편집형 데이터 입력
셀 편집, typed editor, custom editor component, 입력 검증/인터셉트 패턴
운영 모니터링
읽기 전용 운영 테이블과 상태/정렬 중심 가시화
대규모 데이터
getRowId, valueCache, rowBufferPx 중심의 대량 데이터 렌더링 가이드
원격 연동 계약
openView, window load, batch save, push invalidation까지 백엔드 계약 정리
마이그레이션 플레이북
기존 grid 모델을 opt-datagrid의 row, column, edit pipeline으로 옮기는 단계별 가이드
앱 조합 가이드
opt-ui 레이아웃 안에 DataGrid를 넣는 경계와 상위 상태 분리 기준
컬럼 설계 플레이북
getValue/setValue/renderCell과 custom editor component, 파생 컬럼 invalidation, renderer refresh 설계
Skills
설치, 마이그레이션, backend contract, 업그레이드, release action skill 정리
릴리즈 노트
opt-datagrid 버전별 변경 사항과 하이라이트
Hook 레퍼런스
useAsyncDataSource, useColumnSort 등 11개 Hook 시그니처와 사용 예제
타입 레퍼런스
DataGridColumn, DataGridSelection, 에디터 타입 등 핵심 타입 정의
3. 변형 선택 가이드
| 시나리오 | 적합한 상황 | 핵심 API |
|---|---|---|
| 편집형 데이터 입력 | 관리자가 테이블 안에서 바로 수정하고 저장 흐름을 처리해야 할 때 | onRowsChangeonCellCommitonCellsEditedonPaste |
| 운영 모니터링 | 읽기 전용 운영 대시보드에서 상태/지표를 빠르게 스캔해야 할 때 | onHeaderMenuActiononVisibleRegionChangedheight |
| 대규모 데이터 | 수천 행 이상 데이터를 스크롤하며 지연 로딩을 연결할 때 | getRowIdvalueCachevalueCacheStrategyrowBufferPxmaxRenderedRowsonVisibleRegionChanged |
| 컬럼 설계 플레이북 | 여러 화면에서 컬럼 스키마를 재사용하고 진화시켜야 할 때 | onColumnsChangeonColumnResizeonColumnMovedonHeaderMenuAction |
4. Performance Model
DataGrid의 성능 문서는 외부 비교보다 내부 비용 구조를 설명하는 데 집중합니다. 아래 다섯 축을 기준으로 어떤 설정이 어떤 비용을 줄이는지 먼저 확인한 뒤 scale preset을 맞추는 편이 좋습니다.
Stable row identity
`getRowId`는 sort/reorder 이후에도 rendered row key와 refresh intent를 안정적으로 유지합니다.
Cached value access
`valueCache`는 active cell 이동이나 selection 변화처럼 interaction-only update에서 `getValue` 재계산을 줄입니다.
Pixel-based row buffering
`rowBufferPx`와 `maxRenderedRows`는 dynamic row height와 큰 viewport에서 render window를 더 안정적으로 제어합니다.
Renderer reuse
`rendererRefreshMode`와 `refreshCellRenderer`는 mount 비용이 큰 셀을 remount 대신 reuse하도록 돕습니다.
Benchmark regression checks
`benchmark`, baseline, history 흐름으로 감에 의존하지 않고 변경 전후를 비교할 수 있습니다.
5. Recommended Scale Config
대규모 데이터셋의 시작점은 `getRowId`, `valueCache`, `valueCacheStrategy="row-id"`, `rowBufferPx`, `maxRenderedRows` 조합입니다. 이후에만 도메인별 viewport sync나 renderer reuse 정책을 추가하세요.
import { DataGrid } from "@reopt-ai/opt-datagrid";
<DataGrid
rows={rows}
columns={columns}
getRowId={(row) => String(row.id)}
valueCache
valueCacheStrategy="row-id"
rowBufferPx={480}
maxRenderedRows={600}
height={440}
ariaLabel="Scale grid"
/>;6. API 매트릭스
아래 목록은 callback만이 아니라 성능을 조정하는 tuning surface도 함께 포함합니다. 특히 `getRowId`, `valueCache`, `rowBufferPx` 같은 항목은 대규모 데이터셋의 비용 구조를 먼저 결정합니다.
입력/변경 파이프라인
셀 편집, 붙여넣기, 삭제, 배치 변경을 제어합니다.
onRowsChange내부 편집 결과를 외부 rows 상태로 반영하는 기본 콜백
onCellCommit한 셀 편집 커밋 시점의 이전/다음 값을 수집
onCellsEdited붙여넣기/삭제/fill-handle 일괄 변경을 가로채는 훅
onPaste클립보드 파싱 결과를 직접 적용하거나 차단
onDelete선택 영역 삭제 동작을 도메인 정책으로 제어
onFillPatternfill handle 드래그 확장 규칙을 커스터마이즈
선택/포커스 제어
활성 셀과 선택 영역을 외부 상태로 제어합니다.
initialActiveCell초기 포커스 셀 좌표 지정
gridSelection선택 영역 제어형 모드 입력값
onActiveCellChange활성 셀 이동 추적
onGridSelectionChange선택 영역 변경 추적
컬럼 인터랙션
리사이즈/재정렬/헤더 메뉴 동작을 도메인 로직에 연결합니다.
onColumnsChange컬럼 배열 제어형 모드 업데이트
onColumnResize사용자 리사이즈 결과를 저장
onColumnMoved드래그 재정렬 결과를 저장
onHeaderClicked헤더 클릭을 정렬/필터 UI 트리거로 연결
onHeaderMenuClick헤더 메뉴 버튼 오픈 액션을 커스터마이즈
onHeaderMenuAction헤더 메뉴 액션(sort 등)을 도메인 정렬 로직에 연결
성능/뷰포트
row identity, value recomputation, pixel buffer, renderer reuse를 튜닝합니다.
height그리드 viewport 높이
rowHeight행 높이 튜닝값
rowBufferPxdynamic row height에 맞는 pixel-based render buffer
maxRenderedRows과도한 render window를 안전하게 제한하는 상한
getRowId정렬/삽입/reorder 이후에도 stable row identity를 유지
valueCacheinteraction-only update에서 getValue 재계산을 줄이는 캐시
valueCacheStrategyvalue cache identity를 row-ref 또는 row-id로 선택
rendererRefreshMode비용이 큰 셀에서 remount 대신 renderer reuse 정책을 제어
onVisibleRegionChanged현재 뷰포트 행/열 범위 변경 이벤트
7. 기본 사용 코드
import * as React from "react";
import { DataGrid, type DataGridColumn } from "@reopt-ai/opt-datagrid";
interface TeamRow {
id: number;
name: string;
role: string;
}
const columns: DataGridColumn<TeamRow>[] = [
{
id: "name",
title: "Name",
width: 200,
editable: true,
getValue: (row) => row.name,
setValue: (row, nextValue) => ({ ...row, name: nextValue }),
},
{
id: "role",
title: "Role",
width: 160,
editable: true,
getValue: (row) => row.role,
setValue: (row, nextValue) => ({ ...row, role: nextValue }),
},
];
export function Example() {
const [rows, setRows] = React.useState<TeamRow[]>([
{ id: 1, name: "Mina", role: "Owner" },
{ id: 2, name: "Joon", role: "Editor" },
]);
return (
<DataGrid
rows={rows}
columns={columns}
onRowsChange={(nextRows) => setRows(Array.from(nextRows))}
height={420}
ariaLabel="Team grid"
/>
);
}