TableColumn
Grid의 열을 선언적으로 정의하는 컴포넌트
개요
TableColumn은 직접 DOM을 렌더링하지 않는 선언적 열 정의 컴포넌트입니다. <Grid>의 자식으로 사용되며, Grid가 children에서 TableColumn의 props를 수집하여 열을 구성합니다.
주요 특징
- ✅ 선언적 열 정의: JSX로 열을 직관적으로 선언
- ✅ 그룹 컬럼: TableColumn 중첩으로 멀티행 헤더 구성
- ✅ 다양한 셀 유형: uiType으로 text/link/icon/range/button/tag 등 지원
- ✅ 정렬·검색·편집: sortable, searchable, editable 열 수준 설정
- ✅ 포맷터: 통화, 천단위 구분, 템플릿 문자열 서식 지원
- ✅ 조건부 서식: 규칙 기반 셀/행 스타일 자동 적용
기본 사용
field와 title로 열을 정의하고 Grid의 자식으로 배치합니다.
Preview
그룹 컬럼 (멀티행 헤더)
TableColumn을 중첩하면 그룹 컬럼이 됩니다. 그룹 컬럼은 field 없이 title만 지정합니다.
Preview
셀 표시 유형 (uiType)
uiType으로 셀 표시 유형을 지정합니다. link, icon, range, button 등을 지원합니다.
Preview
조건부 서식
conditionalFormatting 규칙 배열에 따라 조건을 충족하는 셀/행에 스타일을 자동 적용합니다.
Preview
커스텀 셀 렌더링
renderCell로 셀 렌더링을 완전히 커스터마이징할 수 있습니다.
Preview
열 숨김
hidden으로 열을 시각적으로 숨기거나, enabled={false}로 열을 제거할 수 있습니다.
Preview
인라인 편집 (editable)
editable와 editType으로 셀을 인라인 편집할 수 있습니다. Grid의 inlineEditMode가 "edit" 또는 "add"일 때 편집기가 표시됩니다.
지원하는 editType: text, select, checkbox, radio, date, datetimepicker, lookup, number, switch
Preview
Tip:
onCellChange콜백으로 편집 값을 수신합니다. List 컴포넌트와 함께 사용하면 InlineEditToolbar의 추가/수정/삭제/저장 워크플로우를 구성할 수 있습니다.
컬럼 검색 (searchable)
searchable을 활성화하면 헤더에 돋보기 아이콘이 표시되고, 클릭 시 Popover로 검색 입력이 나타납니다.
| searchType | 설명 | 실행 시점 |
|---|---|---|
text | 텍스트 입력 | Enter 키 |
select | 드롭다운 선택 | 선택 즉시 (단일) / 버튼 클릭 (다중) |
date | 날짜 범위 선택 | 시작·종료 모두 선택 시 |
popup | 팁업 선택 | Enter 키 |
Preview
서버 사이드 검색:
clientSearch를 사용하지 않고onColumnSearch콜백으로 조건을 받아 API를 재호출하는 패턴을 권장합니다.
컬럼 고정 (fixed)
fixed="left" 또는 fixed="right"로 열을 고정하면 수평 스크롤 시에도 해당 열이 고정됩니다.
Preview
데이터 서식 (formatter)
formatter prop으로 천단위 구분, 통화 기호, 템플릿 문자열 서식을 적용합니다.
Preview
셀 표시 유형 상세 (uiType)
uiType별 상세 예시입니다. link, tag, range(rate/progress), button을 함께 사용할 수 있습니다.
Preview
코드 변환 (translate)
translate prop으로 데이터의 코드 값을 사용자에게 의미 있는 텍스트로 변환합니다.
Preview
셀/헤더 스타일 (cellStyle / headerStyle)
cellStyle, headerStyle로 셀과 헤더 영역의 배경색, 글자색, 정렬, 글꼴 등을 커스터마이즈합니다.
Preview
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
field | string | - | 데이터 바인딩 필드명 (그룹 컬럼은 생략 가능) |
title | string | - | 열 머리글 텍스트 |
children | ReactNode | - | 하위 컬럼 (그룹 컬럼용, TableColumn 중첩) |
width | number | - | 열 너비 (px) |
minWidth | number | - | 열 최소 너비 (px) |
maxWidth | number | - | 열 최대 너비 (px) |
enabled | boolean | - | 표시 여부 (false면 열 제거) |
hidden | boolean | - | 시각적 숨김 (DOM은 존재하나 display:none) |
readOnly | boolean | - | 읽기 전용 (편집/버튼/링크 비활성화) |
fixed | boolean | "left" | "right" | - | 열 고정 방향 |
uiType | "text" | "link" | "icon" | "range" | "button" | "tag" | "preformatted" | "number" | - | 셀 표시 유형 |
linkOption | TableColumnLinkOption | - | 링크 설정 (uiType=“link”) |
icon | TableColumnIconOption | - | 아이콘 설정 (uiType=“icon”) |
rangeOption | TableColumnRangeOption | - | 범위(rate/progress) 설정 (uiType=“range”) |
sortable | boolean | - | 정렬 가능 여부 |
searchable | boolean | - | 검색 가능 여부 (머리글 검색 영역 표시) |
searchType | "text" | "date" | "select" | "popup" | - | 검색 입력 유형 |
searchOptions | { label: string; value: string }[] | - | select/popup 검색 시 선택 항목 |
useMultiSelect | boolean | - | 검색 다중 선택 여부 |
searchFormat | string | - | 검색 날짜 포맷 (date-fns 패턴, searchType=“date” 전용) |
maxRangeDays | number | - | 날짜 검색 최대 조회 가능 기간(일 수) |
editable | boolean | - | 인라인 편집 가능 여부 |
editType | "text" | "select" | "checkbox" | "radio" | "date" | "datetimepicker" | "lookup" | "number" | "switch" | - | 편집 입력 유형 |
editOptions | { label: string; value: string }[] | - | select/radio 편집 시 선택 항목 |
directEdit | boolean | - | 직접 편집 아이콘 표시 여부 |
directEditOnHover | boolean | - | 직접 편집 아이콘을 행 hover 시에만 표시 |
calcFlag | boolean | - | 계산 수식 사용 여부 |
calcFormula | string | - | 수식 문자열 (다른 열 값 참조 동적 계산) |
conditionalFormatting | TableColumnConditionalRule[] | - | 조건부 서식 규칙 배열 |
formatter | TableColumnFormatter | - | 데이터 서식 설정 |
translate | Record<string, string> | - | 코드→텍스트 다국어 매핑 |
cellStyle | TableColumnCellStyle | - | 셀 영역 스타일 |
headerStyle | TableColumnHeaderStyle | - | 머리글 영역 스타일 |
buttonStyle | TableColumnButtonStyle | - | 버튼 영역 스타일 |
summary | TableColumnSummary | - | 합계 행 설정 |
className | string | - | 열 래퍼 CSS 클래스 |
renderCell | (value, row, rowIndex) => ReactNode | - | 커스텀 셀 렌더링 함수 |
renderHeader | () => ReactNode | - | 커스텀 머리글 렌더링 함수 |
Events
| Event | Type | Description |
|---|---|---|
onLinkClick | (row, rowIndex: number) => void | 링크 클릭 시 호출 |
onButtonClick | (row, rowIndex: number) => void | 버튼 클릭 시 호출 |
onDirectEdit | (row, rowIndex: number) => void | 직접 편집 아이콘 클릭 시 호출 |
onCellChange | (row, rowIndex: number, value: unknown) => void | 인라인 편집 값 변경 시 호출 |
onRangeExceeded | (days: number, maxDays: number) => void | 날짜 검색 범위 초과 시 호출 (searchType=“date” + maxRangeDays) |
TableColumnLinkOption
| Field | Type | Required | Description |
|---|---|---|---|
href | string | ((row) => string) | ✅ | 링크 URL |
target | "_self" | "_blank" | - | 링크 열기 대상 |
TableColumnRangeOption
| Field | Type | Required | Description |
|---|---|---|---|
type | "rate" | "progress" | ✅ | 범위 표시 유형 |
max | number | - | 최대값 |
showText | boolean | - | 값 텍스트 표시 여부 |
TableColumnFormatter
| Field | Type | Description |
|---|---|---|
currency | { prefix?: string; suffix?: string; decimalDigits?: number } | 통화 기호/소수점 자릿수 |
thousandSeparator | boolean | 천단위 구분 기호 |
templateString | string | 템플릿 문자열 서식 |
TableColumnConditionalRule
| Field | Type | Required | Description |
|---|---|---|---|
field | string | ✅ | 비교 대상 필드 |
operator | "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "contains" | "notContains" | "startsWith" | "endsWith" | "isEmpty" | "isNotEmpty" | ✅ | 비교 연산자 |
value | unknown | ✅ | 비교 값 |
style | CSSProperties | ✅ | 조건 충족 시 적용할 스타일 |
applyTo | "cell" | "row" | - | 스타일 적용 대상 |
TableColumnSummary
| Field | Type | Description |
|---|---|---|
type | "sum" | "avg" | "count" | "max" | "min" | "custom" | 집계 유형 |
label | string | 합계 행 레이블 |
formatter | (value: number) => string | 집계 값 서식 함수 |
접근성
권장 사항
- ✅ 모든 열에 의미 있는
title을 지정하여 머리글 텍스트를 제공 - ✅
readOnly로 비활성화된 링크/버튼은 클릭 이벤트가 발생하지 않음 - ❌ 조건부 서식으로 색상만으로 의미를 전달하지 않기 (텍스트/아이콘 병행)