ContextMenu

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

ContextMenu는 런타임 -aware outside-dismiss 브리지를 포함한 팝업 메뉴입니다.

목적

• 유연한 모델 유형에서 메뉴 항목을 렌더링합니다.
• 중첩 오버레이/이벤트 컨텍스트에서 견고한 클로즈 동작을 제공하십시오.

API

데이터/선택:

• items
• selectedIndex
• itemTriggered(index, item) 신호
• itemEventTriggered(eventName, payload, index, item) 신호

레이아웃/시각적:

• itemWidth
• itemSpacing
• menuColor(기본값: Theme.contextMenuSurface = Theme.panelBackground03)
• menuOpacity(기본값: 1.0)
• resolvedMenuColor
• dividerColor(기본값: Theme.contextMenuDivider = Theme.panelBackground08)

행동:

• autoCloseOnTrigger
• dismissOnGlobalPress
• dismissOnGlobalContextRequest

방법:

• openAt(x, y)
• openFor(item, x, y)
• dismissIfOutsideGlobalEvent(eventData)
• triggerEntry(index)

엔트리 모델 규칙

각 항목은 원시 문자열 또는 객체 맵일 수 있습니다.

객체 필드 (공통):

• label/text/title
• key/shortcut
• iconName/icon
• iconSource/source
• enabled
• state
• selected
• showChevron / hasSubmenu
• selectionDirection / direction / chevronDirection (right|left|up|down)
• eventName / event / action
• eventPayload / payload
• events(문자열 또는 이벤트 객체의 배열)
• onTriggered / onClicked / handler (함수 콜백)
• closeOnTrigger / autoClose / keepOpen / preventClose

구분자 감지:

• type: "divider" 또는 divider: true

콜백 컨텍스트

항목 콜백( onTriggered / onClicked / handler )이 제공될 경우, ContextMenu는 하나의 객체로 이를 호출합니다:

• index
• item
• menu
• eventName (첫 번째 해결된 이벤트 이름)
• payload (첫 번째 해결된 페이로드)
• emit(eventName, payload) ( 런타임 사용자 정의 이벤트 발생)
• close() (강제 닫기)

전략 무시

2 경로는 함께 사용됩니다:

1. 팝업 닫기 정책 (CloseOnPressOutside 등).
2. 글로벌 이벤트 브리지(EventListener와 globalPressed / globalContextRequested)에서 dismissIfOutsideGlobalEvent를 호출합니다.

이 이중 경로는 레이어드 오버레이 전반에 걸쳐 근접 행동 결정론을 유지합니다.

사용법

import LVRS 1.0 as LV

LV.ContextMenu {
    id: menu
    items: [
        {
            id: "copy",
            label: "Copy",
            key: "Cmd+C",
            showChevron: false,
            eventName: "menu.copy",
            eventPayload: ({ source: "editor" }),
            onClicked: function(ctx) {
                console.log("callback:", ctx.eventName, JSON.stringify(ctx.payload))
                ctx.emit("analytics.menuClick", ({ id: "copy" }))
            }
        },
        { type: "divider" },
        {
            id: "inspect",
            label: "Inspect",
            showChevron: false,
            events: [
                "menu.inspect",
                { name: "analytics.menuClick", payload: ({ target: "inspect" }) }
            ],
            keepOpen: true
        }
    ]

    onItemEventTriggered: function(eventName, payload, index, item) {
        console.log("event:", eventName, index)
    }
}

고급 예시: 외부 디스미스가 있는 커서 근처 열기

import LVRS 1.0 as LV

LV.ContextMenu {
    id: menu
    dismissOnGlobalPress: true
    dismissOnGlobalContextRequest: true
}

function openMenu(eventData) {
    menu.openAt(eventData.globalX, eventData.globalY)
}

실용적인 참고 사항

• 엔트리 레벨 closeOnTrigger / keepOpen를 사용하여 행당 닫기 동작을 재정의하십시오.
• 구분자 항목을 명시적으로 유지하여 객체 유형 행에서 모호성을 방지하십시오.
• 테스트 또는 명령 라우팅에서 프로그래밍 호출에 triggerEntry(index)를 사용하십시오.

실패 패턴

변환 없이 로컬 아이템 공간의 좌표가 포함된 메뉴를 열 경우, 대상 외에 팝업을 배치할 수 있습니다. openFor(item, x, y)를 사용하거나 좌표를 오버레이 부모 공간으로 변환하십시오.