List
Grid와 InlineEditToolbar를 조합한 데이터 목록 컴포넌트입니다.
개요
List 컴포넌트는 Grid(테이블 렌더링, 페이지네이션, 정렬, 선택)와 InlineEditToolbar(추가/수정/삭제/저장/취소)를 하나로 조합하여, 데이터 목록 조회 + 인라인 편집 워크플로우를 제공합니다.
주요 특징
- ✅ Grid 기반: TableColumn 선언적 열 정의, 페이지네이션, 정렬, 행 선택
- ✅ InlineEditToolbar 통합: 추가/수정/삭제/저장/취소 콜백 연결
- ✅ 읽기 전용:
readOnlyprop으로 편집 버튼 비활성화 - ✅ 무한 스크롤:
infiniteScrollprop으로 pagination 대신 스크롤 로딩 - ✅ 줄무늬/행번호:
striped,showRowNumberprop - ✅ 디자인 토큰: Foundation 토큰 시스템 호환
기본 사용
<List>에 data와 getRowId를 전달하고, <TableColumn>으로 열을 정의합니다.
Preview
공통 —list-* 토큰 오버라이드
List 래퍼와 내부 Grid는 모두 data-token="list"를 사용하며 기존 32개 --list-* 토큰을 공유합니다. 중첩된 Grid는 기본값을 다시 선언하지 않으므로 List에서 재정의한 토큰을 그대로 상속합니다. List와 Grid를 꾸밀 때는 별도의 --grid-*가 아닌 공통 --list-* 네임스페이스를 사용하세요.
List의 style에 CSS 사용자 정의 속성을 전달할 수 있습니다. TypeScript에서는 스타일 객체를 CSSProperties로 지정합니다. 아래 예제에서 체크박스 선택과 상품명 검색·정렬을 조작해 적용 결과를 확인할 수 있습니다.
| 토큰 | 적용 대상 | 예제 값 |
|---|---|---|
--list-head-background | 헤더 배경 | #ede9fe |
--list-cell-foreground | 셀 글자색 | #4c1d95 |
--list-cell-padding-x | 셀 좌우 여백 | 18px |
--list-row-background-selected | 선택 행 배경 | #dcfce7 |
--list-footer-background | 합계 행 배경 | #dbeafe |
Preview
Foundation Table 내부 브리지
내부 Grid는 Foundation Table의 색상·글꼴·셀 여백을 공통 --list-* 토큰에 연결합니다. 이때 사용되는 --table-* 연결은 내부 브리지이므로 List 테마를 변경하기 위해 직접 재정의할 필요가 없습니다. 높이와 모서리 반경 같은 구조적 Foundation Table 토큰은 그대로 유지합니다.
backgroundColor를 전달하면 내부 Grid에서 --list-row-background와 자동 파생된 --list-row-background-hover, --list-row-background-selected 값을 우선 적용합니다. 각 행 상태의 색을 토큰으로 직접 설정하려면 이 prop을 생략하세요.
독립적으로 사용하는 Grid에는 style prop이 없습니다. 같은 토큰을 적용하려면 Grid의 토큰 래퍼 예제를 참고하세요.
행 선택
selectable과 selectionMode로 체크박스(다중) 또는 라디오(단일) 선택을 활성화합니다.
Preview
선택됨: 없음
인라인 편집
inlineEdit를 활성화하면 List 상단에 InlineEditToolbar가 표시됩니다. 추가/수정/삭제/저장/취소 콜백을 연결하여 편집 워크플로우를 구성합니다.
Preview
줄무늬 + 행 번호
Preview
읽기 전용 (readOnly)
readOnly를 활성화하면 InlineEditToolbar의 모든 편집 버튼이 비활성화됩니다.
Preview
서버 사이드 페이징
manualPagination으로 서버 사이드 페이징을 구성합니다. onPageChange 콜백으로 API를 재호출하고 데이터를 갱신합니다.
Preview
ScrollArea 스크롤바 스타일
List는 내부 Grid의 Foundation ScrollArea / ScrollBar를 사용합니다. 기존 height, fullSize, infiniteScroll, onLoadMore API는 그대로이며 별도의 Viewport prop은 필요하지 않습니다.
부모 List의 style에서 토큰을 상속시키면 내부 ScrollArea의 기본값에 가려질 수 있습니다. 아래처럼 예제 범위 안의 [data-token="scroll-area"] 루트에 직접 지정하세요. 세로 너비·가로 높이·thumb 색상이 실제 렌더링된 스크롤바에 적용되며, 기존 --list-* 토큰 예제에는 영향을 주지 않습니다. 같은 선택자 패턴을 Grid, ToolbarGrid, ToolbarList, Comment, Timeline, Tree에도 사용할 수 있습니다.
Preview
무한 스크롤 (라이브)
infiniteScroll을 활성화하면 스크롤 하단에 도달할 때 onLoadMore가 호출됩니다. infiniteScrollDisabled로 추가 로드를 중단할 수 있습니다. 서버에서 받은 행을 누적하는 예제는 기존 manualPagination을 사용해 내부 페이지 크기로 다시 잘리지 않도록 합니다.
Preview
표시 중: 10 / 20
합계 행 (showSummary)
showSummary를 활성화하고 TableColumn에 summary prop을 설정하면 하단에 합계/평균 등의 요약 행이 표시됩니다.
Preview
summary.type:
"sum"|"avg"|"min"|"max"|"count"를 지원합니다.label은 텍스트를 직접 표시합니다.
API Reference
Props
Grid 전달 Props
| Prop | Type | Default | 설명 |
|---|---|---|---|
data | T[] | [] | 데이터 배열 |
getRowId | (row: T) => string | - | 행 고유 ID 추출 함수 (필수) |
children | ReactNode | - | <TableColumn> 자식 컴포넌트들 |
loading | boolean | false | 로딩 상태 |
height | number | string | - | 그리드 높이 |
selectable | boolean | false | 행 선택 활성화 |
selectionMode | "checkbox" | "radio" | "checkbox" | 선택 방식 |
selectedRows | string[] | - | 선택된 행 ID 배열 |
pagination | boolean | true | 페이지네이션 표시 |
pageIndex | number | 0 | 현재 페이지 (0-based) |
pageSize | number | 20 | 페이지당 행 수 |
pageSizeOptions | number[] | [10,20,50,100] | 페이지 크기 선택 목록 |
showRowNumber | boolean | false | 행 번호 열 표시 |
striped | boolean | false | 줄무늬 행 |
fullSize | boolean | false | 화면 가득 채움 |
enableColumnResize | boolean | true | 열 너비 조절 |
backgroundColor | string | - | 배경색 |
List 고유 Props
| Prop | Type | Default | 설명 |
|---|---|---|---|
readOnly | boolean | false | 읽기 전용 |
infiniteScroll | boolean | false | 무한 스크롤 모드 |
infiniteScrollDisabled | boolean | false | 무한 스크롤 추가 로드 비활성화 |
showSummary | boolean | false | 합계 행 표시 |
className | string | - | 컨테이너 CSS 클래스 |
style | React.CSSProperties | - | 컨테이너 인라인 스타일 |
InlineEditToolbar Props
| Prop | Type | Default | 설명 |
|---|---|---|---|
inlineEdit | boolean | false | 편집 도구모음 활성화 |
showAdd | boolean | false | 추가 버튼 |
showEdit | boolean | false | 수정 버튼 |
showDelete | boolean | false | 삭제 버튼 |
showSave | boolean | false | 저장 버튼 |
addMode | boolean | false | 추가 모드 상태 |
editMode | boolean | false | 수정 모드 상태 |
deleteMode | boolean | false | 삭제 모드 상태 |
Events
| Event | Type | 설명 |
|---|---|---|
onRowClick | (row: T, index: number) => void | 행 클릭 |
onRowDoubleClick | (row: T, index: number) => void | 행 더블클릭 |
onSelectionChange | (ids: string[], rows: T[]) => void | 선택 변경 |
onPageChange | (pageIndex: number) => void | 페이지 변경 |
onSortChange | (sorting: SortingState) => void | 정렬 변경 |
onLoadMore | () => void | 무한 스크롤 추가 로드 |
onAdd | () => void | 추가 클릭 |
onEdit | () => void | 수정 클릭 |
onDeleteMode | () => void | 삭제 모드 전환 |
onDelete | () => void | 삭제 실행 |
onSave | () => void | 저장 클릭 |
onCancel | () => void | 취소 클릭 |
접근성
- 테이블은 시맨틱
<table>요소를 사용합니다 - 로딩 상태는
aria-busy="true"로 전달됩니다 - 정렬 방향은
aria-sort속성으로 전달됩니다 - InlineEditToolbar는
role="toolbar"를 사용합니다 - 행 선택 체크박스/라디오는 키보드(Space)로 토글할 수 있습니다
관련 컴포넌트
- Grid - List 내부에서 사용하는 데이터 그리드
- InlineEditToolbar - List 내부에서 사용하는 편집 도구모음
- TableColumn - 열 정의 컴포넌트