Cascade List

계층의 각 단계를 나란히 펼쳐 두고 마지막 항목을 바로 선택합니다.

용법

지역

지역·국가·도시 열을 한 화면에 펼쳐 두고 목적지를 선택합니다.

DestinationAsia / South Korea / Seoul

<!-- Cascade List / Location -->
<script setup lang="ts">
import { CascadeListColumn, CascadeListItem, CascadeListRoot, CascadeListValue } from '@sectile/vue/cascade-list'
const nodes = [{ id: 'asia', parentID: null }, { id: 'kr', parentID: 'asia' }, { id: 'seoul', parentID: 'kr' }]
</script>
<template>
  <CascadeListRoot :nodes="nodes" default-value="seoul" label="Destination" v-slot="{ columns }">
    <CascadeListValue placeholder="Choose a destination" />
    <div class="cascade-list-columns">
      <CascadeListColumn v-for="(_, depth) in columns" :key="depth" :depth="depth" v-slot="{ items }">
        <CascadeListItem v-for="item in items" :key="item" :value="item">{{ item }}</CascadeListItem>
      </CascadeListColumn>
    </div>
  </CascadeListRoot>
</template>

비활성 항목

비활성 가지를 계층에 유지하면서 활성 항목 사이를 이동합니다.

DestinationAsia / South Korea / Seoul

<!-- Cascade List / Disabled -->
<script setup lang="ts">
import { CascadeListColumn, CascadeListItem, CascadeListRoot, CascadeListValue } from '@sectile/vue/cascade-list'
const nodes = [{ id: 'asia', parentID: null }, { id: 'kr', parentID: 'asia' }, { id: 'seoul', parentID: 'kr' }]
</script>
<template>
  <CascadeListRoot :nodes="nodes" default-value="seoul" label="Destination" v-slot="{ columns }">
    <CascadeListValue placeholder="Choose a destination" />
    <div class="cascade-list-columns">
      <CascadeListColumn v-for="(_, depth) in columns" :key="depth" :depth="depth" v-slot="{ items }">
        <CascadeListItem v-for="item in items" :key="item" :value="item">{{ item }}</CascadeListItem>
      </CascadeListColumn>
    </div>
  </CascadeListRoot>
</template>

외부 상태 관리

계층 탐색은 그대로 제공하면서 선택한 목적지는 부모가 관리합니다.

DestinationEurope / France / Paris

<!-- Cascade List / Controlled -->
<script setup lang="ts">
import { CascadeListColumn, CascadeListItem, CascadeListRoot, CascadeListValue } from '@sectile/vue/cascade-list'
const nodes = [{ id: 'asia', parentID: null }, { id: 'kr', parentID: 'asia' }, { id: 'seoul', parentID: 'kr' }]
</script>
<template>
  <CascadeListRoot :nodes="nodes" default-value="seoul" label="Destination" v-slot="{ columns }">
    <CascadeListValue placeholder="Choose a destination" />
    <div class="cascade-list-columns">
      <CascadeListColumn v-for="(_, depth) in columns" :key="depth" :depth="depth" v-slot="{ items }">
        <CascadeListItem v-for="item in items" :key="item" :value="item">{{ item }}</CascadeListItem>
      </CascadeListColumn>
    </div>
  </CascadeListRoot>
</template>

어떤 화면에 쓰나

Cascade List는 계층의 각 단계를 나란히 펼쳐 둡니다. 지역 필터, 설정 탐색, 여러 조건을 이어서 고르는 화면처럼 앞에서 고른 값과 다음 선택지를 함께 확인해야 할 때 적합합니다. 같은 계층을 좁은 공간에 넣을 때는 Cascade Select의 실행 요소와 팝업 구성을 사용할 수 있습니다.

