Tree view

미리보기

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

사용법

계층을 탐색하고 리소스를 선택하세요. Tree는 Headless Tree의 명시적 ARIA 계층 속성을 TanStack Virtual과 결합해 보이는 행과 포커스된 행만 렌더링합니다. 포커스와 선택은 분리되어 있으며 확장 버튼은 자식만 보이거나 숨깁니다. 예시는 제어된 선택과 확장, 단일 및 다중 선택, RTL, 비활성 리소스, 빈 상태, 10,100개 노드를 다룹니다.

• 일반 내비게이션 목록에 tree role을 추가하지 마세요. 대신 링크 목록이 있는 nav를 사용하세요.
• 변경 가능하거나 부분적으로 로드된 데이터를 전달하지 마세요. 대신 고유 ID가 있는 이미 로드된 불변 데이터를 전달하세요.
• Tree가 데이터를 가져오거나 저장하리라 기대하지 마세요. 서버 요청, 권한 확인, 비동기 자식 로딩, 데이터 이동, 영속성은 제품이 소유합니다.
• 화살표 키가 비활성 노드를 건너뛰리라 기대하지 마세요. 발견 가능성을 위해 포커스를 받지만 선택하거나 확장할 수는 없습니다.
• 행 높이를 rowHeight와 다르게 하지 마세요. 가상화 계산이 여기에 의존합니다. 긴 이름은 시각적으로 잘리며 전체 접근 가능한 이름과 title을 유지합니다.
• 가상화가 전송 데이터 크기를 줄이리라 기대하지 마세요. 렌더링되는 행 수만 제한합니다.

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

구성

ScrollArea → tree container → virtualized treeitems(level, posinset, setsize, expanded, selected, disabled) → disclosure button + truncated label; product-owned result summary

키보드와 접근성

• Tab은 단일 현재 treeitem에서 트리로 들어갑니다.
• Up과 Down은 보이는 항목을 이동합니다. Home과 End는 첫 번째와 마지막 항목으로 갑니다.
• Right는 그룹을 확장한 뒤 첫 번째 자식으로 이동하며, 리프에서는 아무것도 하지 않습니다. Left는 그룹을 접거나 부모로 이동하며, RTL에서는 Left와 Right가 바뀝니다.
• *는 같은 레벨의 모든 그룹을 확장합니다.
• 문자를 빠르게 입력하면 해당 접두사로 시작하는 보이는 이름으로 이동합니다. 같은 문자를 반복하면 다음 일치 항목으로 이동합니다.
• Enter 또는 Space는 선택합니다. 화살표 키로 포커스를 이동해도 선택은 바뀌지 않습니다.
• 다중 선택에서 Space 또는 클릭은 토글, Shift는 범위 선택, Ctrl/Meta+A는 보이는 선택 가능한 모든 노드를 선택합니다.
• 가상화된 행으로 이동하면 실제 DOM 포커스와 내부 스크롤 위치가 함께 이동합니다.

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

예시 코드

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

// Needs headless-tree and react-virtual:
// npm install @headless-tree/core @headless-tree/react @tanstack/react-virtual
import { Tree, type TreeNode } from '@surflane/ui/tree'

const nodes: TreeNode[] = [
  {
    id: 'projects',
    label: 'Projects',
    children: [
      { id: 'workspace', label: 'Workspace' },
      { id: 'reserved', label: 'Reserved environment', disabled: true },
    ],
  },
]
<Tree
  nodes={nodes}
  label='Resources'
  height={352}
  expandedIds={expanded}
  onExpandedIdsChange={setExpanded}
  selectedIds={selected}
  onSelectedIdsChange={setSelected}
  selectionMode='multiple'
  virtualized
/>

// Keep IDs unique and data immutable. Validate selected IDs in the product.
// Selection does not imply navigation or authorization.
// rowHeight follows the size, 36, 44 or 52px; custom heights must fit their content.

주요 API

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

관련 토큰