제한사항 및 문제 해결

Figma 및 변환 제한사항

지원되는 Figma 레이어 유형

Relay는 다음 레이어 유형만 지원합니다.

  • 텍스트 노드
  • 이미지 노드(PNG, JPEG 등)
  • 프레임 노드(자동 레이아웃 및 비 자동 레이아웃)
  • 구성요소 및 변형, 구성요소 인스턴스
  • 벡터 노드

지원되지 않는 Figma 레이어 및 기능

  • 프로토타입 제작 기능
  • 마스킹 그룹
  • 슬라이스 레이어

지원되지 않는 Figma 속성

지원되지 않는 속성은 다음과 같습니다.

  • 내부 그림자, 레이어 블러, 배경 블러
  • 레이어 회전(벡터 회전은 지원됨)
  • 레이어 또는 획 혼합 모드(채우기 혼합 모드는 지원됨)
  • 텍스트 속성:
    • 단락 간격
    • 단락 들여쓰기 간격
    • 숫자 스타일 지정
    • 서체
    • 스타일 세트
    • 취소선 및 밑줄
    • 줄 높이(전체 텍스트 요소에 적용할 때도 계속 작동)
  • 벡터 속성:
    • Android의 VectorDrawable 형식에서 지원되지 않는 기능:
      • 삽입된 비트맵 이미지
        • 벡터가 아닌 이미지로 지원되는 직사각형은 예외입니다.
      • 파선
      • 블러
      • 그림자
      • 패턴
      • 마스크
      • 그룹 불투명도
      • 방사형 그래디언트 초점
    • SVG 형식에서 지원되지 않는 기능:
      • 각진 그래디언트
      • 다이아몬드 그래디언트
    • 벡터 객체 간의 불리언 연산(합집합 / 빼기 / 교집합 / 제외)
      • 해결 방법은 단일 벡터로 결합하고 평면화하는 것입니다.

부분적으로 지원되는 Figma 레이어 및 속성

  • 텍스트 잘림(생략 부호)은 텍스트 항목이 한 줄밖에 없을 때 가장 안정적으로 작동합니다.
  • 채우기 색상:
    • 이미지에는 이미지 채우기가 하나만 있을 수 있지만 다른 유형(예: 그래디언트)의 채우기가 더 있을 수 있습니다.
    • 그래디언트의 경우 선형만 지원됩니다. 향후 출시에서는 나머지 그래디언트 유형(방사형, 다이아몬드, 각형)을 추가로 지원합니다.
    • Figma 플러그인에서는 매개변수가 여러 채우기를 허용할 수 있다고 지정할 방법이 없습니다. 채우기 색상을 매개변수화하려는 경우 현재는 매개변수에 단색만 지원됩니다.
  • 그림자:
    • 현재 그림자는 다음 레이어에서 작동하지 않습니다.
      • 직사각형이 아닌 벡터
      • 회전된 직사각형 벡터
    • 레이어당 여러 개의 그림자는 지원되지 않습니다.
    • '일반' 이외의 그림자 혼합 모드는 Android 버전 10 이상에서만 제공됩니다(다른 경우에는 무시됨).
    • 레이어의 그림자는 Android 버전 9 이상에서만 사용할 수 있습니다. 단, Compose에서 지원하는 모든 Android 버전에서 사용할 수 있는 텍스트는 예외입니다.
    • 그림자는 Compose에서 항상 투명한 레이어 뒤에 표시됩니다.
  • 자동 레이아웃 내 절대 위치 지정:
    • 절대 위치로 배치된 객체는 프레임의 모든 자동 레이아웃 요소 뒤 또는 앞에 있어야 합니다. 자동 레이아웃 요소 사이에 레이어된 절대 위치 객체는 이러한 객체 앞으로 푸시됩니다.
    • 다른 자동 레이아웃 프레임 내에 절대 위치로 배치된 객체가 있는 자동 레이아웃 프레임을 중첩하면 잘못된 레이아웃이 발생할 수 있습니다. 중첩된 프레임의 경계 상자가 해당 프레임에 배치된 항목으로 인한 영향을 받기 때문입니다.

스타일이 하나인 텍스트 매개변수로 전달되면 여러 스타일이 삭제됨

상위 구성요소가 스타일이 여러 개인 텍스트를 스타일이 하나뿐인 중첩된 구성요소 텍스트 매개변수로 전달하려고 하면 생성된 Compose 코드에서 여러 스타일이 손실됩니다. 텍스트 매개변수의 원래 스타일만 유지됩니다.

이러한 성능 저하는 생성된 코드의 컴파일을 막는 유형 불일치를 방지하는 데 필요합니다. 구성요소의 텍스트에 여러 스타일이 있다면 생성된 컴포저블은 AnnotatedText 매개변수를 보유하게 됩니다. 구성요소의 텍스트에 스타일이 하나만 있으면 생성된 컴포저블은 일반 String 매개변수를 보유하게 됩니다. 위 시나리오에서는 상위 구성요소의 서식 있는 텍스트를 AnnotatedText에서 String으로 변환하여 여러 스타일을 삭제하므로 중첩된 구성요소 인스턴스로 전달될 수 있습니다.

상위 구성요소와 변형 속성이 동일한 중첩된 구성요소를 컴파일하지 못함

두 구성요소의 [디자인 변형]{:.external}이 속성 이름이 동일하고 한 구성요소가 다른 구성요소에 중첩되는 경우 생성된 코드에서 두 변형에 관해 만들어진 enum은 이름이 동일하며 컴파일 오류가 발생합니다.

Conflicting import, imported name '(variant property)' is ambiguous

이 문제를 해결하려면 구성요소 중 하나의 변형 속성 이름을 변경하세요.

