ONAANDALL/frontend

Fork 0

Files

T

changwng e98fe69d68 [st frontend] st frontend 분석

2026-05-28 13:59:53 +09:00

8.3 KiB

Raw Permalink Blame History

08. 리얼그리드(RealGrid) 활용

ST 앱에서 사용하는 엔터프라이즈급 그리드 라이브러리인 RealGrid 2의 구현 방식과 주요 함수, 속성을 정리합니다.

1. 개요 및 구조

ST 앱은 realgrid-react를 사용하여 리액트 환경에서 그리드를 구현하고 있으며, 공통 모듈인 DataGrid.tsx에서 복잡한 설정을 추상화하여 제공합니다.

주요 컴포넌트

DataGrid.tsx: 가장 핵심이 되는 공통 그리드 컴포넌트.
TabDataGrid.tsx: 탭별로 독립적인 DataGrid를 렌더링.
SplitDataGrid.tsx: 좌우 5:5 분할 화면에 두 개의 그리드를 배치.
CompactDataGrid.tsx: 간소화된 형태의 그리드.

2. 주요 설정 및 속성 (Props)

DataGridProps 인터페이스를 통해 그리드의 동작을 제어합니다.

속성명	타입	설명
`columnInfo`	`ColumnInfo`	컬럼 정의(`columns`)와 레이아웃(`columnLayout`) 정보
`rowData`	`Record[]`	그리드에 표시할 실제 데이터 배열
`fixedColumns`	`number`	좌측에 고정할 컬럼 수
`rowStartNum`	`number`	엑셀 임포트 시 헤더가 시작되는 행 번호
`isExcelImport`	`boolean`	엑셀 가져오기 버튼 표시 여부
`isExcelExport`	`boolean`	엑셀 내보내기 버튼 표시 여부
`showHeaderCheckbox`	`boolean`	헤더 체크박스(CheckBar) 표시 여부
`cellStyleCallback`	`Function`	실시간 조건부 셀 스타일 적용 콜백
`cellTooltipCallback`	`Function`	셀 호버 시 표시할 툴팁 메시지 콜백
`onRowClick`	`Function`	행 클릭 시 실행될 이벤트 핸들러

3. 컬럼 정의 (`ColumnConfig`)

src/components/type/DataGrid.type.ts에 정의된 주요 컬럼 속성입니다.

export type ColumnConfig = {
    name: string;          // 컬럼 고유 이름
    fieldName: string;     // 데이터 필드명
    header: { text: string }; // 헤더 표시 텍스트
    width?: number;        // 컬럼 너비 (px)
    editable?: boolean;    // 편집 가능 여부
    visible?: boolean;     // 숨김 여부
    styleName?: string;    // 적용할 CSS 클래스
    mergeCells?: boolean;  // 셀 병합 여부 (내용이 같을 때)
    valueType?: ValueType; // 데이터 타입 (TEXT, NUMBER 등)
    footer?: FooterConfig; // 푸터 설정 (합계 등)
    computed?: Computed;   // 계산 필드 설정 (합계/평균/비율 등)
};

4. 핵심 기능 구현 상세

4-1. 커스텀 정렬 (`onSorting`)

기본 정렬 사용 시 "시군구" 등 병합된 셀의 그룹 순서가 깨지는 문제를 해결하기 위해 전용 핸들러를 사용합니다.

createOnSortingHandler: 정렬 시 그룹(시군구) 내의 순서를 유지하며 그룹 간 정렬을 수행합니다.
createNumberComparer: 숫자에 포함된 쉼표(,)를 제거하고 순수 숫자 값으로 비교하여 정확한 정렬을 보장합니다.

4-2. 계산 필드 (`Computed Field`)

dataProvider.setFields 시 valueCallback을 통해 실시간 계산 값을 생성합니다.

지원 유형: 단순 합계(sum), 평균(avg), 보급률(pblswrgPopltnSuprtRate) 등 특수 비즈니스 로직.
매커니즘: getComputedValueCallback 유틸을 통해 여러 필드의 값을 조합하여 결과를 반환합니다.

4-3. 엑셀 임포트/익스포트 (Smart Mapping)

일반적인 그리드와 달리, 엑셀 파일과 그리드 간의 정확한 필드 매칭을 위해 특수한 기법을 사용합니다.

익스포트 시: 엑셀 헤더 텍스트 뒤에 (fieldName)을 임시로 붙여서 내보냅니다. (예: 인구수 (popltnCnt))
임포트 시: 정규표현식 /$([a-zA-Z0-9_]+)$$/을 사용하여 헤더에서 fieldName을 추출, 데이터 파싱 시 정확한 객체 키로 매핑합니다.

4-4. 푸터(Footer) 및 레이아웃 합병

footerUserSpans: columnLayout 설정을 통해 푸터 영역에서 여러 셀을 하나로 합치는 기능을 지원합니다.
멀티 푸터: gridView.setFooters를 통해 2행 이상의 푸터를 설정하고, 각 행마다 다른 통계(합계, 평균 등)를 보여줍니다.

5. 자주 사용하는 유틸리티 함수

`toGridRows<T>`

API 응답 객체 배열을 RealGrid가 처리하기 좋은 형태로 변환합니다.

null 또는 undefined 값을 빈 문자열("")로 치환하여 그리드 상에서 null 문구가 노출되지 않도록 합니다.

6. 스타일 가이드 (`styleName`)