구성	화면 배치	선택 흐름
Cascade List	열을 페이지 안에 계속 배치	가지를 고르면 다음 열이 나타나고 마지막 항목을 고르면 값이 확정됨
Cascade Select	실행 요소 아래 팝업에 열을 배치	팝업 안에서 같은 가지 이동과 마지막 항목 선택을 사용

두 컴포넌트는 같은 트리 검증, 현재 항목 이동, 비활성 항목 처리, 값 선택 규칙을 공유합니다. 표현 방식만 화면 목적에 맞게 나뉩니다.

상태 관리

가지 이동은 highlightedValue와 path를 바꾸고, 마지막 항목 선택은 modelValue를 확정합니다. defaultValue로 내부 상태를 시작하거나 v-model로 부모가 값을 관리할 수 있습니다. 열은 페이지 안에 유지되므로 Esc 키는 주변 화면의 기본 동작에 그대로 전달됩니다.

API

Vue 패키지: @sectile/vue/cascade-list

컴포넌트

CascadeListRoot
CascadeListValue
CascadeListColumn
CascadeListItem
CascadeListItemIndicator
CascadeListItemChevron

Props

`CascadeListRootProps`

as: 타입PrimitiveAs기본값'div'
이 파트가 렌더링할 요소 또는 컴포넌트입니다.
asChild: 타입boolean기본값false
하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.
defaultValue: 타입string | null기본값null
컴포넌트가 값을 관리할 때 사용할 초깃값입니다.
disabled: 타입boolean기본값false
사용자 조작을 막을지 여부입니다.
disabledItems: 타입readonly string[]기본값[]
포커스와 선택 대상에서 제외할 항목 값입니다.
form: 타입string기본값undefined
컨트롤을 연결할 네이티브 form 요소의 ID입니다.
label: 타입string기본값undefined
보조 기술이 읽는 컨트롤 이름입니다.
modelValue: 타입string | null기본값undefined
부모가 상태를 관리할 때 사용할 현재 값입니다.
name: 타입string기본값undefined
네이티브 폼 제출에 사용할 이름입니다.
nodes: 타입readonly CascadeListItemDefinition<string>[]기본값필수
계층을 구성할 평면 노드 목록입니다.
policies: 타입CascadeListPolicies<string>기본값undefined
검증, 이동, 선택 동작을 조정하는 정책입니다.
readonly: 타입boolean기본값false
값 확인만 허용하는 읽기 전용 상태 여부입니다.
required: 타입boolean기본값false
제출 전에 올바른 값이 반드시 있어야 하는지 여부입니다.
textValue: 타입(id: string) => string기본값undefined
항목 값을 검색 또는 표시 문자열로 바꾸는 함수입니다.

`CascadeListColumnProps`

as: 타입PrimitiveAs기본값'div'
이 파트가 렌더링할 요소 또는 컴포넌트입니다.
asChild: 타입boolean기본값false
하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.
depth: 타입number기본값필수
단계별 선택에서 이 열의 0부터 시작하는 깊이입니다.
label: 타입string기본값undefined
보조 기술이 읽는 컨트롤 이름입니다.

`CascadeListItemProps`

as: 타입PrimitiveAs기본값'div'
이 파트가 렌더링할 요소 또는 컴포넌트입니다.
asChild: 타입boolean기본값false
하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.
disabled: 타입boolean기본값false
사용자 조작을 막을지 여부입니다.
value: 타입string기본값필수
이 계약이 노출하는 현재 값입니다.

`CascadeListPartProps`

as: 타입PrimitiveAs기본값파트별로 다름
이 파트가 렌더링할 요소 또는 컴포넌트입니다.
asChild: 타입boolean기본값false
하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.

슬롯

`CascadeListRootSlotProps`

