Grid는 대량 데이터를 효율적으로 표시하며 정렬, 필터, 페이징, 컬럼 설정 등 다양한 기능을 제공합니다.

운영 화면과 관리 시스템에서 사용할 수 있도록 높은 확장성과 사용자 설정 기능을 제공합니다.

HTML 영역

<div id="gridToolbar"></div>
<div id="gridContainer"></div>
<div id="gridPagination"></div>

클래스 import

import coForward_grid from './Grid.js';

Grid.js 는 기본 export를 사용합니다. 일반 <script> 전역 등록은 코드에서 확인되지 않았습니다.
위치: Grid.js:1909

CSS와 의존성

Grid 스타일은 __grid.scss 에 정의되어 있습니다. 프로젝트의 Sass 빌드에 포함하여 CSS로 컴파일한 후 사용합니다.

다음은 Grid.js 에서 생성되며 __grid.scss 에 스타일이 정의된 주요 CSS 클래스입니다.

필수 브라우저 API로는 HTMLElement , <dialog> , CustomEvent 가 사용됩니다. 위치: Grid.js:52-58 , Grid.js:260-351 , Grid.js:665-666

기본 순서

import coForward_grid from './Grid.js';

const container = document.getElementById('gridContainer');

if (!container) {
                                throw new Error('그리드 컨테이너를 찾을 수 없습니다.');
}

const grid = new coForward_grid();

grid.setHeader(header);
grid.setData(rows);
grid.render(container);

권장 호출 순서는 new coForward_grid() → setHeader(header) → setData(rows) → render(container) 입니다.

컨테이너 연결

setContainer(container) 는 HTMLElement 만 허용합니다. 문자열 선택자나 ID 문자열은 허용하지 않습니다. 잘못된 값이면 콘솔에 오류를 출력합니다.
위치: Grid.js:52-58

grid.setContainer(document.getElementById('gridContainer'));

render(container) 에 컨테이너를 전달하면 내부에서 setContainer(container) 를 호출합니다.
위치: Grid.js:594-597

3-3. 테이블 ID와 클래스

grid.setId('employeeGrid');
grid.setClass('compact-grid');

헤더는 컬럼 객체 배열입니다. setHeader(header) 호출 시 header[].key 를 기준으로 원본 컬럼 순서와 현재 컬럼 순서를 초기화합니다.
위치: Grid.js:211-215

4-1. 기본 스키마

const header = [
                                { key: 'select', caption: '', type: 'check', setting: 'lock' },
                                { key: 'name', caption: '이름', type: 'text', sort: '' },
                                { key: 'department', caption: '부서', type: 'text' },
                                { key: 'hireDate', caption: '입사일', type: 'date', format: 'yyyy-MM-dd' },
                                { key: 'salary', caption: '급여', type: 'number', format: ',' }
];

4-2. 지원되는 type

보안상 외부 데이터 표시 예제에서는 html 타입을 사용하지 않습니다. 외부 데이터는 기본 텍스트 타입 또는 직접 만든 안전한 HTMLElement 를 htmlElement 타입으로 전달합니다.

5-1. 행 데이터 기본 형식

setData(data) 는 행 배열의 배열을 받습니다. 각 행은 셀 객체 배열입니다.
위치: Grid.js:220-239 , Grid.js:874-896

const rows = [
                                [
                                                                { key: 'checked', value: 'EMP-001' },
                                                                { key: 'name', value: '김민수' },
                                                                { key: 'department', value: '개발팀' },
                                                                { key: 'hireDate', value: '2026-07-01' },
                                                                { key: 'salary', value: 4200000 }
                                ],
                                [
                                                                { key: 'checked', value: 'EMP-002' },
                                                                { key: 'name', value: '이서연' },
                                                                { key: 'department', value: '기획팀' },
                                                                { key: 'hireDate', value: '2026-07-03' },
                                                                { key: 'salary', value: 3900000 }
                                ]
];

5-2. 셀 객체 스키마

5-3. idx 의 의미

setData(data) 는 행에 { key: 'idx', value: 번호 } 셀이 없으면 자동으로 추가합니다. 자동 번호는 setData() 호출 시 0부터 다시 부여됩니다.
위치: Grid.js:223-232

idx 는 행의 data-sequence , 행 드래그 순서 갱신, setValue(sequence, key, value) , 변경 셀 추적에 사용됩니다.
위치: Grid.js:807 , Grid.js:1137-1141 , Grid.js:1865-1880 , Grid.js:1902-1905

