기존 코드에 구성요소 매핑

개발자는 생성된 코드 대신 UI 패키지와 기존 코드 구성요소 간의 매핑을 제공하여 코드 생성 프로세스를 맞춤설정할 수 있습니다. 이는 기존 구현에 생성된 코드로는 달성할 수 없는 기능(예: 드롭다운 메뉴와 같은 복잡한 동작, 애니메이션 등)이 있는 경우에 유용합니다.

구성요소를 매핑하는 방법은 매핑 파일을 사용하여 지정합니다. 매핑 파일은 코드 생성기가 적절한 클라이언트 코드를 생성할 수 있도록 타겟 구성 가능한 함수에 도달하는 방법을 알려줍니다.

매핑된 구성요소 개요 다이어그램

예를 들면 다음과 같습니다.

디자이너가 Figma에서 Play Bar 구성요소의 인스턴스를 포함하는 카드 구성요소를 만들고 두 구성요소를 패키징하여 개발자에게 전달합니다.

개발자가 Figma에서 UI 패키지를 가져오면 ui-packages에 card와 play_bar라는 두 개의 디렉터리가 생성됩니다. 개발자가 프로젝트를 빌드하면 Card와 PlayBar라는 두 개의 구성 가능한 함수가 생성됩니다. 일반적으로 Figma에서 Card는 Play Bar 인스턴스를 포함하므로 코드에서 Card 구성 가능한 함수는 PlayBar 호출을 포함합니다.

그런데 디자이너와 개발자는 Card가 Figma에서 설명하기 어려운 기능을 갖고 있는 기존 컴포저블 MyExistingPlaybar를 사용하도록 하고자 합니다. 따라서 개발자는 play_bar UI 패키지를 MyExistingPlaybar에 매핑하는 play_bar.json이라는 매핑 파일을 추가합니다.

{
    "target": "MyExistingPlaybar",
    "package": "com.example.myApp"
}

이제 개발자가 프로젝트를 빌드하면 Card가 PlayBar 대신 MyExistingPlaybar를 호출합니다. 이때 MyExistingPlaybar는 PlayBar와 동일한 매개변수를 가져야 합니다(단, 아래의 추가 지침에 설명된 것처럼 몇 가지 차이점은 있을 수 있음).

매핑 파일

Android 스튜디오 프로젝트에서 매핑 파일은 ui-packages 폴더 옆의 ui-package-resources/mappings 아래에 추가됩니다. Relay는 빌드 중에 매핑 파일을 찾습니다.

프로젝트 뷰의 매핑 파일

매핑 파일 생성

Relay는 가져온 UI 패키지의 매핑 파일을 생성할 수 있습니다. 다음 단계를 따르세요.

  1. 패키지 폴더 또는 타겟 ui-package 폴더 내의 파일을 마우스 오른쪽 버튼으로 클릭합니다. 매핑 파일 생성을 선택합니다.

    매핑 파일 어포던스 생성

  2. 대화상자에서 다음 옵션을 구성합니다.

    매핑 파일 생성 대화상자

    • 파일 위치: 생성된 매핑 파일의 위치를 설정합니다.

    • 타겟 컴포저블: 생성된 컴포저블 대신 사용되는 맞춤 컴포저블을 설정합니다. 기존 컴포저블을 사용하거나 대화상자에서 새 컴포저블을 만들 수 있습니다. 새 컴포저블을 만들면 UI 패키지에 정의된 것과 동일한 매개변수를 사용하여 컴포저블이 생성됩니다.

    • 생성된 파일: 매핑 파일에서 generateImplementation 및 generatePreview 옵션을 설정합니다. 자세한 내용은 아래의 파일 콘텐츠 매핑을 참고하세요.

  3. 매핑 파일 생성을 클릭합니다. 지정된 구성으로 ui-package-resources/mapping 폴더 내에 새 매핑 파일이 생성됩니다.

다음 단계에 따라 Relay 패키지 모듈 UI에서 매핑 파일 생성 대화상자를 열 수도 있습니다.

  1. 대상 ui-package 폴더 내의 UI 패키지 파일을 클릭합니다.

  2. 릴레이 도구 창이 자동으로 열리지 않으면 릴레이 아이콘을 클릭하여 창을 엽니다.

  3. 패키지 옵션에서 Generate mapping file(매핑 파일 생성) 버튼을 클릭합니다.

    매핑 파일 어포던스 생성

매핑 파일 이름

