Features

기본 Basics

정렬·필터·선택·페이지네이션 — 대부분의 그리드가 가장 먼저 필요로 하는 것들.

Sorting

헤더 클릭으로 오름차순 → 내림차순 → 해제 순환. Shift+클릭으로 다중 정렬(정렬 순서 배지 표시). sortModel로 초기 정렬을 지정할 수 있습니다.

Column Filters

헤더에 마우스를 올리면 나타나는 메뉴 버튼으로 컬럼별 필터를 엽니다. filter: 'text' · 'number' · 'set'. 여러 컬럼 필터는 AND로 결합됩니다.

Floating Filter (헤더 필터 행)

floatingFilter: true — 헤더 바로 아래에 컬럼별 인라인 필터 입력을 표시합니다. text/number는 입력하는 대로(250ms 디바운스) 필터링되고, set은 드롭다운으로 단일 값을 고릅니다. 필터 메뉴와 같은 필터 모델을 공유하므로 Esc로 지우거나 메뉴에서 바꾼 내용이 서로 반영됩니다.

Quick Filter

모든 컬럼을 대상으로 한 전역 검색 — 공백으로 구분된 모든 단어가 일치해야 합니다.

고급 필터 (Advanced Filter)

advancedFilter: true — AND/OR 그룹을 3단까지 중첩한 조건 트리를 만듭니다. 컬럼 필터와 배타가 아니라 AND로 합성되며, 지금 걸린 식은 항상 그리드 위 요약 바에 보입니다. 날짜 비교(before/after)와 빈 값(blank/notBlank)은 고급 필터에만 있습니다. API는 setAdvancedFilterModel() · getAdvancedFilterModel() · clearAdvancedFilter() · openAdvancedFilterBuilder().

Row Selection

rowSelection: 'multiple' — 체크박스, 헤더 전체 선택(부분 선택 시 indeterminate), Ctrl/⌘+클릭 토글, Shift+클릭 범위 선택.

Pagination

페이지 크기 선택, 처음/이전/번호/다음/마지막 버튼, "X to Y of Z" 요약. 페이지네이션을 끄면 전체 가상 스크롤로 동작합니다.

Basic Click & Pagination Events

cellClicked · rowClicked · rowDoubleClicked 이벤트는 클릭한 셀/행의 payload를 전달하고, paginationChanged는 페이지 이동·페이지 크기 변경 때 { page, pageSize }를 전달합니다 (page는 0부터).

컬럼 Columns

컬럼 정의·표시·헤더 구성. 값을 어떻게 보여줄지와 헤더를 어떻게 묶을지.

Column Pinning · Resize · Reorder

pinned: 'left' | 'right' 고정 컬럼(스크롤 시 그림자), 헤더 경계 드래그로 크기 조절, 경계 더블클릭으로 자동 맞춤, 헤더 드래그로 순서 변경.

Column Visibility & Auto-size

column.hide로 초기 숨김을 지정하고, setColumnVisible(colId, visible)로 런타임에 토글합니다. getColumns()는 정규화된 컬럼 목록을 반환하고 (아래 체크박스가 이 목록으로 만들어집니다), autoSizeColumn(colId)은 내용 폭에 맞춰 컬럼 폭을 조정합니다 (헤더 경계 더블클릭과 동일).

Row Numbers · Max Width · Grid-level Editable

rowNumbers: true는 왼쪽에 고정된 행 번호 컬럼을 추가합니다(정렬·필터·복사 제외). column.maxWidth는 드래그 리사이즈·flex·자동 맞춤의 상한이 됩니다. 그리드 레벨 editable: false / setEditable(bool)은 컬럼 설정을 무시하고 편집 전체를 잠급니다.

Column Data Type & Declarative Format

dataType: 'number' | 'date' | 'bool'은 정렬 비교· filter: true의 필터 종류·기본 정렬 방향(숫자는 오른쪽)을 자동 결정합니다. format: '$#,##0.00' / 'yyyy-MM-dd' 선언적 포맷은 valueFormatter를 대신하며, 같은 패턴을 DataGrid.format(value, pattern) 유틸로도 쓸 수 있습니다.

Column Group Headers

columnGroups: [{ headerName, children: ['field'...] }]는 헤더 위에 그룹 스팬 행을 추가합니다. 같은 그룹의 연속된 컬럼이 하나의 스팬으로 묶이고, 컬럼을 드래그해 그룹 밖으로 옮기면 스팬이 자동으로 갈라집니다. 고정(pinned) 컬럼 경계에서는 스팬이 끊겨 스크롤과 어긋나지 않습니다.

Nested Column Group Headers (3단 헤더)

