Wijmo 블로그 MESCIUS 기술 블로그 ·

React에 Wijmo FlexGrid 적용하기: 설치부터 필터·이벤트 처리까지

React 앱에서 목록이나 대용량 데이터를 표로 보여주려면 정렬, 필터, 편집 기능을 직접 만들어야 해서 코드가 빠르게 불어납니다. Wijmo FlexGrid는 이런 기능을 npm 패키지 하나로 제공하는 React용 데이터 그리드입니다.

이 글에서는 @mescius/wijmo.react.grid 로 React 프로젝트에 FlexGrid를 붙이는 과정을 처음 해보는 개발자 기준으로 두 가지 예제에 걸쳐 단계별로 따라 해봅니다.

⭐
Key Points
이 글에서 다루는 핵심 내용
01
React 프로젝트에서 npm install @mescius/wijmo.react.all 한 줄로 Wijmo 전체 패키지를 설치하는 방법
02
itemsSource 로 데이터를 연결하고 <FlexGridColumn> 으로 컬럼을 선언해 React 데이터 그리드를 만드는 방법
03
<FlexGridFilter /> 한 줄로 모든 컬럼에 Excel 스타일 필터를 붙이는 방법
04
autoGenerateColumns={false} 와 <wjcGrid.FlexGridColumn> 을 조합해 컬럼 타입·형식·너비를 세밀하게 지정하는 방법
05
initialized 이벤트로 그리드 인스턴스를 받아 초기화 후 추가 설정을 적용하는 방법
06
selectionChanged 이벤트 핸들러에서 선택된 행 데이터를 React 상태에 반영하는 방법
07
@mescius/wijmo.cultures/wijmo.culture.ko import 한 줄로 날짜·숫자·필터 UI를 한국어로 바꾸는 방법

React 프로젝트에 Wijmo 설치하고 시작하기

npm으로 패키지 설치

React 프로젝트 루트에서 다음 명령을 실행합니다.

@mescius/wijmo.react.all 은 그룹 패키지로, FlexGrid·FlexChart·입력 컨트롤 등 모든 Wijmo React 래퍼를 한 번에 설치합니다. FlexGrid만 필요하다면 @mescius/wijmo.react.grid 를 개별 설치할 수도 있습니다.

그리드 스타일시트 불러오기

Wijmo 컨트롤의 레이아웃과 테마가 올바르게 렌더링되려면 CSS를 반드시 로드해야 합니다. 앱의 루트 파일( src/index.jsx 또는 src/main.jsx )에 다음 한 줄을 추가합니다.

그리드를 한국어(ko-KR)로 표시하기

Wijmo는 기본적으로 미국 영어 문화권으로 날짜·숫자를 포맷하고 필터 다이얼로그 UI를 영어로 표시합니다. 한국어 환경에 맞추려면 @mescius/wijmo.cultures 패키지의 한국어 culture 파일을 import 합니다. 이 한 줄이면 날짜 형식, 숫자 구분자, 필터 다이얼로그의 "적용"·"취소" 같은 UI 문자열이 모두 한국어로 자동 전환됩니다.

💡 SUMMARY
culture 파일은 import 하는 것만으로 전역 적용됩니다. 별도의 함수 호출은 필요하지 않으며, 이후 생성되는 모든 Wijmo 컨트롤에 한국어 문화권이 반영됩니다.

Wijmo 배포키 발급 및 설정

같은 루트 파일에서 React 앱이 렌더링되기 전에 setLicenseKey 를 호출합니다. 배포키 없이 실행하면 평가판 워터마크가 표시됩니다.

Wijmo(위즈모) 배포키는 구매하신 Wijmo 배포 라이선스를 사용해서, MESCIUS 배포 라이선스 키 발급 포털 페이지에서 도메인별로 발급받습니다.

💡 SUMMARY
@mescius/wijmo.react.all 설치 후 루트 파일에서 CSS 임포트, 한국어 culture 임포트, setLicenseKey 호출을 완료하면 Wijmo React 통합의 기반이 갖춰집니다.

예제 1: React 그리드 기본 구성과 Excel 스타일 필터 추가

FlexGrid에 <FlexGridColumn> 으로 표시할 컬럼을 선언하고, <FlexGridFilter> 컴포넌트를 자식으로 한 줄만 추가하면 모든 컬럼 헤더에 Excel 스타일 필터가 자동으로 붙습니다. 여기에 한국어 culture를 적용하면 필터 다이얼로그의 버튼과 숫자 형식이 모두 한국어/로컬 형식으로 표시됩니다.

STEP 1: import 구문과 함수형 컴포넌트 뼈대 만들기

FlexGrid·FlexGridColumn은 @mescius/wijmo.react.grid 에서, 필터 컴포넌트 FlexGridFilter는 @mescius/wijmo.react.grid.filter 에서 가져옵니다.

STEP 2: 데이터를 정의하고 FlexGridFilter 붙이기

200행 데이터를 생성하고, <FlexGridColumn> 으로 컬럼을 선언한 뒤 <FlexGridFilter /> 를 FlexGrid의 자식으로 추가합니다.

컬럼 헤더의 필터 아이콘을 클릭하면 값 목록·조건 필터 다이얼로그가 열립니다. 한국어 culture가 적용되어 있어 다이얼로그의 버튼과 숫자 형식이 한국어/로컬 형식으로 표시됩니다. 위 라이브 데모에서 직접 필터를 조작해 볼 수 있습니다.