매핑 파일의 이름은 기존 구성요소 UI 패키지 폴더의 이름과 일치해야 합니다. 따라서 play_bar.json은 ui-packages/mappings 폴더의 UI 패키지를 기존 코드 구성요소에 매핑합니다.

파일 콘텐츠 매핑

매핑 파일에는 다음 속성이 포함됩니다.

  • target: (필수) 맞춤 구성 가능한 함수의 이름입니다. 기본적으로 생성된 코드로 생성된 함수의 이름입니다.

    "target" : "CustomComposableName"

  • package: (필수) 맞춤 컴포저블이 있는 패키지의 이름입니다. 기본적으로 이는 생성된 코드로 생성된 함수의 패키지입니다.

    "package" : "com.example.podcastapp.ui.components"

  • generateImplementation: (선택사항) true 또는 false입니다. 이 값이 true이면 생성된 코드 파일에 이 UI 패키지의 구현이 계속 생성됩니다. false인 경우 구현이 생성되지 않습니다. 기본값은 true입니다.

    "generateImplementation" : true

  • generatePreviews: (선택사항) true 또는 false입니다. 이 속성이 true이면 생성된 코드 파일에 매핑된 맞춤 구성요소의 미리보기가 생성됩니다. false인 경우 미리보기가 생성되지 않습니다. 기본값은 true입니다.

    "generatePreviews" : true

매핑된 변형

Figma 구성요소에 변형이 있으면 생성된 컴포저블에는 (디자인 변형 처리 튜토리얼에서 설명하는 것처럼) 변형을 인코딩하는 enum 매개변수가 포함됩니다. 변형이 있는 Figma 구성요소를 기존 코드에 매핑하려면 생성된 컴포저블과 동일한 매개변수를 사용하는 컴포저블에 매핑해야 합니다. 예를 들어 속성이 ChipType, Chip의 생성된 컴포저블 서명은 다음과 같습니다.

@Composable
fun Chip(
    modifier: Modifier = Modifier,
    chipType: ChipType = ChipType.Red,
    chipText: String
) { ... }

Chip Figma 구성요소를 기존 MyChip 컴포저블에 매핑하려면 MyChip의 서명이 생성된 컴포저블과 동일한 서명을 가져야 합니다 (지정된 추가 지침이 없다는 전제하에). 개념적으로 이는 기존 코드 구성요소가 Figma 구성요소와 동일한 디자인 변형을 지원할 수 있음을 의미합니다.

추가 지침

예를 들어 타겟팅하려는 구성 가능한 함수의 서명이 다음과 같다고 가정해 보겠습니다.

@Composable
fun MyChip(
    modifier: Modifier = Modifier,
    chipType: ChipType = ChipType.Red,
    description: String  // instead of chipText
) { ... }

매개변수가 매핑되는 방식에 영향을 주는 fieldMappings 블록을 매핑 파일에 추가할 수 있습니다. 이때 이 블록은 Chip의 chipText 매개변수에서 MyChip의 description 매개변수로의 매핑을 포함합니다.

{
    "target": "MyChip",
    "package": "com.example.myApp",
    "fieldMappings": [
        {
            "type": "parameter",
            "source": "chipText",
            "target": "description"
        }
    ]
}

fieldMappings 블록의 유형은 다음과 같습니다.

  • parameter: UI 패키지 필드를 코드 매개변수에 매핑합니다.
    • source: UI 패키지에 지정된 매개변수 이름입니다.
    • target: 타겟 코드 구성요소에 지정된 매개변수의 이름입니다.
  • lambda: UI 패키지 필드를 콘텐츠 람다에 매핑합니다.
    • source: UI 패키지에 지정된 매개변수 이름입니다.
    • target: 타겟 코드 구성요소에 지정된 매개변수의 이름입니다.

  • modifier: UI 패키지 필드를 수정자 메서드에 매핑합니다.

    • source: UI 패키지에 지정된 매개변수 이름입니다.
    • method: 생성된 코드에서 호출되어야 하는 수정자 객체의 메서드입니다.
    • parameter: 지정된 수정자 메서드 내의 매개변수 이름입니다.
    • library: 수정자 메서드에 액세스하기 위해 가져올 정규화된 패키지 이름입니다.
    • scope: 수정자의 범위를 나타내는 두 값 중 하나입니다.
    • any: 모든 수신기 범위에서 수정자를 사용할 수 있습니다.
    • relay: Relay RelayContainer 객체의 수신기 범위에서 수정자를 사용해야 합니다.