Wijmo 블로그 MESCIUS 기술 블로그 ·

Wijmo FlexGrid itemFormatter로 셀 색상·배지·진행률 바 구현

그리드에 숫자와 문자열만 나열하면 사용자가 핵심 정보를 한눈에 파악하기 어렵습니다. 목표에 못 미친 실적은 빨간색으로 강조하고, 프로젝트 상태는 색상 배지로, 진행률은 셀 안의 막대로 보여 주는 화면을 처음 만들어야 한다면 어디서부터 시작해야 할까요?

Wijmo FlexGrid에서는 itemFormatter 프로퍼티 하나로 데이터 셀은 물론 열 헤더와 행 헤더까지 렌더링 방식을 직접 제어할 수 있습니다. 이 글은 두 가지 예제로 구현 과정을 단계별로 따라가 봅니다.

  • 예제 1 — 판매 실적 그리드: 실적 값에 따라 셀 배경색을 바꾸는 조건부 서식

  • 예제 2 — 프로젝트 현황 그리드: cell.innerHTML 로 상태 배지와 진행률 바를 셀 안에 삽입

⭐
Key Points
이 글에서 다루는 핵심 내용
01
itemFormatter 는 (panel, r, c, cell) 네 개의 파라미터를 받는 함수이며, 그리드가 셀을 그릴 때마다 호출된다
02
panel.cellType 을 wijmo.grid.CellType 열거형과 비교하면 데이터 셀, 열 헤더, 행 헤더를 구분해 처리할 수 있다
03
cell.style 로 배경색과 글꼴을 바꾸고, cell.innerHTML 로 배지나 진행률 바 같은 HTML 요소를 셀 안에 넣을 수 있다
04
FlexGrid는 셀 DOM을 재활용하므로, 수정한 스타일 속성은 빈 문자열로 초기화해야 이전 셀의 스타일이 남지 않는다
05
cell.innerHTML = panel.getCellData(r, c, true) 로 기존 텍스트를 유지한 채 그 뒤에 요소를 덧붙일 수 있다

예제 1: 값에 따라 셀 배경색이 바뀌는 판매 실적 그리드

판매 직원별 실적을 표시하는 그리드에서, 실적(%)에 따라 셀 배경색과 글꼴 색상을 자동으로 다르게 표시합니다.

STEP 1: HTML 컨테이너 준비

FlexGrid는 DOM 요소를 선택자로 받아 그 안에 그리드를 렌더링합니다. 먼저 컨테이너 div 를 준비합니다.