columnGroups의 children에 컬럼 이름 대신 그룹 객체를 다시 넣으면 그룹 줄이 한 줄 더 생겨 3단 헤더가 됩니다. 자식 그룹이 없는 구간은 상위 그룹이 두 줄을 차지해 라벨이 가운데에 놓입니다 — 그래서 깊이가 섞여 있어도 표가 들쭉날쭉해 보이지 않습니다. 줄 수는 설정이 아니라 지금 보이는 컬럼에 실제로 걸린 깊이로 정해지므로, 하위 그룹 컬럼을 전부 숨기면 그 줄이 저절로 사라집니다.

Custom Header (headerRenderer / headerClass / headerTooltip)

column.headerRenderer(params)는 헤더 라벨을 커스텀 콘텐츠(HTML 문자열 또는 Element)로 교체합니다 — cellRenderer의 헤더판. 정렬·필터 메뉴·리사이즈·리오더는 그대로 동작하고, 커스텀 헤더 안의 버튼·입력 등 인터랙티브 요소 클릭은 정렬을 발동하지 않습니다. headerClass·headerTooltip으로 클래스와 툴팁도 지정할 수 있습니다.

Computed Columns & Row Styling

column.valueGetter(row)는 파생 값을 계산해 행에 기록합니다 — 정렬·필터·CSV/JSON 내보내기 모두 같은 값을 봅니다. getRowClass(row, index)는 행별 CSS 클래스를, column.suppressMove는 특정 컬럼의 드래그 이동을 막습니다.

Merge Cells (연속 값 세로 병합)

mergeCells: ['field'...]는 표시 순서상 연속된 같은 값을 세로로 병합해 보여줍니다 — 병합 구간이 하나의 셀이 되어 값이 세로 중앙에 표시됩니다. 해당 컬럼으로 정렬하면 병합 효과가 커지고, 그룹 헤더·디테일 행에서는 병합이 끊깁니다. 데이터 자체는 그대로라 CSV/클립보드에는 영향이 없습니다.

편집 Editing

인라인 셀 편집 — 에디터 종류, 검증, 편집 가능 범위 제어.

Cell Editing

editable: true 셀을 더블클릭(또는 Enter)하면 편집 시작 — text / number / select 에디터, Enter 커밋, Esc 취소, cellValueChanged 이벤트 발행.

Edit Validation & Programmatic Control

column.validator(value, row)가 true가 아닌 값(오류 메시지 문자열)을 반환하면 커밋이 거부되고 편집기가 빨간 테두리로 유지됩니다(Esc로 취소). beforeCellSave 이벤트에서 e.cancel = true로 저장을 막을 수 있고, startEdit(row, field) / stopEdit(commit) / isEditing()으로 편집을 코드로 제어합니다. 편집 수명주기는 editingStarted / editingStopped로 관찰합니다.

Continuous Editing & Custom Editor

editOnSingleClick(클릭 한 번 편집) · enterMovesDown(Enter로 아래 셀 연속 편집) · tabMovesRight(Tab/Shift+Tab으로 좌우 이동, 행 끝에서 줄바꿈) 옵션과, editor: { init(cell, value, row, col), getValue(), destroy() } 커스텀 에디터 객체입니다. Rating 컬럼은 슬라이더 에디터를 씁니다.

Editable Column Indicator (editableIndicator)

editableIndicator: true를 주면 편집 가능한 컬럼 헤더에 연필 아이콘이 붙습니다 — 어떤 컬럼을 더블클릭할 수 있는지 한눈에 보입니다. 표시 기준은 지금 실제로 편집할 수 있는가라서, setEditable(false)로 그리드를 잠그면 아이콘도 함께 사라집니다(거짓 표시 방지). 아래 버튼으로 확인해 보세요.

Required Columns (column.required)

column.required: true는 표시와 검증을 한 번에 켭니다 — 비어 있는 셀에만 오른쪽 위 모서리 마커가 나타나며, 빈 값 커밋은 인라인 편집 · 팝업 폼 · 붙여넣기 · updateRows 어느 경로로도 거부됩니다. 그리드 표시는 셀 마커 하나이고 헤더에는 표식을 두지 않습니다 — 필수 컬럼의 모든 셀에 그리면 다 같은 표시라 정보량이 0이기 때문입니다. (* 표식은 팝업 폼 라벨에만 붙습니다 — 아래 "첫 행 폼 편집"으로 확인하세요.) trackChanges의 수정됨 마커(왼쪽 위 주황)와 자리·색이 겹치지 않게 오른쪽 위 빨강을 씁니다 — 한 셀에 둘이 동시에 뜰 수 있습니다. 0과 false는 유효한 값으로 취급합니다. 단 number·date 에디터는 빈 입력이 기존 정규화 규칙에 따라 이전 값으로 되돌아가므로 애초에 빈 값이 커밋되지 않습니다 — 인라인에서 required 오류를 보려면 텍스트 계열 컬럼(아래 Department)을 쓰세요.