그리드 셀에 적용되는 주요 CSS 클래스입니다 (프로젝트 관례).

rg-cell-readonly: 읽기 전용 셀 배경색 처리
rg-cell-total: 합계 행/열 강조
rg-cell-error: 검증 오류 발생 셀 (빨간색 테두리 등)
rg-cell-required: 필수 입력 셀 표시

7. RealGrid 원천 API 상세 (Native API)

프로젝트 코드(DataGrid.tsx, CompactDataGrid.tsx)에서 실제로 호출하고 있는 RealGrid의 원천 함수와 속성 목록입니다.

7-1. 전역 설정 (`realgrid`)

RealGrid.setLicenseKey(key: string): 라이선스 키를 등록합니다.
ValueType: 필드 데이터 타입을 지정하는 열거형 (예: ValueType.TEXT, ValueType.NUMBER).
GridFitStyle: 그리드 너비 맞춤 스타일 (예: GridFitStyle.EVEN).

7-2. 그리드 뷰 (`GridView`)

그리드의 시각적 요소와 이벤트를 제어합니다.

API	설명
`setOptions(options)`	그리드 전역 옵션 설정 (`checkBar.visible`, `summaryMode` 등)
`setDisplayOptions(options)`	화면 표시 상세 설정 (`fitStyle`, `rowHeight` 등)
`setFixedOptions(options)`	고정 컬럼 설정 (`colCount`)
`setFooters(heights)`	멀티 푸터 행들의 높이를 배열로 설정
`setColumns(columns)`	컬럼 구성을 동적으로 재설정
`setColumnLayout(layout)`	컬럼의 시각적 배치(그룹 헤더 등) 적용
`setColumnProperty(col, prop, val)`	특정 컬럼의 속성(예: `renderer`)을 개별 변경
`exportGrid(options)`	엑셀 파일 내보내기 실행
`setCurrent(index)`	특정 행/셀로 포커스 이동 (`itemIndex` 사용)
`setFocus()`	그리드 자체에 포커스 부여
`refresh()`	그리드 화면 강제 다시 그리기 (스타일 변경 시 유용)
`columnByName(name)`	이름으로 특정 컬럼 객체 반환

주요 이벤트 핸들러:

onSorting: 정렬 시점 발생. (커스텀 그룹 정렬 구현 시 사용)
onCellClicked: 셀 클릭 시 발생. (행 선택 로직 구현)
onShowTooltip: 툴팁 표시 직전 발생. (동적 툴팁 내용 생성)

7-3. 데이터 프로바이더 (`LocalDataProvider`)

그리드 내부의 실제 데이터를 관리합니다.

API	설명
`setFields(fields)`	데이터 필드(데이터 모델) 구조 정의
`setRows(rows)`	전체 데이터 로드
`getRowCount()`	전체 데이터 행 수 반환
`getValue(row, field)`	특정 행/필드의 데이터 값 조회
`setDataComparer(field, fn)`	특정 필드의 정렬 로직을 사용자 정의 함수로 위임

8. RealGrid-React 컴포넌트 (`realgrid-react`)

8-1. `<RealGridReact />` (메인 컨테이너)

ref: 내부 gridView와 dataProvider 객체에 접근하기 위해 사용.
rows: 리액트 상태(rowData)를 그리드 데이터와 바인딩.
layout: 정의된 columnLayout을 적용.
autoGenerateField: true 설정 시 행 데이터를 바탕으로 필드를 자동 생성.
onInitialized(grid): 그리드 초기화 완료 후 실행되는 콜백.

8-2. `<RGDataColumn />` (컬럼 속성 정의)

JSX 형태로 각 컬럼의 세부 속성을 설정합니다.

주요 Props	설명
`name` / `fieldName`	컬럼/필드 식별자
`valueType`	데이터 타입 (`TEXT`, `NUMBER`)
`numberFormat`	숫자 표시 형식 (예: `#,##0.000`)
`header`	헤더 설정 객체 (`{ text: "제목" }`)
`editable`	해당 컬럼의 편집 가능 여부
`styleName`	해당 컬럼에 적용할 CSS 클래스명
`renderer`	셀 렌더러 설정 (예: `{ showTooltip: true }`)
`footer`	푸터 합계/수식 설정
`mergeRule`	셀 병합 규칙 (`{ criteria: "value" }`)
`sortable`	정렬 가능 여부

8.3 KiB Raw Permalink Blame History

08. 리얼그리드(RealGrid) 활용

1. 개요 및 구조

주요 컴포넌트

2. 주요 설정 및 속성 (Props)

3. 컬럼 정의 (ColumnConfig)

4. 핵심 기능 구현 상세

4-1. 커스텀 정렬 (onSorting)

4-2. 계산 필드 (Computed Field)

4-3. 엑셀 임포트/익스포트 (Smart Mapping)

4-4. 푸터(Footer) 및 레이아웃 합병

5. 자주 사용하는 유틸리티 함수

toGridRows<T>

6. 스타일 가이드 (styleName)

7. RealGrid 원천 API 상세 (Native API)

7-1. 전역 설정 (realgrid)

7-2. 그리드 뷰 (GridView)

7-3. 데이터 프로바이더 (LocalDataProvider)

8. RealGrid-React 컴포넌트 (realgrid-react)

8-1. <RealGridReact /> (메인 컨테이너)

8-2. <RGDataColumn /> (컬럼 속성 정의)