columns: 타입readonly (readonly string[])[]
현재 표시 중인 단계별 선택 열입니다.
disabled: 타입boolean
사용자 조작을 막을지 여부입니다.
highlightedValue: 타입string | null
조작 대상으로 강조된 현재 값입니다.
path: 타입readonly string[]
현재 선택 경로입니다.
readonly: 타입boolean
값 확인만 허용하는 읽기 전용 상태 여부입니다.
value: 타입string | null
이 계약이 노출하는 현재 값입니다.
valuePath: 타입readonly string[]
루트부터 마지막 항목까지의 현재 선택값입니다.

`CascadeListColumnSlotProps`

depth: 타입number
현재 계층 항목의 깊이입니다.
items: 타입readonly string[]
현재 계산된 항목 컬렉션입니다.
parentValue: 타입string | null
현재 단계별 선택 열을 소유한 값입니다.

`CascadeListItemSlotProps`

branch: 타입boolean
이 항목이 하위 항목을 소유하는지 여부입니다.
disabled: 타입boolean
사용자 조작을 막을지 여부입니다.
expanded: 타입boolean
하위 항목이 보이는지 여부입니다.
highlighted: 타입boolean
조작 대상으로 강조된 항목인지 여부입니다.
selected: 타입boolean
현재 선택된 항목인지 여부입니다.
value: 타입string
이 계약이 노출하는 현재 값입니다.

이벤트

`CascadeListRoot`

highlight: 페이로드string | null
강조된 항목이 바뀔 때 발생합니다.
update:modelValue: 페이로드string | null
컴포넌트가 외부 제어 값의 변경을 요청할 때 발생합니다.

기타 타입

`CascadeListTextValueResolver`

type CascadeListTextValueResolver = NonNullable<CascadeListRootProps['textValue']>

`CascadeListValueChangeHandler`

type CascadeListValueChangeHandler = (value: string | null) => void

`CascadeListHighlightHandler`

type CascadeListHighlightHandler = (value: string | null) => void

파트

공통 범위: [data-scope="cascade-list"]. 컴포넌트 내부로 스타일을 제한할 때 파트 선택자와 함께 사용합니다.

파트	선택자	역할	추가 속성
`root`	`[data-part="root"]`	컴포넌트 경계와 내부 파트를 묶습니다.	—
`value`	`[data-part="value"]`	현재 확정 값을 표시합니다.	—
`column`	`[data-part="column"]`	계층형 선택 항목의 한 단계를 묶습니다.	—
`item`	`[data-part="item"]`	선택하거나 실행할 수 있는 항목 하나입니다.	—
`item-indicator`	`[data-part="item-indicator"]`	항목의 선택 상태를 표시합니다.	—
`item-chevron`	`[data-part="item-chevron"]`	항목에 하위 단계가 있음을 표시합니다.	—

키보드 동작

키	동작
`Arrow Up` / `Arrow Down`	현재 열에서 선택 가능한 항목 사이를 이동합니다.
`Arrow Left` / `Arrow Right`	부모 열로 돌아가거나 현재 가지의 다음 열로 이동합니다.
`Home` / `End`	현재 열의 선택 가능한 첫 항목 또는 마지막 항목으로 이동합니다.
`Enter` / `Space`	현재 가지를 펼치거나 마지막 항목을 선택합니다.

접근성

화면에 보이는 계층의 각 단계는 이름이 있는 목록 상자이며 항목은 선택·가지·펼침·비활성 상태를 전달합니다.

Cascade List ​

용법 ​

지역 ​

비활성 항목 ​

외부 상태 관리 ​

어떤 화면에 쓰나 ​

상태 관리 ​

API ​

Props ​

CascadeListRootProps ​

CascadeListColumnProps ​

CascadeListItemProps ​

CascadeListPartProps ​

슬롯 ​

CascadeListRootSlotProps ​

CascadeListColumnSlotProps ​

CascadeListItemSlotProps ​

이벤트 ​

CascadeListRoot ​

기타 타입 ​

CascadeListTextValueResolver ​

CascadeListValueChangeHandler ​

CascadeListHighlightHandler ​

파트 ​

키보드 동작 ​

접근성 ​