Wijmo 블로그 MESCIUS 기술 블로그 ·

Wijmo FlexGrid Vue 3 Composition API 사용법 가이드

Vue 3로 데이터 그리드를 처음 붙이는 개발자라면 "기존 Options API 기반 UI 컴포넌트를 <script setup> 스타일로 어떻게 연결하지?"라는 고민을 하게 됩니다. 이 글에서는 @mescius/wijmo.vue2.all 단일 패키지로 Wijmo FlexGrid를 Vue 3 Composition API 환경에 설치하고, :initialized 이벤트와 ref() 를 조합해 그리드를 간결한 함수형 코드로 제어하는 방법을 단계별로 살펴봅니다.

⭐
Key Points
이 글에서 다루는 핵심 내용
01
npm install @mescius/wijmo.vue2.all 명령 한 줄이면 Vue 3 프로젝트에서 Wijmo 컴포넌트를 모두 사용할 수 있습니다.
02
<script setup> 에서 ref() 로 만든 반응형 데이터를 :items-source 에 연결하면, 데이터가 바뀔 때 FlexGrid가 이를 자동으로 반영합니다.
03
:initialized 이벤트에 function initGrid(sender, args) {} 같은 핸들러를 걸면, 마운트가 끝난 뒤 FlexGrid 인스턴스를 바로 다룰 수 있습니다.
04
Vue 3 템플릿에서는 camelCase( itemsSource )와 lower-case-dash( items-source ) 두 가지 속성 표기를 모두 쓸 수 있습니다.
05
registerGrid(app) 전역 등록과 컴포넌트 단위 등록 중에서 프로젝트 규모에 맞는 방식을 고르면 됩니다.

Vue 3 프로젝트에 Wijmo FlexGrid 설치하고 등록하기

Wijmo의 Vue 패키지명에는 vue2 가 포함되어 있지만, 이는 내부 네이밍 규칙에서 비롯된 것이며 Vue 3와 완전히 호환됩니다. MESCIUS 공식 퀵스타트 가이드도 Vue 3 Composition API 예제를 직접 제공합니다.

npm으로 패키지 설치

단일 패키지로 FlexGrid, FlexChart, 입력 컨트롤 등 100개 이상의 Wijmo 컴포넌트를 모두 설치합니다. 특정 모듈만 필요하다면 @mescius/wijmo.vue2.grid 처럼 개별 설치도 가능합니다.

전역 등록과 컴포넌트 등록 비교

방법 1 — 전역 등록 (main.js): 애플리케이션 전체에서 wj-flex-grid 를 바로 사용할 수 있습니다.

방법 2 — 컴포넌트 레벨 등록: 필요한 SFC에서만 직접 import해 사용합니다. 불필요한 전역 등록 없이 번들 크기를 관리하기 좋습니다.

💡 SUMMARY
npm install @mescius/wijmo.vue2.all 한 줄로 Vue 3 프로젝트에 모든 Wijmo 컴포넌트가 설치되며, registerGrid(app) 또는 개별 import로 등록 방식을 선택할 수 있습니다.

Options API와 Composition API, Wijmo에서 무엇이 다른가

Wijmo 이벤트 핸들러는 일반적으로 (sender, args) 두 매개변수를 받는 함수 형태로 정의합니다. Options API와 Composition API에서 작성 방식이 다음과 같이 달라집니다.

Options API — data() 와 methods 객체에 코드가 분산됩니다:

Composition API ( <script setup> ) — 관련 로직이 한 스코프에 모입니다:

코드 라인 수가 줄어들 뿐 아니라, 데이터 정의·초기화 로직·이벤트 핸들러가 같은 스코프에 모여 가독성이 높아집니다. 대규모 팀에서는 그리드 관련 로직을 Composable로 분리해 재사용하기도 훨씬 쉬워집니다.

💡 SUMMARY
Wijmo(위즈모)는 <script setup> 과 ref() 를 사용하는 Vue 3 Composition API를 공식 지원하며, :initialized 이벤트로 FlexGrid 인스턴스에 직접 접근할 수 있습니다.

예제 1: Vue 3 FlexGrid 만들기 — script setup과 initialized 이벤트

이 예제에서는 <script setup> 으로 반응형 데이터를 구성하고, :initialized 이벤트로 FlexGrid 인스턴스에 접근해 컬럼 너비를 자동 조정하는 방법을 살펴봅니다.

STEP 1: main.js에서 Wijmo 전역 등록하기

