본문으로 건너뛰기
가이드

App Menu 목적지 추가

Resource 목적지와 독립 App 페이지를 App Menu에 공개하고, 각각이 올바른 행위자에게만 나타나는지 확인합니다.

이미 만든 App 화면을 App 메뉴에 노출합니다. App 패키지 만들기를 마친 App과 동작하는 화면이 필요합니다. 메뉴 선언과 별도로 해당 API의 읽기 권한을 먼저 구현하세요.

목적지 등록

Manifest의 contribution 경로에 NavigationContribution 구현을 두고 navigationItems()에서 목적지를 반환합니다. 아래 코드는 packages/people/src/Contribution/PeopleWorkNavigation.php의 실제 온보딩 목적지만 남긴 완전한 contribution입니다.

코드 예시
PHP
<?php

namespace Nexia\Apps\Amuz\People\Contribution;

use Nexia\Navigation\Contracts\NavigationContribution;
use Nexia\Navigation\NavigationItem;

final class PeopleWorkNavigation implements NavigationContribution
{
    public static function navigationItems(): array
    {
        return [NavigationItem::make(
            id: 'people-onboarding',
            route: '/apps/people/onboarding',
            icon: 'list-checks',
            sort: 210,
            labelKey: 'people.onboarding.title',
            appKey: 'people',
            contextId: 'app',
            groupId: 'management',
            permission: 'people.onboarding_case.read',
        )];
    }
}

labelKey에는 번역 카탈로그 키, permission에는 이미 선언한 읽기 권한을 넣습니다. 이 권한은 링크 표시 여부를 결정하므로 API에서도 권한을 검사해야 합니다. 별도 화면을 새로 만들었다면 App 화면 만들기에 따라 컴포넌트 등록과 pageElementsExtras() 연결을 완료합니다.

프로젝트에서 nexia dev를 실행하고 선언 동기화·샌드박스 준비 완료를 기다리세요. 이미 감시 중이라면 중복 실행하지 않습니다. 새 권한은 워크스페이스의 설정 → 자격 증명 및 접근에서 부여합니다. 앱 개발자가 Core Artisan이나 호스트 캐시 명령을 실행할 필요는 없습니다.

결과 확인

App이 운영 가능한 테넌트에서 읽기 권한이 있는 계정으로 메뉴를 엽니다. 관리 그룹의 온보딩 항목을 누르면 연결한 화면이 열려야 합니다. 권한이 없는 계정에서는 메뉴가 사라지고 같은 API 요청도 거절되어야 합니다. 명령 팔레트에서 번역된 제목으로 검색하면 검색 노출도 확인할 수 있습니다.

Resource 목록과 배치

생성된 Resource는 ContributesNavigationDestination을 통해 메뉴를 제공합니다. 별도 contribution을 중복 생성하지 말고 $navigation을 조정하세요. 생성 과정은 Resource 만들기에 있습니다. visible: false는 메뉴만 숨기며 Resource 경로는 유지합니다.

설정쓰임
contextId: 'app'소유 App의 app:{app_key}로 해석
groupId: nullApp 개요처럼 그룹 밖에 배치
insights, management, operations, master-data, settingsApp에서 사용하는 그룹
subgroupId그룹 안의 하위 묶음; groupId 필요
permission 배열나열한 권한 중 하나가 있으면 노출
searchable: false검색 결과에서 제외

Shell 컨텍스트와 그룹 순서는 플랫폼이 관리합니다. 설정 화면은 설정 페이지 추가, 에이전트의 화면 이동은 Command Palette 검색를 이어서 보세요. 부모 목적지, 활성 경로 패턴, 대상 집단 옵션은 packages/app-sdk/packages/laravel/src/Navigation/NavigationItem.php에 정의되어 있습니다.

항목이 나타나지 않을 때

선언 반영 후에도 앱 실행 준비, 사용자 권한, 화면 컴포넌트 등록을 확인해야 합니다. 앱 테스트를 참고하세요.

CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.

화면 쿼리 매개변수

레코드와 관계 선택에 필요한 참조를 앱 화면 쿼리에 유지하세요. Core는 URL 인코딩된 쿼리를 포함하여 디코딩된 screen 대상의 길이를 32,768자까지 허용하며, 경로 본문은 2,048자로 제한합니다. 대상은 같은 앱에 등록된 경로와 계속 일치해야 합니다. 이는 Core 탐색 한도이며 브라우저나 프록시의 요청 크기를 보장하지 않습니다. 앱 API는 참조와 권한을 계속 검증합니다. URL을 줄이려고 관계 참조를 제거하지 마세요.

관련 이슈.

원본 위치: docs/developers/content/ko/platform-extensions/add-navigation.md