계층 구조

위치: qml/components/navigation/Hierarchy.qml

Hierarchy는 툴바와 스크롤 가능한 계층 목록으로 구성된 트리 패널 표면입니다.

목적

• 명시적인 확장/축 축소 컨트롤을 사용하여 중첩된 모델 데이터를 렌더링합니다.
• 호스트 기능에 대한 활성화 및 확장 콜백을 제공합니다.
• 중첩된 스크롤 컨테이너 내에서 트리 탐색을 사용할 수 있도록 유지합니다.

API

필수 입력:

• 도구 모음 선언: toolbarItems(배열 모델) 또는 toolbarButtons(수동 ToolbarButton 하위)
• 목록 모델 바인딩: model / treeModel

모델 및 선택 별칭:

• model / treeModel
• activeListItem
• activeListItemId
• activeListItemKey

도구 모음 별칭:

• toolbarButtons
• toolbarItems
• activeToolbarButton
• activeToolbarButtonId
• activeToolbarIndex

동작 별칭:

• autoExpandDepth
• keyboardListNavigationEnabled

선택적 바닥글:

• footerVisible
• footerInteractive
• footerButton1
• footerButton2
• footerButton3

방법:

• expandAll()
• collapseAll(keepRootExpanded)
• activateListItemById(itemId)
• activateListItemByKey(itemKey)
• triggerFooterButton(index)

신호:

• toolbarActivated(button, buttonId, index)
• toolbarButtonTriggered(button, buttonId, index, item)
• toolbarEventTriggered(eventName, payload, index, item, buttonId)
• listItemActivated(item, itemId, index)
• listItemExpanded(item, itemId, index, expanded)
• footerButtonTriggered(index, config)

사용법

import LVRS 1.0 as LV

LV.Hierarchy {
    toolbarItems: [
        { id: "structure", iconName: "projectStructure", eventName: "hierarchy.structure" },
        { id: "layers", iconName: "projectStructure", events: ["hierarchy.layers", "analytics.layers"] }
    ]
    model: [
        {
            key: "root",
            label: "Root",
            expanded: true,
            children: [{ key: "child", label: "Child" }]
        }
    ]
    footerVisible: true
    footerButton1: ({ type: "icon", iconName: "projectStructure" })
    footerButton2: ({ type: "icon", iconName: "delete" })
    footerButton3: ({ type: "menu", iconName: "viewMoreSymbolicDefault" })
}

동작 원리

• 도구 모음과 목록은 명시적인 신호와 전달된 별칭을 통해 통신합니다.
• ensureListItemVisible는 목록이 가시성을 요청할 때 깜박일 수 있는 뷰포트를 조정합니다.
• 중첩된 스크롤 블리드를 방지하기 위해 WheelScrollGuard가 설치되었습니다.
• 옵션 ListFooter는 왼쪽 하단에 고정되어 있습니다. 표시되면 목록 뷰포트가 바닥글 상단에서 끝납니다.

고급 사용법: 프로그래밍 방식 활성화

import LVRS 1.0 as LV

LV.Hierarchy {
    id: tree
}

function focusNodeByKey(key) {
    tree.activateListItemByKey(key)
}

운영 참고 사항

• 안정적인 프로그래밍 방식 활성화를 위해 항목 ID/키를 안정적으로 유지하세요.
• 온보딩 흐름에서 expandAll()와 activate*()를 결합하여 결정론적으로 딥 노드를 표시합니다.

실패 패턴

형제 노드에 고유하지 않은 키를 사용하면 프로그래밍 방식 활성화 및 확장 추적이 중단됩니다. 각 논리 노드에 안정적인 고유 식별자를 할당합니다.