전역 등록 방식을 사용하면 모든 SFC에서 wj-flex-grid 를 별도 import 없이 사용할 수 있습니다. CSS import와 라이선스 키 설정도 이 파일에서 처리합니다.

STEP 2: script setup에 반응형 데이터 선언하기

ref() 로 배열을 감싸면 데이터가 변경될 때 FlexGrid가 자동으로 재렌더링됩니다. generateData() 처럼 일반 함수로 초기 데이터를 생성하고 ref() 에 전달하는 패턴이 권장됩니다.

STEP 3: wj-flex-grid 템플릿 작성과 initialized 이벤트 연결

:initialized 이벤트 핸들러 initGrid 는 FlexGrid 인스턴스가 DOM에 마운트된 직후 실행됩니다. 첫 번째 매개변수 sender 가 FlexGrid 인스턴스이며, 여기서 autoSizeColumns() 같은 API를 바로 호출할 수 있습니다.

STEP 4: 완성 — 바로 실행해 보는 코어 API 버전

💡 SUMMARY
CodePen은 번들러가 없어 <script setup> SFC나 @mescius/wijmo.vue2.* 래퍼 컴포넌트를 실행할 수 없습니다. 아래 라이브 데모는 위에서 설명한 것과 동일한 Composition API 원리( ref , onMounted )를 Vue 3 전역 빌드 + Wijmo 코어 API로 재현한 버전입니다. 실제 프로젝트(Vite/webpack 등 번들러 환경)에서는 위에서 설명한 <wj-flex-grid> 방식을 그대로 사용하시면 됩니다.
실행 결과

위 라이브 데모에서 그리드가 로드되면 초록색 상태 메시지가 즉시 표시되어 onMounted 안의 초기화 로직이 정상 실행됐음을 확인할 수 있습니다.

💡 SUMMARY
<script setup> 에서 ref() 로 감싼 배열을 :items-source 에 바인딩하고, :initialized 이벤트 핸들러의 첫 번째 매개변수( sender )로 FlexGrid 인스턴스에 직접 접근합니다.

예제 2: 이벤트 핸들러로 Vue 3 그리드 동적으로 제어하기

Wijmo FlexGrid는 선택·편집·스크롤 등 다양한 이벤트를 제공합니다. 이 예제에서는 selectionChanged 로 선택 행 정보를 추적하고, cellEditEnded 로 편집이 완료된 셀의 변경 내역을 실시간으로 감지합니다.

STEP 1: selectionChanged로 선택된 행 따라가기

selectionChanged 이벤트는 사용자가 다른 셀을 클릭하거나 키보드로 이동할 때마다 발생합니다. sender.collectionView.currentItem 에서 현재 행의 데이터 객체를 가져올 수 있습니다.

STEP 2: cellEditEnded로 셀 편집 완료 감지하기

cellEditEnded 이벤트는 사용자가 셀 편집을 마치고 값을 커밋하거나 취소할 때 발생합니다. e.row 와 e.col 로 편집된 셀 위치를 파악하고, sender.getCellData(e.row, e.col, true) 로 최신 값을 문자열로 가져옵니다.

STEP 3: 완성 — 바로 실행해 보는 코어 API 버전

💡 SUMMARY
위 예제와 마찬가지로, 아래 라이브 데모는 <wj-flex-grid> 대신 코어 API의 grid.selectionChanged.addHandler(...) / grid.cellEditEnded.addHandler(...) 패턴으로 동일한 이벤트 제어를 구현합니다.
실행 결과

위 라이브 데모에서 행을 클릭하면 왼쪽 패널에 선택 행 정보가 표시되고, 셀을 더블클릭해 값을 수정하면 오른쪽 패널에 편집 내역이 실시간으로 기록됩니다.

💡 SUMMARY
Wijmo FlexGrid의 이벤트 핸들러는 Composition API에서 function handler(sender, args) {} 형태로 :selection-changed , :cell-edit-ended 등의 속성에 바인딩하면 컨트롤 상태 변화에 즉시 반응할 수 있습니다.

Vue 3 그리드로 Wijmo를 고려할 만한 이유

엔터프라이즈 개발 환경에서 데이터 그리드 라이브러리 선택은 기술적 결정이자 비즈니스 결정입니다. Wijmo가 국내 SI·엔터프라이즈 환경에서 갖는 주요 차별점을 정리합니다.

항목 Wijmo 주요 경쟁사
외부 의존성 Zero Dependency 다양한 peer deps 요구
Vue 3 설치 단일 패키지 ( wijmo.vue2.all ) 프레임워크별 개별 설치
한국 기술지원 MESCIUS 한국 공식 지원 영어 지원만 제공
컨트롤 수 100개 이상 (그리드·차트·입력 통합) 그리드 특화
번들 크기 Zero Dependency로 작은 번들 peer deps 포함 시 증가