5-4. 데이터 등록, 추가, 삭제, 초기화

6-1. 페이징 활성화

grid.setPagingRows(10);
grid.setPageNavigationContainer(document.getElementById('gridPagination'));
grid.setPageNavigationCount(5);

renderPageNavigation() 은 pageNavigationContainer 가 없으면 아무것도 하지 않습니다. totalPage < 1 이면 내비게이션을 만들지 않습니다.
위치: Grid.js:109-119

6-2. 페이지 내비게이션 생성 조건

7-1. 체크박스 컬럼 선언

{ key: 'checked', caption: '', type: 'check', setting: 'lock' }

type: 'check' 헤더는 헤더에 전체 선택 체크박스를 만들고, 각 행에는 체크박스를 만듭니다.
위치: Grid.js:709-717 , Grid.js:949-984

행에 checked 셀이 없으면 체크박스 렌더링 중 { key: 'checked', value: false, readOnly: false } 가 추가됩니다.
위치: Grid.js:956-982

7-2. 체크 상태 조회와 설정

7-3. pagingCheck

setPage(page) 호출 시 pagingCheck 가 true 이면 현재 체크 상태를 기준으로 전체 선택 체크박스 상태만 갱신합니다. false 이면 모든 체크를 초기화합니다.
위치: Grid.js:63-71 , Grid.js:1566-1586 , Grid.js:1589-1599

grid.pagingCheck = true;

7-4. checkRowFix

checkRowFix 가 true 이면 행 체크 시 체크된 <tr> 에 position: sticky 와 top 을 적용해 헤더 아래에 고정합니다. 정렬·필터·페이징 후 고정 상태를 자동으로 재적용하는 전용 로직은 확인되지 않았습니다.
위치: Grid.js:204-206 , Grid.js:1535-1554

grid.setCheckRowFix(true);

8-1. 정렬 가능한 컬럼

헤더 객체에 sort 속성을 undefined 가 아닌 값으로 넣으면 헤더 텍스트가 버튼으로 렌더링되고 클릭 정렬이 가능해집니다.

{ key: 'name', caption: '이름', type: 'text', sort: '' }

위치: Grid.js:696-706 , Grid.js:1294-1312

8-2. 초기 정렬 설정

grid.setSort('salary', 'desc');

setSort(key, direction) 은 sortSetting = { key, direction } 을 저장합니다. 실제 적용은 render() 시점에 이루어집니다.
위치: Grid.js:606-611 , Grid.js:1642-1644

정렬 방향은 asc , desc 를 사용합니다. 값이 없으면 asc 가 기본입니다.
위치: Grid.js:1314-1324

8-3. 값 필터

grid.setFilter('department', '개발팀', 'origin', true);
grid.render(container);

target / dataType 은 'current' 또는 'origin' 을 사용합니다. value 는 단일 값 또는 배열을 사용할 수 있습니다. exactly = true 면 완전 일치, false 면 includes() 부분 일치를 사용합니다.
위치: Grid.js:1678-1704

8-4. 범위 필터

grid.setRange('salary', 3000000, 5000000, 'origin');
grid.render(container);

범위 필터는 헤더 타입이 number 또는 date 인 컬럼에만 적용됩니다.
위치: Grid.js:1754-1819

grouping 은 별도 그룹 기준 컬럼을 지정하는 기능이 아니라, 각 행 안의 sub 데이터를 열고 닫는 그룹 컬럼을 추가하는 기능입니다.

grid.setGrouping('close'); // 초기 서브 행 닫힘
grid.setGrouping('open');  // 초기 서브 행 열림

서브 행은 셀 객체의 sub 속성에 행 배열 목록을 넣어 표현합니다.
위치: Grid.js:825-847

[
                                { key: 'name', value: '상위 행' },
                                {
                                                                key: 'children',
                                                                value: '',
                                                                sub: [
                                                                                                [
                                                                                                                                { key: 'name', value: '하위 행 1' },
                                                                                                                                { key: 'department', value: '개발팀' }
                                                                                                ]
                                                                ]
                                }
]

10-1. 컬럼 순서

setHeader(header) 호출 시 columnOrderOriginal 과 columnOrder 는 header[].key 배열로 초기화됩니다.
위치: Grid.js:211-215

grid.updateColumnOrder(['checked', 'department', 'name', 'hireDate', 'salary']);
grid.render();

