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
ID | 상품명 | 가격 |
|---|---|---|
1 | 상품1 | 1,000 |
2 | 상품2 | 2,500 |
그룹 컬럼 (멀티행 헤더)
TableColumn을 중첩하면 그룹 컬럼이 됩니다. 그룹 컬럼은 field 없이 title만 지정합니다.
Preview
⇅ | 주소 | ||
|---|---|---|---|
이름⇅ | 도시 | 우편번호 | 상태 |
홍길동 | 서울 | 06100 | active |
김영희 | 부산 | 48060 | inactive |
이철수 | 대전 | 34100 | active |
셀 표시 유형 (uiType)
uiType으로 셀 표시 유형을 지정합니다. link, icon, range, button 등을 지원합니다.
Preview
링크 | 재고율 |
|---|---|
350/500 |
조건부 서식
conditionalFormatting 규칙 배열에 따라 조건을 충족하는 셀/행에 스타일을 자동 적용합니다.
Preview
ID | 재고 |
|---|---|
1 | 50 |
2 | 200 |
3 | 400 |
커스텀 셀 렌더링
renderCell로 셀 렌더링을 완전히 커스터마이징할 수 있습니다.
Preview
ID | 상태 |
|---|---|
1 | ● 활성 |
2 | ● 비활성 |
열 숨김
hidden으로 열을 시각적으로 숨기거나, enabled={false}로 열을 제거할 수 있습니다.
Preview
ID | 이름 | 상태 |
|---|---|---|
1 | 홍길동 | active |
2 | 김영희 | inactive |
3 | 이철수 | active |
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 | - | 검색 다중 선택 여부 |
editable | boolean | - | 인라인 편집 가능 여부 |
editType | "text" | "select" | "checkbox" | "radio" | "date" | "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 | 인라인 편집 값 변경 시 호출 |
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로 비활성화된 링크/버튼은 클릭 이벤트가 발생하지 않음 - ❌ 조건부 서식으로 색상만으로 의미를 전달하지 않기 (텍스트/아이콘 병행)
관련 컴포넌트
Last updated on