Row / Cell Locking (setRowEnabled · setCellEnabled)

setRowEnabled(row, false)는 행을, setCellEnabled(row, field, false)는 셀을 잠급니다. 행 잠금은 편집(인라인·붙여넣기·채우기·팝업 폼)과 선택까지 막고 흐리게 표시하며, 셀 잠금은 편집 계열만 막습니다. 잠금 상태는 그리드가 들고 있으므로 호출 한 번이면 다시 그리기까지 끝나고, setRowData()로 데이터를 갈아끼우면 함께 초기화됩니다. 조회는 isRowEnabled(row) / isCellEnabled(row, field), 일괄 해제는 resetEnabled()입니다.

Date / DateTime Editor (editor: 'date' | 'datetime')

editor: 'date' / editor: 'datetime'은 브라우저 기본 날짜 피커 (<input type="date"> / datetime-local)로 편집합니다. dataType: 'date'만 줘도 date 에디터가 자동 선택됩니다. 커밋 값은 원본 타입을 보존합니다 — 문자열이었으면 문자열(컬럼 format 표기), Date였으면 Date, 타임스탬프 숫자였으면 숫자. editorOptions: { min, max }로 선택 범위를 제한하고, 입력을 비우면 null로 지워집니다. 아래 상태 줄에서 커밋된 값의 타입을 확인해 보세요.

Select Editor — label/value Options

editorOptions는 문자열 배열 외에 { label: '한국', value: 'kr' } 객체 배열도 받습니다 — 드롭다운에는 label이 표시되고, 선택하면 value가 데이터에 저장되어 셀에 표시됩니다 (숫자 value는 타입이 보존됩니다). editor를 선언한 컬럼은 editable: true를 생략해도 편집이 켜집니다 (명시적 editable: false가 우선).

Searchable Select Editor (editorSearch)

editor: 'select'에 editorSearch를 주면 네이티브 셀렉트 대신 검색 입력이 있는 옵션 패널로 바뀝니다. editorSearch: true는 정적 editorOptions를 로컬에서 필터하고, editorSearch: { fetch(query) }는 질의마다 비동기로 목록을 불러옵니다 (lazy 검색 — debounce·minLength· placeholder 옵션). 짝꿍 렌더러 DataGrid.renderers.searchselect()는 lazy 검색으로 고른(정적 목록에 없는) 값도 선택 당시의 label로 표시합니다. 툴바 체크박스로 editOnSingleClick을 켜서 클릭 한 번 편집과 함께 테스트해 보세요.

Multiselect · Radio · Checkbox Editors & Renderers

editor에 'multiselect'(체크리스트 패널, 값은 배열)· 'radio'(단일 선택 라디오 패널)·'checkbox'(체크박스)를 지정할 수 있고, 각각 짝꿍 렌더러 DataGrid.renderers.multiselect()(label 칩 목록)· renderers.radio()(value → label)·renderers.checkbox()(표시 전용 체크박스)가 있습니다. multiselect는 editorOptions 순서대로 배열을 커밋하며 내용이 같으면 커밋하지 않습니다. checkbox는 불리언 외에 editorOptions: { checked: 'Y', unchecked: 'N' } 매핑으로 Y/N·0/1 같은 표기도 그대로 저장·표시합니다.

Searchable Multiselect Editor (multiselect + editorSearch)

editor: 'multiselect'에도 editorSearch를 줄 수 있습니다 (v2.25). 스키마는 검색형 select와 동일합니다 — true면 정적 editorOptions를 로컬 필터하고, { fetch(query) }면 질의마다 비동기로 목록을 불러옵니다. 고른 값은 칩으로 검색창 위에 상시 표시되므로, 필터로 목록에서 가려지거나 lazy 질의로 목록이 통째로 갈려도 지금 무엇이 골라져 있는지 사라지지 않습니다. 칩의 × 또는 항목 재클릭으로 해제합니다. Enter는 목록이 보일 때만 활성 항목(↑/↓로 고른 것)을 토글하고, 목록이 접혀 있으면 셀에서는 커밋 · 폼에서는 저장으로 넘어갑니다 — 마우스로 고른 직후의 Enter가 방금 고른 항목을 되돌리지 않습니다 (BUG-014). 저장 순서는 고른 순서이며, 원본이 배열이면 배열로 · 콤마 문자열이면 콤마 문자열로 되돌려 커밋합니다.

팝업 폼(popupEditor)에서는 접히는 콤보박스가 됩니다 — 평소엔 칩 줄과 검색창만 보이고 클릭·타이핑할 때만 목록이 떠서 다른 필드를 덮습니다. 검색이 없는 일반 multiselect가 폼에서 항상 펼쳐지는 이유는 "고른 값을 보여줄 자리가 없어서"인데, 칩 줄이 그 자리를 대신하므로 접어도 정보가 사라지지 않습니다.