updateColumnOrder(orderArray) 는 전달된 key 순서대로 this.header 를 재정렬합니다.
위치: Grid.js:570-575

10-2. 숨김 컬럼

hiddenColumns 는 컬럼 key 문자열 배열입니다. 설정 화면의 체크박스 해제 시 해당 key가 추가되고, 체크 시 제거됩니다.
위치: Grid.js:545-553 , Grid.js:751-756 , Grid.js:941-945

grid.hiddenColumns = ['salary'];
grid.render(container);

직접 배열을 수정할 수는 있지만, 설정 화면과 동기화가 필요하므로 초기 상태 지정 정도로만 사용하는 것을 권장합니다.

10-3. 설정 버튼 생성 조건

grid.setSettingButtonContainer(document.getElementById('gridToolbar'));
grid.settingButtonCaption = '컬럼 설정';
grid.settingButtonToolTip = '표시 컬럼과 순서를 설정합니다.';
grid.render(container);

settingButtonContainer 가 있고 그 컨테이너의 innerHTML 이 빈 문자열이면 render() 시 설정 버튼을 자동 생성합니다.
위치: Grid.js:642-644

설정 버튼은 button.title 에 settingButtonToolTip 을 적용합니다.
위치: Grid.js:245-255

10-4. 설정 다이얼로그 동작

설정 버튼 클릭 시 showSettingModal() 이 호출됩니다. 현재 구현은 settingType 값을 분기하지 않습니다.

settingType = 'modal' 은 생성자 기본값으로 존재하지만 실제 코드에서 사용되는 곳은 확인되지 않았습니다. 문서에서는 직접 설정 항목으로 안내하지 않습니다.
위치: Grid.js:38 , 전체 검색 결과 settingType 사용 없음

10-5. 헤더 setting 값

11-1. 안전한 표시 방식

외부 데이터를 표시할 때는 기본 텍스트 타입을 사용합니다.

{ key: 'name', caption: '이름', type: 'text' }

기본 타입은 textContent 로 표시합니다.
위치: Grid.js:1084-1088

DOM 요소가 필요하면 htmlElement 타입에 직접 만든 HTMLElement를 전달합니다.

const button = document.createElement('button');
button.type = 'button';
button.textContent = '보기';

const rows = [
                                [
                                                                { key: 'action', value: button }
                                ]
];

위치: Grid.js:1001-1008

11-2. 주의가 필요한 표시 방식

type: 'html' 은 innerHTML 을 사용합니다. 외부 입력값을 그대로 넣는 예제는 사용하지 않습니다.
위치: Grid.js:992-999

format 함수가 문자열을 반환하면 formatElement() 에서 innerHTML 로 삽입합니다. 외부 데이터 기반 문자열을 반환하지 말고, 가능하면 HTMLElement 를 반환합니다.
위치: Grid.js:1146-1155

11-3. 값 변경과 변경 표시

변경된 셀은 다음 렌더링 시 coForward-grid-updated-cell 클래스가 붙고, 표시 후 updateCells 에서 제거됩니다.
위치: Grid.js:920-927

추가된 행은 addData() 후 다음 렌더링 시 coForward-grid-added-row 클래스가 붙고, 표시 후 addRowIdx 에서 제거됩니다.
위치: Grid.js:791-793 , Grid.js:1474-1498

변경 정보를 별도로 조회하거나 초기화하는 공개 메서드는 확인되지 않았습니다. 개발 담당자 확인 필요.

12-1. 렌더 완료 이벤트

makeTbody() 끝에서 fireRenderEvent() 가 호출됩니다. 렌더 완료 시 다음 이벤트가 발생합니다.

detail 에는 id , columnOrder , hiddenColumns , sortSetting , filterSetting , rangeSetting , 원본/현재 행 수, 현재 페이지, 전체 페이지, 시작/끝 인덱스가 포함됩니다.
위치: Grid.js:648-663

12-2. 체크 이벤트

HTML

<div id="gridContainer"></div>

<script type="module" src="./grid-basic.js"></script>

JavaScript

import coForward_grid from './Grid.js';

const container = document.getElementById('gridContainer');

if (!container) {
                                throw new Error('그리드 컨테이너를 찾을 수 없습니다.');
}

const header = [
                                { key: 'name', caption: '이름', type: 'text' },
                                { key: 'department', caption: '부서', type: 'text' },
                                { key: 'hireDate', caption: '입사일', type: 'date', format: 'yyyy-MM-dd' }
];

