Table

미리보기

로컬 미리보기입니다. 실제 계정, 환경, 실행 데이터에는 영향을 주지 않습니다.

사용법

행과 열의 관계를 비교하세요. 네이티브 테이블을 렌더링합니다: Caption, scope=col 또는 scope=row의 HeaderCell, Cell. 라벨이 있는 스크롤 영역인 Container로 감쌉니다. 숫자 열에는 numeric을, 정렬할 수 있는 열에는 SortHeader를 쓰고, 포인터로 훑어보는 콘솔에는 density="compact"를 설정하세요. 정렬, 검색, 선택 상태는 호출하는 화면이 소유하며, useTableSelection이 행 ID로 선택을 기억합니다. 규칙마다 동작하는 시안은 아래 가이드라인에 있습니다. 행이 바뀌어도 열이 움직이지 않게 하려면 layout="fixed"와 Column 너비를, 콘솔처럼 한 줄짜리 행에는 nowrap과 긴 이름용 Truncate를, Container가 좁아질 때 비켜도 되는 열에는 hideBelow를 쓰세요.

• 일반 테이블에 grid role이나 화살표 키 셀 내비게이션을 추가하지 마세요. 대신 네이티브 테이블 의미를 유지하세요.
• 전체 행 클릭에 의존하지 마세요. 대신 셀 안에 링크, 버튼, checkbox를 두세요.
• Row.selected만 믿지 마세요. 시각적일 뿐입니다. 선택 의미를 담는 이름 있는 checkbox와 함께 쓰세요.
• 모든 셀에 단위를 쓰지 마세요. 대신 헤더에 단위를 적고 numeric을 설정하세요.

크기: SizeProvider size="small" 포털까지 포함해 구성 전체의 크기를 바꿉니다. 기본 크기는 Default입니다. 크기 안내 및 비교

구성

Container(ScrollArea) → Root(table, density, layout, stickyHeader) → Caption + Columns(Column)? + Head(Row/HeaderCell or SortHeader) + Body(Row/Cell, Truncate, or Message)

가이드라인

실제 화면에 적용하는 규칙과, 규칙마다 동작하는 시안입니다. 시안은 배포되는 부품을 사용하며 로컬에서만 동작합니다.

키보드와 접근성

Tab은 정렬 버튼, 행 선택 checkbox, 액션을 순서대로 이동합니다. 행은 포커스 대상이 아닙니다. 작은 화면에서는 라벨이 있는 영역이 포커스를 받고 가로로 스크롤됩니다. SortHeader는 정렬 중인 열에만 aria-sort를 설정하고, 버튼은 열에 보이는 이름을 그대로 씁니다.

각 컨트롤에 목적을 설명하는 이름을 지정하세요. 오류 메시지를 해당 컨트롤에 연결하고, 상태를 색만으로 알리지 마세요. 자동 검사는 수동 키보드 및 보조 기술 테스트를 대신하지 않습니다.

예시 코드

공유 컴포넌트는 디자인 토큰에서 스타일을 가져옵니다. 각 예시는 자체 구성과 접근성 속성을 설정합니다. 호출하는 화면이 콜백, ref, 제품 데이터를 정의합니다.

import { Table, Checkbox, useTableSelection } from '@surflane/ui'

const selection = useTableSelection({
  rows: pageRows,
  getId: (row) => row.id,
  canSelect: (row) => row.canManage,
})

<Table.Container label='Service inventory'>
  <Table.Root density='compact'>
    <Table.Caption>Services</Table.Caption>
    <Table.Head>
      <Table.Row>
        <Table.HeaderCell scope='col'>
          <Checkbox.Root
            aria-label='Select services on this page'
            {...selection.pageCheckbox}
          >
            <Checkbox.Indicator />
          </Checkbox.Root>
        </Table.HeaderCell>
        <Table.SortHeader sort='ascending' onSort={toggleNameSort}>
          Name
        </Table.SortHeader>
        <Table.SortHeader numeric onSort={sortByLatency}>
          p95 latency (ms)
        </Table.SortHeader>
      </Table.Row>
    </Table.Head>
    <Table.Body>
      {pageRows.map((row) => (
        <Table.Row key={row.id} selected={selection.isSelected(row.id)}>
          <Table.Cell>
            <Checkbox.Root
              aria-label={`Select ${row.name}`}
              {...selection.rowCheckbox(row)}
            >
              <Checkbox.Indicator />
            </Checkbox.Root>
          </Table.Cell>
          <Table.HeaderCell scope='row'>{row.name}</Table.HeaderCell>
          <Table.Cell numeric>{row.latency.toLocaleString()}</Table.Cell>
        </Table.Row>
      ))}
    </Table.Body>
  </Table.Root>
</Table.Container>

주요 API

표는 공통 래퍼의 주요 props를 나열합니다. 전체 타입은 패키지 타입 선언을 참조하세요.

관련 토큰