Fill Handle (엑셀식 채우기)

fillHandle: true(cellSelection 필요)는 선택 범위 우하단에 채우기 핸들을 표시합니다. 핸들을 세로로 드래그하면 숫자 2개 이상은 등차 수열로 외삽하고(1, 3 → 5, 7, 9…), 그 외에는 패턴을 반복합니다. 편집 가능한 셀에만 쓰이고 validator· beforeCellSave를 통과한 값만 반영됩니다.

폼 편집 Popup Editor

행 단위 폼 편집. 인라인 에디터와 컬럼 정의를 그대로 재사용합니다.

Popup Editor (popupEditor)

popupEditor는 인라인 셀 편집 대신 행 전체를 폼에서 편집합니다. 폼의 각 필드는 컬럼 정의를 그대로 재사용하므로 editor · editorOptions · validator가 인라인과 똑같이 동작합니다 — 아래 예제는 지원하는 에디터 형식을 전부 한 폼에 담았습니다: text · text+validator · number · date · datetime · select(문자열) · select({ label, value }) · 검색형 select(정적) · 검색형 select(lazy fetch) · multiselect · radio · checkbox(불리언) · checkbox(Y/N 값 매핑) · 커스텀 객체 · 읽기 전용. 검증에 실패하면 라벨이 빨갛게 바뀌며 저장이 막힙니다. 위치는 'center'(기본) · 'left' · 'right'(슬라이드 패널), 배치는 columns: 1 | 2 (폭이 모자라면 자동으로 1열이 되고, 더 좁아지면 라벨이 입력 위로 올라갑니다). 행을 더블클릭하거나 아래 버튼을 눌러 보세요.

Popup Editor — 버튼 · 컬럼 단위 커스터마이즈

폼 하단 버튼은 buttons 배열로 구성합니다 — 문자열 'save'/'cancel'은 내장 버튼이고, 객체를 섞어 배열 순서대로 배치합니다. 컬럼마다 column.popupEditor로 팝업 안에서만 라벨 · 도움말 · 순서 · 읽기 전용 · span을 바꾸거나, 에디터를 통째로 교체하고(셀은 좁으니 select, 폼은 넓으니 검색형), 폼에서만 다른 validator를 걸고, 필드 옆 버튼과 임의 HTML(before/after)을 넣을 수 있습니다. 그리드 셀의 표시·동작은 전혀 바뀌지 않습니다 — 아래 그리드에서 셀을 직접 보세요.

Popup Button onLoad (버튼 초기화 훅)

팝업 버튼의 onLoad는 폼이 완전히 만들어진 직후 한 번 호출됩니다 — onClick과 같은 컨텍스트에 버튼 DOM(ctx.buttonEl)이 더해져, 행 값을 보고 버튼 문구·잠금을 정하거나 해당 필드(ctx.fieldEl)와 값(ctx.setValue)을 초기화할 수 있습니다. 호출 순서는 DOM 순서(필드 버튼 → 푸터 버튼)이고, 모든 필드가 이미 존재하므로 다른 필드도 안전하게 만질 수 있습니다.

데이터 · CRUD Data & CRUD

행 추가·수정·삭제와 변경 추적. 저장 전 스테이징 상태를 다룹니다.

Row Data API (CRUD)

setRowData · addRow · updateRow(row, changes) · removeRows로 행을 프로그래매틱하게 관리합니다. getRowId 옵션은 행 식별 기준을 지정하고, getRowData()는 전체 데이터, getDisplayedRows()/ getDisplayedRowCount()는 필터·정렬이 적용된 표시 뷰 기준입니다.

Insert Position (addRow / addRows index)

addRow(row, index) / addRows(rows, index)의 두 번째 인자로 삽입 위치를 지정합니다 — 0이면 맨 앞, 생략하면 기존처럼 맨 뒤. 범위를 벗어나면 클램프됩니다. index는 원본 배열 기준이라 정렬이 켜져 있으면 표시 순서는 정렬이 결정합니다. rowNumbers로 삽입 위치를 확인해 보세요.

Change Tracking & Undo / Redo

trackChanges: true는 마지막 기준선 이후의 변경을 추적합니다 — 수정 셀은 모서리 마커(dirty), 추가 행은 배경으로 표시되고 getChanges() / commitChanges() / rollbackChanges()로 제어합니다. undoRedo: true는 Ctrl+Z / Ctrl+Y와 undo() / redo()를 활성화합니다.

Built-in CRUD Staging (statusColumn / softDelete)