글꼴 지원

현재는 Google Fonts의 글꼴만 지원됩니다.

Android 스튜디오 문제 해결

Windows에서 SVG 리소스를 변환하는 중에 오류가 발생했습니다.

FAILURE: Build failed with an exception.
*   What went wrong:
Execution failed for task ':app:generateDebugRelayCode'.
> A failure occurred while executing com.google.relay.gradle.GenerateCode$GenerateCodeWorkAction
      > Converting SVG files: Exception Converting SVG resources for my_packaged_component
        The syntax of the command is incorrect

Android 스튜디오 프로젝트 이름이 너무 깁니다. Windows에서 Android 스튜디오 프로젝트는 70자(영문 기준) 이하여야 합니다. Google은 향후 릴리스에서 이 길이를 늘릴 수 있습니다.

업데이트를 Android 스튜디오로 가져올 수 없음

플러그인은 Figma 파일의 이름이 지정된 최신 버전만 가져옵니다. 변경사항이 있는, 이름이 지정된 새 버전의 Figma 파일을 만들었는지 다시 확인하세요.

빌드할 때 SVG 및 자바 런타임에 관한 오류가 발생함

Converting SVG Files: Exception running shell command 'cd /path-to/relay/bin; path/to/relay/bin/vd-tool -c -in path/to/hello_card -out /var/folders/...'.
The operation couldn't be completed. Unable to locate a Java Runtime.
Please visit http://www.java.com for information on installing Java.

자바 런타임을 설치한 다음 다시 빌드하세요.

빌드할 때 글꼴에 관한 오류가 발생함

다음과 같은 오류가 표시될 수 있습니다.

FAILURE: Build failed with an exception.
*   What went wrong:
Execution failed for task ':app:generateDebugRelayCode'.
> Multiple task action failures occurred:
   > A failure occurred while executing com.google.relay.gradle.GenerateCode$GenerateCodeWorkAction
      > /Users/me/AndroidStudioProjects/MyProject/app/build/generated/res/relay/debug/font/relay_inter_bold.ttf
   > A failure occurred while executing com.google.relay.gradle.GenerateCode$GenerateCodeWorkAction
      > /Users/me/AndroidStudioProjects/MyProject/app/build/generated/res/relay/debug/font/relay_inter_bold.ttf

이는 여러 구성요소가 동일한 글꼴을 동일한 디렉터리에 복사하려고 하는 경합 상태로 인해 발생합니다. 현재 Google에서는 이 문제를 해결하기 위해 노력하고 있습니다. 그동안은 다시 빌드해 보시기 바랍니다.

삭제된 UI 패키지 폴더 실행취소가 Android 스튜디오에서 실패할 수 있음

Android 스튜디오의 ui-packages 폴더 내에서 UI 패키지 폴더를 삭제한 후 삭제를 실행취소하면 삭제 전에 열지 않은 해당 폴더 내 모든 파일이 제대로 복원되지 않을 수 있습니다.

해결 방법: File > New > Import UI Packages…를 사용하여 필요한 Figma 파일의 버전을 다시 가져옵니다. 또한 가져올 때 UI 패키지 폴더의 모든 파일을 클릭하여 올바르게 복원할 수 있습니다.

ui-packages 외부에서 리소스를 업데이트해도 새 빌드가 강제 적용되지 않음

ui-packages 디렉터리 외부에 있는 종속 항목(예: 테마 매핑 파일 또는 참조 구성요소 파일)을 업데이트해도 프로젝트를 빌드할 때 코드가 강제로 다시 생성되지 않습니다.

해결 방법: 생성된 코드를 강제 업데이트하려면 프로젝트를 정리하거나(Build > Clean Project로 이동), 업데이트해야 하는 UI 패키지와 연결된 생성된 코드 폴더를 삭제하세요. 그런 다음 다시 빌드합니다.

생성된 코드 또는 폴더 ui-packages개가 Android 프로젝트 브라우저에 누락됨

Android 스튜디오용 Relay 플러그인에서 생성된 폴더가 표시되지 않는 경우가 있습니다. Android 프로젝트 브라우저에 나타납니다.

해결 방법: 프로젝트 폴더를 새로고침하려면 최상위 폴더를 마우스 오른쪽 버튼으로 클릭하고 '디스크에서 새로고침'을 선택합니다.

하위 구성요소의 앱 테마가 업데이트되지 않음

새 앱 테마로 상위 구성요소를 다시 가져오면 하위 구성요소(DEPS.txt에 나열됨)에는 새 테마가 적용되지 않습니다.

해결 방법: 상위 구성요소의 구성요소에서 미리보기 테마를 복사합니다. config.json로 대체하고 하위 구성요소의 각각에 포함된 테마 미리보기 각 config.json 다시 빌드한 후에는 하위 구성요소의 테마가 수정될 것입니다

UI 패키지 이름은 문자로 시작해야 함

UI 패키지 이름이 문자로 시작하지 않는 경우 Relay는 컴파일되지 않는 Compose 코드를 생성하고 The resource name must start with a letter라는 오류 메시지를 표시합니다.

해결 방법: Figma에서 UI 패키지 이름을 문자로 시작하도록 변경합니다.

Compose의 글꼴 패딩이 Figma와 일치하지 않음

Figma와 Compose는 경계 상자 내에 텍스트를 다르게 배치합니다. Compose는 경계 상자 상단에 패딩을 더 추가합니다.

해결 방법: Compose에서 올바르게 정렬되도록 Figma의 텍스트 위치를 몇 픽셀 위로 이동해야 합니다. Google에서는 문제를 완전히 해결하기 위해 노력하고 있습니다.