Grid · Props
@baneung-pack/grid의 전체 props와 GridColumn 필드, GridHandle ref API 레퍼런스.
GridProps
| Property | Type | 기본값 | 설명 |
|---|---|---|---|
| columns | GridColumn<TRow>[] | 필수 | 컬럼 정의 배열 |
| data | TRow[] | 필수 | 행 데이터 배열 |
| virtualized | boolean | false | 가상화 활성. 1000+ 행 권장 |
| rowHeight | number | 36 | 가상화 모드에서 행 높이(px) |
| height | number | string | 400 | 컨테이너 높이 |
| autoSize | boolean | false | 부모 컨테이너에 꽉 맞춤 (height 무시) |
| pageSize | number | 0 | > 0 이면 페이지네이션 활성 |
| showPagination | boolean | true | 내장 페이지네이션 UI 표시. 외부 페이징 사용 시 false |
| page | number | - | controlled 페이지 (1-based) |
| onPageChange | (page: number) => void | - | controlled 모드 콜백 |
| emptyState | ReactNode | - | 데이터 없을 때 표시 |
| getRowId | (row, idx) => string | number | - | 행 키 추출. 편집/선택/트리 사용 시 필수 권장 |
| selectable | boolean | false | 첫 컬럼에 체크박스 자동 추가 |
| onRowChange | (row, id) => void | - | 편집 commit 시 콜백 |
| tree | boolean | false | Tree(계층) 모드 활성 |
| getChildren | (row) => TRow[] | undefined | - | tree=true 시 자식 추출 함수 (필수) |
| defaultExpandedIds | 'all' | 'none' | (string | number)[] | 'none' | 초기 펼침 상태 |
| cellSelection | 'none' | 'single' | 'multi' | 'single' | 셀 선택 모드 |
| clearOnDelete | boolean | false | Delete/Backspace 키로 선택 셀 값 클리어 |
| clipboard | boolean | false | Ctrl+C/V로 Excel 호환 클립보드 (TSV) |
| quickFilter | string | - | 모든 visible 컬럼 부분 일치 검색 |
| resizable | boolean | false | 헤더 우측 드래그로 컬럼 폭 조절 |
| onColumnResize | (colId, width) => void | - | 리사이즈 콜백 (영속화용) |
| reorderable | boolean | false | 헤더 drag&drop으로 컬럼 순서 변경 (pin 그룹 내) |
| onColumnReorder | (order: string[]) => void | - | 순서 변경 콜백 |
| columnVisibility | Record<string, boolean> | - | controlled 표시/숨김 |
| onColumnVisibilityChange | (v) => void | - | 표시/숨김 변경 콜백 |
| showColumnMenu | boolean | false | 우상단 ⚙️ 컬럼 표시 메뉴 버튼 |
| showFooter | boolean | false | column.aggregate 푸터 행 표시 |
| contextMenu | boolean | (ctx) => Item[] | - | 우클릭 메뉴 (기본 또는 동적) |
| viewKey | string | - | 정렬/폭/표시/순서 localStorage 자동 저장 키 |
| onViewChange | (view) => void | - | view 변경 콜백 (외부 영속화) |
| ref | Ref<GridHandle<TRow>> | - | imperative API 접근 |
GridColumn 필드
| Property | Type | 기본값 | 설명 |
|---|---|---|---|
| id | string | 필수 | 컬럼 고유 식별자 |
| header | ReactNode | 필수 | 헤더 표시 노드 |
| accessor | keyof TRow | (row) => unknown | 필수 | 행에서 값 추출 (key 또는 함수) |
| width | number | string | - | 셀 너비 (px 또는 CSS) |
| minWidth / maxWidth | number | - | 리사이즈 시 폭 범위 |
| resizable | boolean | - | 개별 리사이즈 예외 |
| draggable | boolean | - | 개별 reorder 예외 |
| pin | 'left' | 'right' | - | 좌/우 sticky 고정 |
| hidden | boolean | false | 초기 숨김 |
| hideable | boolean | true | 컬럼 메뉴에서 토글 허용 여부 |
| align | 'left' | 'center' | 'right' | 'left' | 컬럼 정렬 |
| renderer | 'text' | 'progress' | 'date' | (v, r) => ReactNode | 'text' | 셀 렌더링 방식 |
| cellStyle | (v, r) => CSSProperties | - | 값/행 기준 인라인 스타일 |
| cellClassName | (v, r) => string | - | 값/행 기준 클래스 |
| aggregate | 'sum'|'avg'|'count'|'min'|'max' | (rows) => ReactNode | - | 푸터 집계 (showFooter=true 필요) |
| editable | boolean | false | 더블클릭 인라인 편집 활성 |
| editor | 'text' | 'number' | 'date' | 'dropdown' | 'text' | 편집 모드 input 종류 |
| options | { value, label }[] | - | editor='dropdown' 시 선택지 |
| min / max | number | 0 / 100 | renderer='progress' 범위 |
| dateFormat | string | 'YYYY-MM-DD' | renderer='date' 포맷 (YYYY/MM/DD/HH/mm/ss) |
| sortable | boolean | false | 헤더 클릭 정렬 (3-state). Shift+클릭=다중 |
| filterable | boolean | false | 헤더 funnel + popover 필터 |
GridHandle (ref API)
| 메서드 | 반환 | 설명 |
|---|---|---|
| getSavedData() | TRow[] | 편집 반영, 삭제 제외한 현재 데이터 |
| getChangedData() | TRow[] | 편집된 행만 (PATCH 페이로드) |
| getDeletedData() | TRow[] | 삭제된 행의 원본 스냅샷 |
| getSelectedIds() | (string | number)[] | 체크박스로 선택된 행 ID |
| deleteSelected() | void | 체크박스 선택 행을 모두 삭제 bucket으로 |
| clearSelection() | void | 체크박스 선택 해제 |
| reset() | void | 편집·삭제·추가 내역 폐기, 원본 복원 |
| addRow(row, position) | void | 행 추가: 'first' | 'last' | 'above-active' | 'below-active' |
| removeSelectedRows() | void | 셀 선택된 행을 모두 삭제 bucket으로 |
| clearSelectedCells() | void | 셀 선택된 셀의 값을 빈 문자열로 |
| exportCsv(filename?, options?) | void | CSV 다운로드 (UTF-8 BOM, Excel 호환) |
| exportXlsx(options?) | Promise<void> | XLSX 다운로드 (exceljs 동적 로드) |
| getColumnVisibility() | Record<string, boolean> | 표시/숨김 상태 반환 |
| toggleColumnVisibility(colId) | void | 표시/숨김 토글 |
| getView() | GridView | 현재 view 스냅샷 |
| setView(view) | void | view 부분 적용 |
| clearView() | void | view 초기 상태 리셋 |
💡 cellSelection ("none" | "single" | "multi")과 selectable은 별개 축입니다. cellSelection은 그리드 셀의 시각 선택, selectable은 체크박스 기반 행 선택.