width 와 height 를 반드시 지정해야 합니다. 높이가 없으면 그리드가 보이지 않습니다. FlexGrid는 CSS 선택자( #salesGrid )를 new wijmo.grid.FlexGrid('#salesGrid', {...}) 에 그대로 전달합니다.

💡 SUMMARY
그리드 컨테이너는 id 를 가진 div 이며, 반드시 높이( height )를 지정해야 합니다.

STEP 2: 데이터와 FlexGrid 초기화

데이터는 wijmo.collections.CollectionView 로 감쌉니다. CollectionView는 정렬, 필터링, 그룹핑을 제공하는 Wijmo의 데이터 래퍼입니다.

isReadOnly: true 는 사용자가 셀을 편집하지 못하도록 합니다. columns 배열의 binding 은 데이터 객체의 필드명과 일치해야 합니다.

💡 SUMMARY
wijmo.collections.CollectionView 로 데이터를 감싸고, columns 배열의 binding 을 데이터 필드명과 정확히 일치시킵니다.

STEP 3: itemFormatter 함수의 기본 골격 만들기

itemFormatter 를 그리드 인스턴스에 연결합니다. 먼저 panel.cellType 을 확인해 데이터 셀, 열 헤더, 행 헤더 등 셀 영역을 구분합니다. 조건에 따라 일부 스타일만 적용하는 경우에는 이전 셀의 스타일이 남지 않도록, 변경한 스타일 속성을 초기화하거나 각 조건 분기에서 값을 명시적으로 다시 설정해야 합니다.

FlexGrid는 렌더링 성능을 위해 셀 DOM을 재활용합니다. 이전 행에서 설정한 backgroundColor 가 다른 행으로 번지지 않으려면 매 호출마다 초기화 코드를 먼저 실행해야 합니다.

CellType 열거형 값:

값 숫자 설명
CellType.Cell 1 일반 데이터 셀
CellType.ColumnHeader 2 열 헤더 셀
CellType.RowHeader 3 행 헤더 셀
CellType.TopLeft 4 좌상단 교차점 셀
💡 SUMMARY
itemFormatter 는 항상 ①CellType 분기 → ②스타일 초기화 → ③커스터마이징 순서로 작성합니다.

STEP 4: 실적 값에 따라 셀 색상 바꾸기

STEP 3의 구조 위에 실적 열( sales )에 값 조건에 따른 배경색과 글꼴 스타일을 추가합니다.

panel.rows[r].dataItem 은 해당 행에 바인딩된 원본 JavaScript 객체입니다. item.sales 처럼 필드에 직접 접근해 조건을 검사합니다.

아래 CodePen에서 완성된 예제를 확인하세요.

실행 결과
💡 SUMMARY
col.binding 으로 열을 식별하고 item 필드값으로 조건을 분기해 cell.style 에 색상을 지정합니다.

예제 2: 셀 안에 상태 배지와 진행률 바 넣기

cell.style 이 스타일만 바꿨다면, cell.innerHTML 은 셀 내부 콘텐츠를 완전히 교체합니다. 상태 배지, 진행률 바, 아이콘 등 임의의 HTML 요소를 삽입할 수 있습니다.

STEP 1: 그리드를 담을 HTML 컨테이너 준비

예제 1과 동일하게 FlexGrid를 렌더링할 div 컨테이너를 먼저 준비합니다. 이 예제는 statusGrid 라는 ID를 사용합니다.

이 예제에서 cell.innerHTML 로 HTML 요소를 삽입할 열은 두 개입니다.

열 ( binding ) 삽입할 HTML 요소 목적
status 색상 배지( <div> ) 작업 상태를 시각적으로 구분
progress 진행률 바(중첩 <div> ) 완료 비율을 게이지로 표시
💡 SUMMARY
그리드 컨테이너를 준비하고, 어느 열에 HTML을 삽입할지 미리 설계합니다.

STEP 2: 프로젝트 데이터 정의와 FlexGrid 생성

status 와 progress 필드를 가진 프로젝트 데이터를 CollectionView 로 감싸 그리드에 바인딩합니다.

status 와 progress 열은 기본 텍스트로 렌더링되며, 다음 STEP에서 itemFormatter 로 교체합니다.

💡 SUMMARY
progress (숫자)와 status (문자열) 필드를 가진 데이터를 CollectionView 로 바인딩합니다.

STEP 3: 상태 값을 색상 배지로 표시하기

STATUS_MAP 으로 상태별 색상과 레이블을 정의하고, cell.innerHTML 에 배지 HTML을 할당합니다. 초기화와 CellType 분기를 먼저 작성합니다.

display:inline-flex 를 사용하는 이유: CMS 환경에서는 <span> 의 background-color 인라인 스타일이 PHP sanitizer에 의해 제거될 수 있습니다. <div style="display:inline-flex"> 로 동일한 시각 효과를 안전하게 적용합니다.

💡 SUMMARY
STATUS_MAP 으로 색상·레이블을 관리하고, cell.innerHTML 에 배지 HTML을 할당합니다.

STEP 4: 셀 안에 진행률 바 추가하고 마무리

기존 itemFormatter 에 progress 열 처리 분기를 추가합니다. 외부 컨테이너와 내부 채움 바를 중첩한 HTML 구조를 cell.innerHTML 로 직접 렌더링합니다.

진행률에 따른 막대 색상:

  • pct === 100 → 녹색( #28a745 ) — 완료
  • pct >= 50 → 파란색( #007bff ) — 진행 중
  • pct < 50 → 노란색( #ffc107 ) — 초기 단계

기존 셀 텍스트를 유지하면서 요소를 앞에 추가하고 싶다면 panel.getCellData(r, c, true) 로 포맷된 값을 가져와 조합합니다.

아래 CodePen에서 배지와 진행률 바가 포함된 완성 예제를 확인하세요.

실행 결과
💡 SUMMARY
cell.innerHTML 에 HTML 문자열을 직접 할당해 배지, 진행률 바, 아이콘 등 임의의 UI 요소를 셀 안에 렌더링할 수 있습니다.

참고: itemFormatter와 formatItem 이벤트 중 무엇을 쓸까

FlexGrid는 두 가지 셀 커스터마이징 방법을 제공합니다.

구분 itemFormatter 프로퍼티 formatItem 이벤트
등록 방식 flex.itemFormatter = fn flex.formatItem.addHandler(fn)
핸들러 수 1개만 등록 가능 여러 핸들러 독립 등록 가능
파라미터 (panel, r, c, cell) (flex, e) — e.panel , e.row , e.col , e.cell
적합한 상황 단일 커스터마이징 로직 여러 모듈이 독립적으로 스타일 적용 시

컴포넌트 기반 구조에서 여러 기능이 같은 그리드에 각자의 스타일을 적용해야 할 때는 formatItem.addHandler() 를 사용합니다. 핸들러끼리 서로 덮어쓰지 않습니다.

자주 묻는 질문 (FAQ)

Q01

itemFormatter에서 스타일 초기화가 꼭 필요한가요?

항상 필수인 것은 아닙니다. FlexGrid는 렌더링 성능을 위해 셀 DOM 요소를 재활용하므로, 이전 셀에 적용한 스타일이 다른 셀에 남을 가능성이 있습니다. 다만 모든 조건 분기에서 동일한 CSS 속성을 새 값으로 다시 지정한다면 별도의 초기화 없이도 정상적으로 동작할 수 있습니다. 반대로 특정 조건에서만 일부 스타일을 적용하고, 조건을 만족하지 않을 때 해당 속성을 되돌리지 않는다면 이전 스타일이 남을 수 있습니다. 따라서 itemFormatter 에서 변경한 CSS 속성이 모든 경우에 다시 지정되지 않는다면, 해당 속성을 빈 문자열로 초기화하거나 각 조건 분기에서 명시적으로 기본값을 설정하는 것이 안전합니다.
Q02

itemFormatter와 CellType 열거형은 어떤 관계인가요?

itemFormatter 는 데이터 셀, 열 헤더, 행 헤더 등 그리드의 모든 패널 셀에서 호출됩니다. 그래서 panel.cellType 값을 wijmo.grid.CellType 열거형( Cell = 1 , ColumnHeader = 2 , RowHeader = 3 , TopLeft = 4 )과 비교해 현재 셀이 어느 영역인지 판별한 뒤, 영역마다 알맞은 로직을 적용합니다.
Q03

특정 열의 셀에만 스타일을 적용하려면 어떻게 하나요?

먼저 panel.cellType === wijmo.grid.CellType.Cell 로 데이터 셀인지 확인합니다. 그다음 panel.columns[c].binding 으로 열 이름을 확인하고, panel.rows[r].dataItem 의 필드값으로 조건을 검사해 원하는 열의 셀에만 스타일을 적용합니다.
Q04

cell.innerHTML 사용 시 주의할 점이 있나요?

cell.innerHTML 을 설정하면 FlexGrid가 렌더링한 기본 텍스트가 사라집니다. 원본 텍스트를 유지하려면 panel.getCellData(r, c, true) 로 포맷된 값을 먼저 가져온 뒤 HTML과 조합합니다. 또한 셀 재활용에 대비해 매 호출마다 cell.innerHTML 을 초기화하는 것이 안전합니다.
Q05

FlexGrid 셀 렌더링 성능을 최적화하는 방법은 무엇인가요?

itemFormatter 내부에서 ① 관련 없는 CellType은 즉시 return으로 탈출, ② document.createElement 대신 cell.innerHTML 문자열 할당 사용, ③ panel.rows[r].dataItem을 지역 변수에 캐싱, ④ 서버 요청이나 복잡한 연산 금지 규칙을 준수합니다. 이를 통해 수천 행의 그리드에서도 부드러운 스크롤 성능을 유지할 수 있습니다.

MESCIUS Wijmo

지금 바로 Wijmo 를 무료로 체험해 보세요

30일 무료 체험판으로 모든 기능을 직접 확인하세요.

Wijmo 무료 체험판 다운로드