위 카드의 스테이징 패턴을 옵션 두 개로 처리합니다 — 상태 관리 코드가 전혀 없습니다. statusColumn은 변경 추적 상태(added/updated/deleted)를 태그 컬럼으로 표시하고, softDelete: true는 삭제를 스테이징으로 바꿉니다: 서버 행은 삭제 표시(취소선, 편집 차단, restoreRows()로 복원), 신규 행은 로우 자체 제거. 셀을 더블클릭해 편집하면 자동으로 ‘수정’이 되고, commitChanges()(저장 성공 후 — 삭제 표시 행 물리 제거) / rollbackChanges()(전부 되돌리기)로 마무리합니다.

그룹핑 · 트리 Grouping & Tree

행을 계층으로 묶는 세 가지 방식 — 그룹핑, 트리, 마스터-디테일.

Row Grouping & Aggregation

groupBy: ['department']로 행을 그룹핑하고, 그룹 헤더 행을 클릭(또는 Enter)해 접고 펼칩니다. aggFunc: 'sum' | 'avg' | 'min' | 'max' | 'count'를 컬럼에 지정하면 그룹 헤더와 grandTotal 요약 행에 집계값이 표시됩니다. 다단계 그룹핑(['department', 'city'])도 지원합니다.

Custom aggFunc (집계 함수 직접 작성)

aggFunc에 문자열 대신 (values, ctx) => any 함수를 줄 수 있습니다. values는 그 컬럼의 원본 값 배열, ctx는 { rows, field, colDef, parent }이고 parent는 트리 요약에서만 부모 행입니다(그룹·전체합계에서는 null). 집계는 필터 적용 후의 행으로 매번 다시 계산되므로, 아래 Name 컬럼의 (자손 수)는 필터를 자동으로 따라갑니다. 커스텀 함수의 결과에는 valueFormatter가 적용되지 않습니다 — 함수가 이미 출력을 정했기 때문입니다.

Tree Grid (treeData)

treeData는 계층 데이터를 트리로 표시합니다 — nested(children 배열)와 flat(parentId) 형식을 모두 지원하고, 정렬은 형제끼리, 필터는 매치된 노드의 조상을 유지한 채 동작합니다. expandAllNodes()/collapseAllNodes()/toggleNode()로 프로그램 제어, beforeNodeToggle(취소 가능)/nodeExpanded/nodeCollapsed 이벤트를 제공합니다.

Tree Checkbox — cascade (checkboxSelection)

트리 모드에서는 기존 checkboxSelection 컬럼이 3상태 캐스케이드 체크박스가 됩니다 — 부모를 체크하면 자손 전체가 행 선택되고, 자식 일부만 선택되면 부모가 indeterminate로 표시됩니다 (treeData.cascade: false로 끌 수 있음). 별도 API 없이 선택 API를 그대로 씁니다: getSelectedRows()· selectAll()/deselectAll()·selectionChanged/beforeSelectionChange. headerCheckboxSelection의 헤더 체크박스도 트리 규칙을 따릅니다 — 전체 체크/해제 시 treeData.checkboxDisabled(row) 행은 건드리지 않고, 표시 상태(전체/일부)도 체크 가능한 행만 기준으로 계산합니다. 이 카드는 flat(parentId) 형식 데이터를 사용합니다.

Tree Summary (treeData.summary)

treeData.summary: true는 column.aggFunc가 지정된 컬럼에서 부모 노드 행에 자손 리프들의 집계값을 표시합니다 (표시 전용 — 데이터는 그대로). 필터를 걸면 남은 리프 기준으로 집계가 다시 계산됩니다.

Tree Lazy Loading (treeData.fetchChildren)

treeData.fetchChildren(row)는 노드를 처음 펼칠 때 자식을 비동기로 로드합니다 (Promise 반환, 로딩 중 토글이 스피너로 회전). hasChildren(row)가 로드 전 토글 표시 여부를 결정하고, 빈 배열이 오면 리프로 확정됩니다. 실패 시 dataLoadError가 발생하고 접힌 상태로 남아 재시도할 수 있습니다.

Master-Detail Rows

rowDetail: { renderer(row), height }는 행 아래에 커스텀 디테일 패널을 펼칩니다. 첫 컬럼의 셰브론(자동 추가)이나 expandRow(row) / collapseRow(row) / toggleRowDetail(row)로 제어하고 rowExpanded / rowCollapsed 이벤트가 발생합니다. 디테일 높이는 가상 스크롤 레이아웃에 정확히 반영됩니다. (renderer 반환 HTML은 이스케이프되지 않으므로 신뢰할 수 있는 마크업만 사용하세요.)

원격 데이터 Remote Data

서버에서 조회하는 그리드 — 서버 정렬·필터·페이징과 무한 스크롤.

Remote Data Source (Server-side Sort / Filter / Paging)

dataSource: { url, method, params, parse }는 fetch로 데이터를 불러옵니다. sortMode / filterMode / pageMode: 'server'인 축은 클라이언트 처리를 건너뛰고 현재 상태를 요청 파라미터(page·pageSize·sort·filter·quickFilter)로 보냅니다. reloadData()로 다시 불러옵니다. 이 데모는 데모 서버의 /api/employees(500행)를 사용합니다.