const rows = [
                                [
                                                                { key: 'name', value: '김민수' },
                                                                { key: 'department', value: '개발팀' },
                                                                { key: 'hireDate', value: '2026-07-01' }
                                ],
                                [
                                                                { key: 'name', value: '이서연' },
                                                                { key: 'department', value: '기획팀' },
                                                                { key: 'hireDate', value: '2026-07-03' }
                                ]
];

const grid = new coForward_grid();

grid.setHeader(header);
grid.setData(rows);
grid.render(container);

아래 예제는 페이징, 설정 버튼, 체크박스, 정렬, 필터, 값 변경을 포함합니다.

HTML

<div id="gridToolbar"></div>
<div id="gridContainer"></div>
<div id="gridPagination"></div>
<button id="showChecked" type="button">체크 행 확인</button>
<button id="filterDev" type="button">개발팀만 보기</button>
<button id="resetData" type="button">초기화</button>
<button id="updateFirst" type="button">첫 행 이름 변경</button>

<script type="module" src="./grid-page.js"></script>

JavaScript

import coForward_grid from './Grid.js';

const toolbar = document.getElementById('gridToolbar');
const container = document.getElementById('gridContainer');
const pagination = document.getElementById('gridPagination');

if (!toolbar || !container || !pagination) {
                                throw new Error('그리드 적용에 필요한 HTML 요소가 없습니다.');
}

const header = [
                                { key: 'checked', caption: '', type: 'check', setting: 'lock' },
                                { key: 'name', caption: '이름', type: 'text', sort: '' },
                                { key: 'department', caption: '부서', type: 'text' },
                                { key: 'hireDate', caption: '입사일', type: 'date', format: 'yyyy-MM-dd' },
                                { key: 'salary', caption: '급여', type: 'number', format: ',' }
];

const rows = [
                                [
                                                                { key: 'select', value: 'EMP-001' },
                                                                { key: 'name', value: '김민수' },
                                                                { key: 'department', value: '개발팀' },
                                                                { key: 'hireDate', value: '2026-07-01' },
                                                                { key: 'salary', value: 4200000 }
                                ],
                                [
                                                                { key: 'select', value: 'EMP-002' },
                                                                { key: 'name', value: '이서연' },
                                                                { key: 'department', value: '기획팀' },
                                                                { key: 'hireDate', value: '2026-07-03' },
                                                                { key: 'salary', value: 3900000 }
                                ],
                                [
                                                                { key: 'select', value: 'EMP-003' },
                                                                { key: 'name', value: '박지훈' },
                                                                { key: 'department', value: '개발팀' },
                                                                { key: 'hireDate', value: '2026-07-05' },
                                                                { key: 'salary', value: 5100000 }
                                ]
];

const grid = new coForward_grid();

grid.setId('employeeGrid');
grid.setClass('employee-grid');
grid.setHeader(header);
grid.setData(rows);
grid.setPagingRows(2);
grid.setPageNavigationContainer(pagination);
grid.setPageNavigationCount(5);
grid.setSettingButtonContainer(toolbar);
grid.settingButtonCaption = '컬럼 설정';
grid.settingButtonToolTip = '표시 컬럼과 순서를 설정합니다.';
grid.pagingCheck = true;
grid.setCheckRowFix(true);
grid.render(container);

container.addEventListener('checkRow', (event) => {
                                console.log('체크 행:', event.detail);
});

container.addEventListener('render', (event) => {
                                console.log('렌더 완료:', event.detail);
});

document.getElementById('showChecked').addEventListener('click', () => {
                                console.log('체크된 데이터:', grid.getCheckedData());
});

document.getElementById('filterDev').addEventListener('click', () => {
                                grid.filterByOriginalData('department', '개발팀');
                                grid.setPagingRows(2);
                                grid.render();
});

document.getElementById('resetData').addEventListener('click', () => {
                                grid.resetData(true);
});

document.getElementById('updateFirst').addEventListener('click', () => {
                                grid.setValue(0, 'name', '김민수 수정');
                                grid.resetData(true);
});

사용자 설정 메서드

데이터 조회·변경 메서드

정렬·필터 메서드

다음 속성은 코드에서 내부 상태로 사용됩니다. 화면 상태와 데이터 상태가 어긋날 수 있으므로 직접 수정하지 않는 것을 권장합니다.

© team coForward