限制與疑難排解

Figma 和轉譯限制

支援的 Figma 圖層類型

Relay 僅支援下列圖層類型：

  • 文字節點
  • 圖片節點 (PNG、JPEG 等)
  • 畫面節點 (自動版面配置和非自動版面配置)
  • 元件和變化版本、元件執行個體
  • 向量節點

不支援的 Figma 圖層與功能

  • 原型設計功能
  • 遮蓋群組
  • Slice 圖層

不支援的 Figma 屬性

有幾個不支援的屬性，包括：

  • 內陰影、圖層模糊處理及背景模糊處理
  • 圖層旋轉 (支援向量旋轉)
  • 圖層或筆劃混和模式 (支援填滿混和模式)
  • 文字內容：
    • 段落間距
    • 段落縮排
    • 數字樣式
    • 字母形式
    • 文體集
    • 刪除線和底線
    • 行高 (套用至整個文字元素時仍適用)
  • 向量屬性：
    • Android VectorDrawable 格式不支援的功能：
      • 內嵌點陣圖圖片
        • 矩形除外，支援做為圖片而非向量
      • 虛線筆劃
      • 模糊處理
      • 陰影
      • 圖案
      • 面具
      • 群組不透明度
      • 放射漸層焦點
    • 可擴充向量圖形格式不支援的功能︰
      • 角度漸層
      • 菱形漸層
    • 向量物件之間的布林作業 (聯集/相減/交集 /排除)
      • 解決方法是組合並壓平合併成單一向量

部分支援的 Figma 圖層與屬性

  • 文字項目只有一行時，文字截斷 (省略符號) 最為可靠
  • 填滿顏色：
    • 圖片只能採用一種圖片填滿，但可以採用其他類型的額外填滿 (例如漸層)。
    • 如為漸層，僅支援線性。日後推出的版本將支援其餘漸層類型 (放射狀、菱形和角度)。
    • 在 Figma 外掛程式中，無法指定參數可接受多種填滿。如要為參數設定顏色填滿，目前參數僅支援單色。
  • 投射陰影：
    • 投射陰影目前不適用於下列圖層：
      • 非矩形向量
      • 旋轉矩形向量
    • 每個圖層不支援多個投射陰影。
    • 「一般」以外的投射陰影混和模式僅適用於 Android 10 以上版本 (除非不需要)。
    • 圖層的投射陰影僅適用於 Android 9 以上版本，但文字除外，文字可在 Compose 支援所有 Android 版本上使用。
    • 在 Compose 中，陰影將一律在透明圖層後方顯示。
  • 自動版面配置中的絕對定位：
    • 絕對定位物件必須位於影格所有自動版面配置元素的後方或前方。在自動版面配置元素之間疊加的任何絕對定位物件，將會推送至這些物件的前方。
    • 在其他自動版面配置頁框中，以絕對定位物件建立巢狀結構的自動版面配置頁框，可能會導致版面配置不正確，因為巢狀結構頁框的定界框會影響該頁框中的定位項目。

如果傳遞至只有一種樣式的文字參數，則會捨棄多種樣式

如果父項元件嘗試將包含多個樣式的文字傳遞至只有一種樣式的巢狀元件文字參數，則多個樣式會在產生的 Compose 程式碼中遺失。只會保留文字參數的原始樣式。

必須進行降級，以免造成類型不符的問題，致使產生的程式碼無法編譯。如果元件中的文字有多種樣式，產生的可組合項則會包含 AnnotatedText 參數。如果元件中的文字只有一種樣式，產生的可組合項將會有純 String 參數。在上述情境中，我們必須將父項元件的 RTF 格式從 AnnotatedText 轉換為 String，捨棄多個樣式，以將其傳遞至巢狀元件執行個體。

子類屬性與父項元件相同的巢狀元件無法編譯

如果兩個元件有相同屬性名稱的 [設計變化版本]{:.external}，並在產生的程式碼中相互巢狀，為兩個變化版本建立的列舉將具有相同名稱，且會發生編譯錯誤：

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

如要解決此問題，請變更其中一個元件的變化版本屬性名稱。

字型支援

我們目前僅支援 Google Fonts 的字型。

Android Studio 疑難排解

我收到在 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 Studio 專案名稱可能過長。在 Windows 中，Android Studio 專案的完整路徑不得超過 70 個半形字元。我們正在努力在日後推出的版本中提高這個長度。

更新無法匯入 Android Studio

外掛程式只會下拉 Figma 檔案的最新已命名版本。 請再次檢查包含變更的 Figma 檔案新的已命名版本。

建構時收到 SVG 與 Java 執行階段的錯誤

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.

安裝 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

這是因為競爭狀況所致：多個元件嘗試將同一字型複製到同一目錄。我們正在設法解決此問題。同時，請再嘗試建構。

在 Android Studio 中，無法復原已刪除的使用者介面套件資料夾

刪除 Android Studio 中 ui-packages 資料夾中的「UI Package」資料夾後，如要復原刪除動作，則該資料夾中未開啟的所有檔案可能無法正確還原。

解決方法：前往「File」>「New」>「Import UI Packages...」 重新匯入所需 Figma 檔案版本 您也可以在匯入後按一下「UI Package」資料夾中的每個檔案，以確保正確還原。

在 ui-package 外更新資源不會強制執行新版本

更新 ui-packages 目錄外的依附元件 (例如主題對應檔案或參照元件檔案) 並不會強制在建構專案時重新產生程式碼。

解決方法：如要強制更新產生的程式碼，請清除專案 (依序前往「Build」>「Clean Project」) 或刪除與要更新 UI 套件關聯的程式碼資料夾。然後再次建構。

Android 專案瀏覽器缺少產生的程式碼或 ui-packages 資料夾

在某些情況下，Relay for Android Studio 外掛程式產生的資料夾不會顯示在 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 會在定界框的頂端加入更多邊框間距。

解決方法：您必須將 Figma 中的文字位置向上移動幾個像素，才能在 Compose 中正確對齊。我們正在設法提供永久的修正方案。