Remote Data Source — 서버 스펙 맞춤 (request / parse / headers)

서버의 파라미터·응답 스펙이 그리드 기본값과 다를 때: dataSource.request(state)로 요청 파라미터를 서버 스펙(예: offset/limit/orderBy)으로 바꾸고, parse(json)으로 envelope 응답을 { rows, total }로 변환하며, headers로 인증 토큰을 보냅니다. 조회 조건은 params 함수 + reloadData()로, 서버 교체는 setDataSource()로. 이 데모는 데모 서버의 /api/employees-v2(다른 스펙의 서버 흉내)를 사용합니다.

Nested Request Params (중첩 파라미터 직렬화)

dataSource.request가 중첩 객체·배열을 반환해도 쿼리스트링으로 올바르게 펼쳐집니다. 쿼리스트링의 중첩 표기는 표준이 없어 서버마다 관례가 다르므로 dataSource.paramsFormat으로 맞춥니다 — 'dot'(기본, Spring·ASP.NET)은 page.selectPage=1, 'bracket'(qs·PHP·Rails)은 page[selectPage]=1. 배열 인덱스는 두 표기 모두 대괄호입니다(sorts[0].field — Spring의 List 바인딩 규약). 둘 다 아니면 paramsSerializer로 직렬화를 통째로 대체하세요. 아래 셀렉트로 바꿔 보면 status line에 데모 서버가 실제로 복원한 구조가 표시됩니다 (이 카드는 데모 서버가 있어야 동작합니다 — 로컬에서는 node demo/server.js 8087).

Deferred First Load (dataSource.autoLoad)

dataSource.autoLoad: false면 그리드가 스스로 첫 조회를 하지 않습니다 (기본값 true). 검색 조건을 받은 뒤에 조회하는 화면, 비싼 쿼리, 탭이 열릴 때까지 미루는 경우에 씁니다. 데이터 소스를 끄는 게 아니라 "자동"만 끄는 것이라 reloadData() · loadMore() 같은 명시적 호출은 그대로 동작하고, 정렬·필터 자동 재조회도 한 번이라도 조회한 뒤부터는 평소처럼 동작합니다. setDataSource()도 새 소스가 autoLoad: false면 교체만 하고 조회하지 않습니다.

Infinite Scroll (infiniteScroll)

infiniteScroll: true | { threshold, pageSize }는 바닥 근처에 닿으면 다음 페이지를 자동으로 조회해 기존 행 뒤에 이어 붙입니다(교체가 아닙니다). dataSource가 필요하며 페이저 UI와는 배타입니다 — 대신 하단 상태 바가 불러오는 중 / N건 불러옴 / 마지막 페이지를 알립니다. 끝 판정은 서버가 준 플래그(last · lastPage · isLast · hasMore · hasNext)가 최우선이고, 없으면 total → 수신 건수 순으로 추론합니다. 이 데모 서버(/api/employees-infinite)는 총건수를 주지 않고 last만 주므로, 마지막 페이지 표시가 순전히 그 플래그에서 나옵니다. 상태 바 왼쪽의 크기 선택으로 한 번에 받을 행 수를 바꿀 수 있습니다 (paginationPageSizeOptions가 선택지, 바꾸면 쌓인 것을 버리고 새 크기로 다시 받습니다). 끄려면 infiniteScroll: { pageSizeSelector: false }.

Remote Data + CRUD Staging (신규 / 수정 / 삭제 상태 컬럼)

서버에서 불러온 데이터를 로컬에서 편집해 두었다가 한 번에 저장하는 실무 패턴입니다. 상태 컬럼(_rowStatus)을 renderers.tag로 표시하고 — 신규는 addRow로 추가된 로컬 행, 수정은 서버 행을 편집(rowValueChanged)하거나 수정 버튼을 누른 행, 삭제는 서버 행에 삭제 표시(getRowClass로 취소선). 신규 행을 삭제하면 서버에 없는 데이터이므로 로우 자체가 제거됩니다(removeRows). 삭제 표시된 행은 beforeCellSave로 편집이 차단됩니다. v2.6부터는 이 패턴이 statusColumn / softDelete 옵션으로 내장되어 아래 Built-in CRUD Staging 카드처럼 소비자 코드 없이 동작합니다 — 이 카드는 옵션 없이 직접 구현할 때의 레시피로 남겨둡니다.

서버사이드 row model (Server-Side Row Model)

