Skip to Content

List

Grid와 InlineEditToolbar를 조합한 데이터 목록 컴포넌트입니다.


개요

List 컴포넌트는 Grid(테이블 렌더링, 페이지네이션, 정렬, 선택)와 InlineEditToolbar(추가/수정/삭제/저장/취소)를 하나로 조합하여, 데이터 목록 조회 + 인라인 편집 워크플로우를 제공합니다.

주요 특징

  • Grid 기반: TableColumn 선언적 열 정의, 페이지네이션, 정렬, 행 선택
  • InlineEditToolbar 통합: 추가/수정/삭제/저장/취소 콜백 연결
  • 읽기 전용: readOnly prop으로 편집 버튼 비활성화
  • 무한 스크롤: infiniteScroll prop으로 pagination 대신 스크롤 로딩
  • 줄무늬/행번호: striped, showRowNumber prop
  • 디자인 토큰: Foundation 토큰 시스템 호환

기본 사용

<List>datagetRowId를 전달하고, <TableColumn>으로 열을 정의합니다.


공통 —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

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의 토큰 래퍼 예제를 참고하세요.


행 선택

selectableselectionMode로 체크박스(다중) 또는 라디오(단일) 선택을 활성화합니다.

선택됨: 없음


인라인 편집

inlineEdit를 활성화하면 List 상단에 InlineEditToolbar가 표시됩니다. 추가/수정/삭제/저장/취소 콜백을 연결하여 편집 워크플로우를 구성합니다.


줄무늬 + 행 번호


읽기 전용 (readOnly)

readOnly를 활성화하면 InlineEditToolbar의 모든 편집 버튼이 비활성화됩니다.


서버 사이드 페이징

manualPagination으로 서버 사이드 페이징을 구성합니다. onPageChange 콜백으로 API를 재호출하고 데이터를 갱신합니다.


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에도 사용할 수 있습니다.

무한 스크롤 (라이브)

infiniteScroll을 활성화하면 스크롤 하단에 도달할 때 onLoadMore가 호출됩니다. infiniteScrollDisabled로 추가 로드를 중단할 수 있습니다. 서버에서 받은 행을 누적하는 예제는 기존 manualPagination을 사용해 내부 페이지 크기로 다시 잘리지 않도록 합니다.

표시 중: 10 / 20


합계 행 (showSummary)

showSummary를 활성화하고 TableColumn에 summary prop을 설정하면 하단에 합계/평균 등의 요약 행이 표시됩니다.

summary.type: "sum" | "avg" | "min" | "max" | "count" 를 지원합니다. label은 텍스트를 직접 표시합니다.


API Reference

Props

Grid 전달 Props

PropTypeDefault설명
dataT[][]데이터 배열
getRowId(row: T) => string-행 고유 ID 추출 함수 (필수)
childrenReactNode-<TableColumn> 자식 컴포넌트들
loadingbooleanfalse로딩 상태
heightnumber | string-그리드 높이
selectablebooleanfalse행 선택 활성화
selectionMode"checkbox" | "radio""checkbox"선택 방식
selectedRowsstring[]-선택된 행 ID 배열
paginationbooleantrue페이지네이션 표시
pageIndexnumber0현재 페이지 (0-based)
pageSizenumber20페이지당 행 수
pageSizeOptionsnumber[][10,20,50,100]페이지 크기 선택 목록
showRowNumberbooleanfalse행 번호 열 표시
stripedbooleanfalse줄무늬 행
fullSizebooleanfalse화면 가득 채움
enableColumnResizebooleantrue열 너비 조절
backgroundColorstring-배경색

List 고유 Props

PropTypeDefault설명
readOnlybooleanfalse읽기 전용
infiniteScrollbooleanfalse무한 스크롤 모드
infiniteScrollDisabledbooleanfalse무한 스크롤 추가 로드 비활성화
showSummarybooleanfalse합계 행 표시
classNamestring-컨테이너 CSS 클래스
styleReact.CSSProperties-컨테이너 인라인 스타일

InlineEditToolbar Props

PropTypeDefault설명
inlineEditbooleanfalse편집 도구모음 활성화
showAddbooleanfalse추가 버튼
showEditbooleanfalse수정 버튼
showDeletebooleanfalse삭제 버튼
showSavebooleanfalse저장 버튼
addModebooleanfalse추가 모드 상태
editModebooleanfalse수정 모드 상태
deleteModebooleanfalse삭제 모드 상태

Events

EventType설명
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 - 열 정의 컴포넌트
Last updated on