Zero Dependency 설계 덕분에 버전 충돌 문제 없이 안정적인 번들을 구성할 수 있습니다. Wijmo 배포 라이선스 키는 MESCIUS 배포 라이선스 키 발급 포털 에서 발급받으실 수 있습니다.

💡 SUMMARY
MESCIUS Wijmo는 npm install @mescius/wijmo.vue2.all 한 줄로 Vue 3 프로젝트에 설치되며 Composition API와 즉시 호환됩니다.

자주 묻는 질문 (FAQ)

Q01

Vue 3 Composition API에서 Wijmo FlexGrid를 어떻게 제어하나요?

<script setup> 에서 ref() 로 반응형 데이터를 만들어 :items-source 에 연결하고, :initialized="initGrid" 로 FlexGrid 인스턴스에 접근합니다. initGrid(sender, args) 함수의 sender 가 FlexGrid 인스턴스이므로 sender.autoSizeColumns() 처럼 API를 바로 호출할 수 있습니다. 다른 함수에서도 인스턴스가 필요하면 const flex = ref(null) 를 선언한 뒤 initGrid 안에서 flex.value = sender 로 저장해 재사용하세요.
Q02

script setup에서 Wijmo 컴포넌트를 초기화하는 방법은 무엇인가요?

방법은 두 가지입니다. 전역 등록: main.js 에서 registerGrid(app) 을 호출하면 모든 SFC에서 <wj-flex-grid> 를 따로 import하지 않고 쓸 수 있습니다. 컴포넌트 레벨 등록: <script setup> 안에서 import { WjFlexGrid, WjFlexGridColumn } from '@mescius/wijmo.vue2.grid' 로 필요한 컴포넌트만 가져옵니다. 작은 프로젝트에는 전역 등록이 편하고, 모듈별 책임을 분명히 나누고 싶은 대규모 앱에는 컴포넌트 레벨 등록이 잘 맞습니다.
Q03

Vue 3에서 Options API 대신 Composition API로 Wijmo를 사용해야 하는 이유는?

Composition API에서는 데이터, 이벤트 핸들러, 비즈니스 로직이 같은 스코프에 모여 코드 응집도가 높아집니다. <script setup> 구문은 컴파일 타임 최적화가 적용되어 런타임 성능 면에서 Options API보다 유리하고, 그리드 관련 로직을 Composable 함수로 분리해 여러 컴포넌트에서 재사용하기도 쉽습니다.
Q04

Wijmo Vue 패키지 이름이 vue2인데 Vue 3에서도 사용 가능한가요?

네, @mescius/wijmo.vue2.all 패키지는 Vue 2와 Vue 3를 모두 공식 지원합니다. 패키지명의 vue2 는 Wijmo 내부 네이밍 규칙에서 온 것이며, MESCIUS 공식 문서의 Vue 3 퀵스타트 가이드도 이 패키지를 기준으로 작성되어 있습니다. Vue 3로 마이그레이션하는 중이라도 이름에 혼동하지 말고 같은 패키지를 사용하면 됩니다.
Q05

ref()와 initialized 이벤트로 FlexGrid 인스턴스에 접근하는 방법은?

가장 권장되는 방법은 :initialized 이벤트를 활용하는 것입니다. function initGrid(sender, args) { /* sender가 FlexGrid 인스턴스 */ } 형태로 핸들러를 정의하고 :initialized="initGrid" 로 바인딩하세요. 이후 다른 함수에서도 인스턴스를 참조해야 한다면 const flex = ref(null) 를 선언하고 initGrid 안에서 flex.value = sender 로 저장하면 됩니다. 그러면 flex.value.collectionView 처럼 어디서든 접근할 수 있습니다.
Q06

대규모 Vue 3 엔터프라이즈 앱에 적합한 데이터 그리드 라이브러리는?

MESCIUS Wijmo는 Zero Dependency 설계라 번들 크기가 작고 다른 라이브러리와 버전 충돌이 없으며, FlexGrid·FlexChart·InputControls 등 100개 이상의 컨트롤을 단일 패키지로 제공합니다. 특히 국내 SI 환경에서는 MESCIUS의 국내 공식 기술지원을 활용할 수 있어, 장기 유지보수 측면에서도 안정적인 선택입니다.

MESCIUS Wijmo

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

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

Wijmo 무료 체험판 다운로드