groupMode: 'server'는 그룹 계층을 서버가 계산하게 하고, 그리드는 펼친 경로의 블록만 받아온다. 요청에는 groupBy(그룹 축)와 groupKeys(지금 펼친 노드의 상위 값)가 실리고, 키가 다 채워지면 서버가 리프 행을 준다. 블록은 dataSource.blockSize 단위로 잘려 오고 남은 것은 ‘더 보기’ 행으로 이어 받는다. 아래 데모의 서버 데이터셋은 50,000행이지만 그리드가 한 번에 들고 있는 것은 블록 몇 개뿐이다.

클립보드 · 내보내기 Clipboard & Export

엑셀과 값을 주고받는 경로 — 복사/붙여넣기, CSV·Excel·JSON 내보내기.

Clipboard Copy & Paste (TSV)

선택한 행을 Ctrl+C로 엑셀 호환 TSV로 복사하고(선택이 없으면 포커스 셀), 포커스 셀을 시작점으로 Ctrl+V로 붙여넣습니다 — 편집 가능한 셀에만 쓰이고 validator·beforeCellSave를 통과한 값만 반영됩니다. column.suppressCopy로 복사에서 제외할 컬럼을 지정하고, copy() / pasteTsv(text)로 코드에서도 제어합니다.

Cell / Block Selection & Find

cellSelection: true는 셀 클릭·드래그·Shift+클릭/화살표로 블록 범위를 선택합니다 — Ctrl+C는 범위를 그대로 TSV로 복사하고 getCellRange()로 범위를 읽습니다. findNext(text)는 뷰에서 다음 매치를 찾아 포커스하고(끝에서 처음으로 순환), cellContextMenu / headerClicked / cellKeyDown 이벤트로 상호작용을 확장합니다.

CSV Export

필터·정렬이 적용된 현재 뷰 데이터를 그대로 내보냅니다(포매터 적용, RFC 4180 이스케이프).

Excel Export & beforeExport

exportExcel(filename, sheetName)은 의존성 없이 진짜 .xlsx 파일을 만듭니다 (무압축 ZIP + SpreadsheetML — 포매터 없는 숫자는 숫자 셀로 나가 엑셀에서 바로 계산 가능). beforeExport 이벤트로 내보내기를 취소하거나 rows/columns/filename을 가공하고, column.exportFormatter는 화면 표시와 다른 내보내기 전용 포맷을 지정합니다.

Styled Excel Export (스타일·병합 포함)

exportExcel()이 기본으로 "그리드에서 보이는 대로" 내보냅니다 — 헤더 스타일, 다단 그룹 헤더 병합, mergeCells 세로 병합, 컬럼 폭, 틀고정(헤더+고정 컬럼). format이 있는 숫자·날짜는 문자열이 아니라 원시 값 + Excel 서식으로 나가 엑셀에서 바로 계산됩니다. { styled: false }는 이전(v2.28) 플레인 출력. 그룹 행(groupBy 라벨·집계)은 아직 내보내지 않습니다.

Programmatic Navigation & JSON Export

focusCell(rowIndex, field)는 페이지 이동·스크롤을 포함해 셀에 포커스를 주고, ensureRowVisible(row) / ensureColumnVisible(colId)는 행·컬럼이 보이도록 스크롤합니다. getJson()은 필터·정렬이 적용된 현재 뷰를 JSON 문자열로 반환하고, 셀 더블클릭은 cellDoubleClicked 이벤트를 발생시킵니다.

레이아웃 · 성능 Layout & Performance

대량 데이터의 가상화와 그리드가 화면을 차지하는 방식.

Row Virtualization — 100,000 rows

보이는 범위(±6행 버퍼)만 DOM으로 렌더링해 10만 행도 지연 없이 스크롤합니다.

Column Virtualization — 300 columns (virtualX)

virtualX: true는 가로 뷰포트에 보이는 컬럼(+버퍼 2)만 셀을 렌더링하고 나머지는 폭 스페이서로 대체합니다 — 수백 개 컬럼에서도 행 DOM이 가볍게 유지됩니다. 가로 스크롤 시 컬럼 창이 갱신되고, 고정(pinned) 컬럼은 항상 렌더링됩니다.

Pinned Top Rows · Wrap Text · Auto Height

pinnedTopRows는 헤더 아래에 스크롤과 무관한 고정 행(표시 전용)을 두고 setPinnedTopRows(rows)로 갱신합니다. column.wrapText + autoRowHeight: true는 긴 텍스트를 줄바꿈하고 행 높이를 내용에 맞춰 계산하며(가변 높이 가상화), domLayout: 'autoHeight'는 그리드가 내용 높이만큼 늘어나게 합니다.

Auto-Height Grid (domLayout)

domLayout: 'autoHeight'는 컨테이너 높이 대신 내용 높이만큼 그리드가 늘어납니다 — 세로 스크롤/가상화가 없어지므로 소량 데이터 전용입니다.

Fill Parent Height (domLayout: 'fill')