💡 SUMMARY
<FlexGridColumn> 으로 컬럼을 선언하고 <FlexGridFilter /> 를 자식으로 추가하면 별도 코드 없이 모든 컬럼에 Excel 스타일 필터링이 적용되며, 한국어 culture로 필터 UI까지 한글화됩니다.

예제 2: 컬럼을 직접 정의하고 선택 이벤트 처리하기

실무에서는 컬럼 헤더 한글화, 숫자 포맷, 너비 조정, 읽기 전용 지정 등이 필요합니다. autoGenerateColumns={false} 와 <wjcGrid.FlexGridColumn> 을 조합하면 이 모든 것을 JSX에서 선언적으로 제어할 수 있습니다.

STEP 1: import 구문과 컴포넌트 뼈대 만들기

STEP 2: useState로 데이터와 선택 상태 관리하기

STEP 3: JSX로 FlexGrid 렌더링하고 컬럼 선언하기

autoGenerateColumns={false} 이후에 <wjcGrid.FlexGridColumn> 자식 컴포넌트로 각 컬럼을 선언합니다. 순서가 중요합니다: autoGenerateColumns → <FlexGridColumn> 정의 → itemsSource 바인딩.

STEP 4: selectionChanged와 initialized 이벤트 연결하기

💡 SUMMARY
autoGenerateColumns={false} + <wjcGrid.FlexGridColumn> 조합으로 컬럼별 헤더·형식·너비를 선언적으로 정의하고, selectionChanged 와 initialized 이벤트로 React 상태와 그리드 인터랙션을 연결할 수 있습니다.

React에서 FlexGrid를 쓸 때 알아둘 핵심 패턴

Wijmo React 통합에서 자주 사용하는 패턴들을 정리합니다.

이벤트 핸들러 인자 구조

Wijmo 이벤트 핸들러는 일반적으로 (sender, args) 형식을 사용합니다. sender 는 이벤트를 발생시킨 컨트롤 인스턴스이고, args 는 이벤트 인수입니다.

autoGenerateColumns 속성 작성 순서

컬럼을 명시 정의할 때는 반드시 다음 순서를 지킵니다. 순서를 어기면 FlexGrid가 컬럼을 중복 생성합니다.

자주 쓰는 format 문자열 예시

<wjcGrid.FlexGridColumn format="..."> prop에 사용하는 주요 형식 문자열입니다.

값 타입 format 예시 출력 예
숫자 "n0" 1,234
숫자 "c0" ₩1,234
숫자 "p1" 12.3%
날짜 "yyyy-MM-dd" 2026-07-03
날짜 "M월 d일" 7월 3일
💡 SUMMARY
Wijmo React 이벤트는 일반적으로 (sender, args) 시그니처를 사용하고, autoGenerateColumns={false} 설정은 itemsSource 바인딩보다 앞에 선언해야 컬럼이 올바르게 적용됩니다.

자주 묻는 질문 (FAQ)

Q01

React에서 `@mescius/wijmo.react.grid`와 `@mescius/wijmo.react.all` 중 무엇을 설치해야 하나요?

FlexGrid만 쓴다면 @mescius/wijmo.react.grid 만 설치해도 충분합니다. FlexChart나 입력 컨트롤 등 다른 Wijmo 컴포넌트도 함께 쓸 계획이라면 @mescius/wijmo.react.all 을 설치하는 편이 편리합니다. 그룹 패키지이므로 실제 번들 크기는 임포트한 모듈에 따라 결정됩니다.
Q02

React FlexGrid에서 컬럼을 직접 정의했는데 자동 생성 컬럼이 같이 표시되면 어떻게 하나요?

autoGenerateColumns={false} prop이 없거나, itemsSource 를 autoGenerateColumns 선언보다 먼저 바인딩한 경우에 발생합니다. 다음과 같이 autoGenerateColumns={false} 를 FlexGrid props 중 가장 앞에 위치시켜야 합니다.
Q03

React에서 `selectionChanged` 이벤트로 선택된 행의 데이터를 가져오려면 어떻게 하나요?

sender.selectedItems 배열의 첫 번째 요소를 사용합니다. selectedItems 는 현재 선택 범위에 해당하는 데이터 객체 배열입니다.
Q04

FlexGrid 인스턴스에 접근할 때 `initialized` 이벤트와 React의 `useRef` 중 무엇을 쓰면 되나요?

두 방법 모두 FlexGrid 인스턴스에 접근할 수 있습니다. initialized 이벤트는 Wijmo 컨트롤이 DOM에 완전히 추가된 직후 실행되므로 초기 설정에 적합합니다. useRef 방식은 컴포넌트 생애주기 전반에서 인스턴스를 참조할 때 유용합니다. Wijmo 공식 문서에서는 initialized 이벤트를 권장합니다.
Q05

Next.js 프로젝트에서 Wijmo FlexGrid를 쓸 때 주의할 점이 있나요?

Next.js는 서버 사이드 렌더링(SSR)을 기본으로 합니다. Wijmo FlexGrid는 DOM 접근이 필요한 클라이언트 컴포넌트이므로, 파일 최상단에 'use client' 지시어를 반드시 추가해야 합니다.

MESCIUS Wijmo

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

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

Wijmo 무료 체험판 다운로드