TreeSelect 트리 선택기

드롭다운 트리거와 Tree 패널의 조합입니다. 단일 선택은 string을 반환하고, 다중 선택 (체크박스)은 string[]을 반환합니다.

기본 사용법

단일 선택

<script setup>
import { ref } from 'vue'
const treeValue = ref(undefined)
const treeData = [
  { key: 'a', label: '프론트엔드', children: [
    { key: 'a-1', label: 'Vue' },
    { key: 'a-2', label: 'React' },
  ] },
  { key: 'b', label: '백엔드' },
]
</script>

<template>
  <LhTreeSelect :data="treeData" v-model="treeValue" />
</template>

<script>
export default {
  data() {
    return {
      treeValue: undefined,
      treeData: [
        { key: 'a', label: '프론트엔드', children: [
          { key: 'a-1', label: 'Vue' },
          { key: 'a-2', label: 'React' },
        ] },
        { key: 'b', label: '백엔드' },
      ],
    }
  },
}
</script>

<template>
  <LhTreeSelect :data="treeData" v-model="treeValue" />
</template>

다중 선택

다중 선택

<script setup>
import { ref } from 'vue'
const treeMulti = ref([])
</script>

<template>
  <!-- 다중 선택 -->
  <LhTreeSelect :data="treeData" v-model="treeMulti" multiple placeholder="기술 스택을 선택해 주세요" />
</template>

<script>
export default {
  data() {
    return {
      treeMulti: [],
      treeData: [
        { key: 'a', label: '프론트엔드', children: [
          { key: 'a-1', label: 'Vue' },
          { key: 'a-2', label: 'React' },
        ] },
        { key: 'b', label: '백엔드' },
      ],
    }
  },
}
</script>

<template>
  <!-- 다중 선택 -->
  <LhTreeSelect :data="treeData" v-model="treeMulti" multiple placeholder="기술 스택을 선택해 주세요" />
</template>

비활성화와 마운트

disabled는 선택기를 비활성화합니다. teleported를 false로 설정하면 드롭다운 패널이 제자리에 마운트됩니다 (body로 전송하지 않음).

비활성화 / 제자리 패널

<script setup>
import { ref } from 'vue'
const treeDisabled = ref([])
const treeLocal = ref([])
</script>

<template>
  <!-- 비활성화 -->
  <LhTreeSelect :data="treeData" v-model="treeDisabled" disabled />
  <!-- 제자리 패널 -->
  <LhTreeSelect :data="treeData" v-model="treeLocal" :teleported="false" />
</template>

<script>
export default {
  data() {
    return {
      treeDisabled: [],
      treeLocal: [],
      treeData: [
        { key: 'a', label: '프론트엔드', children: [
          { key: 'a-1', label: 'Vue' },
          { key: 'a-2', label: 'React' },
        ] },
        { key: 'b', label: '백엔드' },
      ],
    }
  },
}
</script>

<template>
  <!-- 비활성화 -->
  <LhTreeSelect :data="treeData" v-model="treeDisabled" disabled />
  <!-- 제자리 패널 -->
  <LhTreeSelect :data="treeData" v-model="treeLocal" :teleported="false" />
</template>

API

LhTreeSelect Props

속성명	설명	타입	기본값
data	트리 데이터	[LhTreeNode](#type-LhTreeNode)[]	—
modelValue	현재 값 (단일 선택 string / 다중 선택 string[], 제어형 v-model)	string | string[]	—
multiple	다중 선택 (체크박스 표시, 값은 선택된 키 배열)	boolean	false
disabled	비활성화	boolean	false
placeholder	플레이스홀더 텍스트	string	—
teleported	패널을 body에 마운트할지 여부 (기본값 true)	boolean	true
sx	sx 빠른 레이아웃 속성	LhSxProps	—

Events

이벤트명	설명	콜백 매개변수
update:modelValue	선택값이 변경될 때 트리거되며, v-model과 함께 사용 (단일 선택은 string, 다중 선택은 string[])	(value: string | string[] | undefined)
change	선택이 변경된 후 트리거	(value: string | string[] | undefined)

접근성

• 트리거는 실제 <button>이며, aria-haspopup="tree" + aria-expanded로 전개 상태를 표시합니다. 패널은 role="listbox"입니다 (다중 선택 시 aria-multiselectable 추가)
• 패널 내부는 Tree의 APG tree 패턴 키보드 내비게이션을 그대로 사용합니다
• 컴포넌트 외부를 클릭하거나 Escape를 누르면 닫히며, 닫힌 후 포커스는 트리거로 돌아갑니다

타입 정의

이 컴포넌트가 외부로 내보내는 TypeScript 타입 구조는 다음과 같습니다 (packages/components/tree-select/src/types.ts와 @lh-ui/share/core/* 소스에서 자동 추출되었습니다. 각 항목을 클릭하여 펼쳐 보세요. 속성 설명은 위쪽 Props 표를 참고하세요):

LhTreeSelectProps

export interface LhTreeSelectProps {
  /** 트리 데이터 */
  data: LhTreeNode[]
  /** 현재 값 (단일 선택 string / 다중 선택 string[], 제어형 v-model) */
  modelValue?: string | string[]
  /** 다중 선택 (체크박스 표시, 값은 선택된 키 배열) */
  multiple?: boolean
  /** 비활성화 */
  disabled?: boolean
  /** 플레이스홀더 텍스트 */
  placeholder?: string
  /** 패널을 body에 마운트할지 여부 (기본값 true) */
  teleported?: boolean
  /** sx 빠른 레이아웃 속성 */
  sx?: LhSxProps
}

LhTreeNode _{(@lh-ui/share/core/tree에서 제공)}

/** 트리 노드 데이터 */
export interface LhTreeNode {
  /** 고유 키 */
  key: string
  /** 표시 텍스트 */
  label: string
  /** 자식 노드 */
  children?: LhTreeNode[]
  /** 비활성화 */
  disabled?: boolean
  /** 리프 여부 (전달하지 않으면 children으로부터 추론) */
  isLeaf?: boolean
}