domLayout: 'fill'은 그리드를 부모 컨테이너 높이에 정확히 맞춥니다 — 데이터가 없어도 줄지 않고, 많아도 부모를 넘지 않습니다(넘치는 행은 본문 스크롤). flex: 1로 잡은 영역처럼 높이를 CSS로 계산해 주는 레이아웃에 쓰세요. 기본값 'normal'은 height: 100%라 부모가 flex 항목이면 자동 최소 크기(min-height: auto)에 밀려 행 수만큼 늘어날 수 있습니다. 아래 같은 400px 부모에 두 모드를 나란히 두었습니다 — 행 수를 바꿔 보세요.

Headerless Grid (showHeader)

showHeader: false는 헤더 영역 전체(정렬·필터 UI 포함)를 숨깁니다 — 읽기 전용 리스트나 커스텀 헤더를 직접 만들 때 사용합니다.

상태 · 런타임 제어 State & Runtime

만든 뒤에 바꾸는 것들 — 상태 저장·복원, 옵션 변경, 이벤트, 오버레이.

Grid State Save & Restore

getState()는 컬럼 순서·숨김·폭, 정렬, 필터, 퀵 필터, 그룹핑, 페이지 상태를 JSON 직렬화 가능한 객체로 반환합니다. localStorage 등에 저장했다가 setState(state)로 복원하고, resetState()로 생성 시점 옵션 기준으로 되돌립니다 (resetState({ sort: true })처럼 부분 리셋도 가능).

Partial Refresh · Runtime Options · Title / Toolbar

refreshCell(row, field) / refreshRow(row) / refreshColumn(colId)은 전체 재계산 없이 렌더된 DOM만 다시 그립니다 (대량 데이터에서 실시간 값 갱신용). setOptions({...})는 재생성 없이 옵션을 바꾸며, title 옵션과 toolbar 슬롯 (소비자 DOM 주입)으로 그리드에 상단 UI를 붙입니다.

Utility Options & Events (v2.0)

once(event, fn)(1회 핸들러) · setEnabled(bool)(전체 인터랙션 잠금 오버레이) · column.headerAlign(헤더만 다른 정렬) · showHeader: false(헤더 숨김) · rowValueChanged(행 단위 변경 묶음 — 편집·붙여넣기·채우기 공통) 모음입니다.

Lifecycle & Cancelable Events

gridReady(초기 렌더 후 1회) · dataChanged(행 추가/삭제/교체) · viewRendered(모든 refresh 후) 라이프사이클 이벤트와, e.cancel = true로 동작을 거부하는 beforeSort / beforeSelectionChange / beforeCellSave 취소 가능 이벤트 규약입니다.

Overlays

로딩 스피너 오버레이와 "No rows to show" 빈 상태.

UI Text Localization (localeText)

그리드가 직접 그리는 UI 문자열(필터 메뉴 · 페이지네이션 · 오버레이 · 그룹 요약 등)은 localeText로 통째로 바꿉니다. 내장 로케일 DataGrid.locales.ko / .en을 그대로 쓰거나, 그 위에 원하는 키만 덮어쓸 수 있습니다. setOptions({ localeText })로 런타임 전환도 됩니다. {from} 같은 토큰은 값으로 치환되며, 번역하지 않은 키는 영어 기본값이 그대로 쓰입니다.

License Key & Evaluation Watermark

키 없이 실행하면 전 기능이 동작하는 평가판 — 개발 호스트(localhost)가 아닌 곳에서는 우하단에 워터마크가 표시됩니다. DataGrid.setLicenseKey(key)로 등록하고 DataGrid.getLicenseInfo()로 판정 상태를 진단합니다. 이 데모는 내부 훅으로 호스트를 바꿔가며 워터마크·상태 전환을 보여줍니다.

렌더러 Renderers

셀 값을 태그·체크·진행바 등으로 그리는 내장 렌더러.

Built-in Renderers (tag / check / progress)

DataGrid.renderers.tag(colorMap)은 상태 값을 색상 배지로, renderers.check()는 불리언을 ✓/–로, renderers.progress()는 0–100 값을 진행 바로 표시합니다. 렌더러는 표시만 바꾸며 정렬·필터·내보내기는 원시 값 기준입니다.

Select Renderer (DataGrid.renderers.select)

select 에디터의 짝꿍 렌더러입니다 — 셀에는 코드(value)가 저장돼 있어도 cellRenderer: DataGrid.renderers.select()가 그 컬럼의 editorOptions에서 label을 찾아 표시합니다. 데이터·정렬·필터·내보내기는 저장된 value 기준 그대로이고, 표시만 label로 바뀝니다. 목록에 없는 값은 원래 표시로 폴백하며, 다른 목록을 쓰려면 DataGrid.renderers.select([{ label, value }, …])처럼 직접 넘길 수 있습니다.

검색 결과가 없습니다.