限制与故障排除

Figma 和转换限制

支持的 Figma 图层类型

Relay 只支持以下图层类型

文本节点
图像节点（PNG、JPEG 等）
框架节点（自动布局和非自动布局）
组件和变体，组件实例
矢量节点

不支持的 Figma 图层和功能

原型功能
蒙版组
切片图层

不支持的 Figma 属性

有一些不支持的属性，包括：

内阴影、图层模糊和背景模糊
图层旋转（支持矢量旋转）
图层或描边混合模式（支持填充混合模式）
文本属性
- 段落间距
- 段落缩进
- 数字样式
- 字形
- 风格集
- 删除线和下划线
- 行高（应用于整个文本元素时仍然有效）
矢量属性
- Android 的 VectorDrawable 格式不支持的功能
  - 嵌入式位图图像
    - 矩形除外，它们作为图像而不是矢量支持
  - 虚线描边
  - 模糊
  - 阴影
  - 图案
  - 蒙版
  - 组不透明度
  - 径向渐变焦点
- SVG 格式不支持的功能
  - 角度渐变
  - 菱形渐变
- 矢量对象之间的布尔运算（联合/减法/相交/排除）
  - 解决方法是组合并扁平化为单个矢量

部分支持的 Figma 图层和属性

文本截断（省略号）在文本项只有一行时最可靠
填充颜色
- 图像只能有一个图像填充，但可以有其他类型的附加填充（例如，渐变）
- 对于渐变，仅支持线性渐变。未来的版本将为其余的渐变类型（径向、菱形和角度）提供更多支持。
- 在 Figma 插件中，无法指定参数可以接受多个填充。如果要设置填充颜色的参数，目前仅支持纯色参数。
投影
- 投影目前在以下图层上不起作用：
  - 非矩形矢量
  - 旋转的矩形矢量
- 每个图层不支持多个投影。
- 除“普通”以外的投影混合模式仅在 Android 10 以上版本可用（否则忽略）。
- 图层上的投影仅在 Android 9 以上版本可用，文本除外，文本在 Compose 支持的所有 Android 版本上都可用。
- 在 Compose 中，阴影始终显示在透明图层之后。
自动布局中的绝对定位
- 绝对定位的对象必须位于框架中所有自动布局元素的后面或前面。任何位于自动布局元素之间的绝对定位对象都将被推到这些对象的前面。
- 嵌套包含绝对定位对象的自动布局框架可能会导致布局不正确，因为嵌套框架的边界框会受到该框架中定位项的影响。

如果一个样式中传递了多个样式，则多个样式将被丢弃

如果父组件尝试将具有多个样式的文本传递到只有一个样式的嵌套组件文本参数中，则生成的 Compose 代码中会丢失多个样式。仅保留文本参数的原始样式。

这种降级是必要的，以避免导致生成的代码无法编译的类型不匹配。如果组件中的文本具有多个样式，则生成的 Composable 将具有 AnnotatedText 参数。如果组件中的文本只有一个样式，则生成的 Composable 将具有普通的 String 参数。在上述情况下，我们需要将父组件的富文本从 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 Runtime 的错误

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 Runtime，然后重新构建。

构建时收到有关字体的错误

您可能会看到类似于以下的错误：

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 中，撤消已删除的 UI 包文件夹可能会失败

如果您在 Android Studio 中的 ui-packages 文件夹中删除了 UI 包文件夹，然后撤消了删除操作，则在删除之前未打开的该文件夹中的任何文件可能无法正确恢复。

解决方法：使用文件 > 新建 > 导入 UI 包…重新导入所需的 Figma 文件版本。您也可以在导入时点击 UI 包文件夹中的每个文件，以确保它们能够正确恢复。

更新 ui-packages 外部的资源不会强制进行新的构建

更新位于 ui-packages 目录之外的依赖项（例如主题映射文件或参考组件文件）不会在您构建项目时强制重新生成代码。

解决方法：要强制更新生成的代码，请清理项目（转到构建 > 清理项目）或删除与需要更新的 UI 包关联的生成的代码文件夹。然后，重新构建。

生成的代码或 `ui-packages` 文件夹在 Android 项目浏览器中缺失

在某些情况下，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 中正确对齐。我们正在努力寻找永久性解决方案。

为您推荐

注意：禁用 JavaScript 时将显示链接文本
了解 UI 包和生成的代码
文本中的多个样式
将组件映射到现有代码