LVRS Storyboard Frame

components/navigation/PageRouter.svx

Path: components/navigation/PageRouter.svx

Last modified:

PageRouter

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

PageRouter는 LVRS용 스택 내비게이션 엔진으로, 경로 문법, StackView 연산, 선택적 뷰-모델 바인딩 메타데이터 및 뷰-상태 추적을 결합합니다.

목적

  • 경로 메타데이터를 사용하여 푸시/리플래스/루트 탐색을 제공합니다.
  • static/param/rest 경로를 해결하십시오.
  • 경로 스택(path)을 시각 스택과 동기화 상태로 유지하십시오.
  • Navigator, ViewModels 및 ViewStateTracker와 통합하십시오.

코어 API

경로 구성:

  • routes
  • initialPath
  • notFoundComponent
  • notFoundSource

스택 상태:

  • path
  • currentPath
  • currentParams
  • canGoBack
  • depth
  • currentPageItem

행동 플래그:

  • registerAsGlobalNavigator
  • enforcePageViewport
  • isolateInactivePages
  • retainInactivePageCount
  • routeResolveCacheCapacity

신호:

  • navigated(path, params)
  • navigationFailed(path)
  • componentNavigated(component)

탐색 방법:

  • go(path, params) / push(path, params)
  • replace(path, params)
  • setRoot(path, params)
  • back() / pop()
  • popToRoot()
  • goTo(component, params)
  • replaceWith(component, params)
  • setRootComponent(component, params)

경로 문법

  • 정적 세그먼트: /reports
  • 동적 세그먼트: /runs/[id]
  • 휴식 구간: /logs/[...path]

경로 정규화는 선행 슬래시를 적용하고 루트를 제외한 후행 슬래시를 제거합니다.

MVVM에 대한 라우트 메타데이터

경로당 선택 메타데이터에는 다음이 포함될 수 있습니다:

  • viewModelKey 또는 modelKey
  • viewId
  • writable 또는 modelWritable

제공되고 ViewModels가 존재하는 경우, 라우터는 탐색 중에 자동으로 ViewModels.bindView(...)를 호출합니다.

사용법

import QtQuick
import LVRS 1.0 as LV

LV.PageRouter {
    id: router
    routes: [
        { path: "/", component: homePage, viewModelKey: "HomeVM", writable: true },
        { path: "/runs/[id]", component: runPage }
    ]
}

동작 원리

스택 작업 흐름:

  1. 정규화된 경로로 경로를 해결합니다.
  2. 라우트 매개변수를 호출자 매개변수와 병합합니다.
  3. StackView 작업을 적용하십시오 ( push , replace , set ).
  4. 정규화된 경로 입력을 사용하여 path 배열을 업데이트하십시오.
  5. currentPath/currentParams를 업데이트하고 내비게이션 신호를 발신하십시오.

프레젠테이션 흐름:

  • enforcePageViewport == true일 때, 새 페이지 항목은 라우터 뷰포트에 제한됩니다.
  • isolateInactivePages == true인 경우, 상단 페이지만 표시되거나 활성화된 상태로 유지됩니다.
  • retainInactivePageCount > 0일 때, N 페이지를 상단 아래에 두고 나머지는 잘라 주세요.

라우트 해석 흐름:

  • 경로 정규화/매칭은 RouteMatcher ( C++ 싱글턴 )를 선호합니다.
  • routeResolveCacheCapacity에 의해 제어되는 경로 해결 LRU 캐시를 사용하여 반복 조회 비용을 줄이십시오.

트래커 흐름:

  • 라우터는 path에서 추적 항목을 빌드합니다.
  • ViewModels 바인딩과 ViewStateTracker 상태를 동기화합니다(전 세계적으로 활성 라우터인 경우).

실패 행동

  • 경로가 누락되어 있고 누락됨 대체 경로 가 없으면 navigationFailed(path) 를 발생시킵니다.
  • 라우트가 존재하지만 구성 요소/소스가 누락된 경우: navigationFailed(path)를 방출합니다.

고급 예시: Dynamic + Rest Segment Route Set

import QtQuick
import LVRS 1.0 as LV

LV.PageRouter {
    routes: [
        { path: "/runs/[id]", component: runPage, viewModelKey: "RunVM" },
        { path: "/logs/[...path]", component: logPage, viewModelKey: "LogVM" }
    ]
}

/logs/a/b/c는 params.path = "a/b/c"를 rest-segment 규칙으로 해결합니다.

문제 해결 체크리스트

  • 라우트가 일치하지 않음: 정규화된 경로와 세그먼트 토큰 구문을 확인하십시오 ( [id] , [...path] ),
  • 페이지 항목이 표시되지 않습니다: 경로에 component 또는 source가 있는지 확인하십시오,
  • 모델 바인딩이 없습니다: viewModelKey/modelKey가 ViewModels 레지스트리에 존재하는지 확인하십시오.
  • 경로 변경 후에도 오래된 매치가 남아 있는 경우: routes가 변경될 때 캐시가 자동으로 삭제됩니다.

라우트 작성 가이드라인

  • 라우트 매개변수 이름을 안정적으로 유지하고, 리네임은 종속 페이지에 대해 API를 깨는 것으로 간주하십시오.
  • 무관한 페이지 의미론으로 하나의 라우트 경로를 과부하하지 않도록 하십시오.
  • 사용자에게 보이는 대체 경로에 대해 무음의 실패 로그보다 명시적인 not found 컴포넌트를 선호하십시오.

관측 가능성 훅

앱 진단 패널에서 이러한 신호를 계측하십시오:

  • navigated(path, params)
  • navigationFailed(path)
  • componentNavigated(component)