限制和故障排除

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 运行时的错误

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 中，撤消已删除的 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 代码，并显示一条错误消息，提示 资源名称必须以字母开头。

解决方法：在 Figma 中，重命名 UI 包名称，使其以字母开头。

Compose 中的字体填充与 Figma 不匹配

Figma 和 Compose 在其边界框内以不同的方式布局文本。Compose 在边界框的顶部添加了更多填充。

解决方法：您需要在 Figma 中将文本位置向上移动几个像素，才能使其在 Compose 中正确对齐。我们正在努力寻找永久性解决方法。