局限性和问题排查

Figma 和翻译限制

支持的 Figma 图层类型

Relay 仅支持以下层类型:

  • 文本节点
  • 图片节点(PNG、JPEG 等)
  • 框架节点(自动布局和非自动布局)
  • 组件和变体、组件实例
  • 矢量节点

不受支持的 Figma 图层和功能

  • 原型设计功能
  • 遮罩组
  • Slice 层

不受支持的 Figma 属性

有一些不受支持的属性,包括:

  • 内部阴影、图层模糊处理和背景模糊处理
  • 图层旋转(支持矢量旋转)
  • 图层或描边混合模式(支持填充混合模式)
  • 文字属性:
    • 段落间距
    • 段落缩进
    • 数字样式
    • 字母
    • 样式设置
    • 删除线和下划线
    • 行高(仍然适用于整个文本元素)
  • 矢量属性:
    • Android 的 VectorDrawable 格式不支持以下功能:
      • 嵌入式位图图像
        • 矩形除外,它可以作为图像而不是矢量
      • 虚线描边
      • 模糊
      • 阴影
      • 图案
      • 遮罩
      • 组不透明度
      • 径向渐变焦点
    • SVG 格式不支持的功能:
      • 角度渐变
      • 菱形渐变
    • 矢量对象之间的布尔运算(并集/相减/相交/排除)
      • 一种权宜解决方法是组合并扁平化为单个矢量

受到部分支持的 Figma 图层和属性

  • 当文本项只有一行时,文本截断(省略号)可以最可靠地运行
  • 填充颜色:
    • 图片只能使用一种图片填充,但可以使用更多种其他类型的填充(例如渐变)。
    • 对于渐变,仅支持线性渐变。未来版本将增加对其余渐变类型(径向、菱形和角度)的支持。
    • 在 Figma 插件中,无法指定某个参数可以接受多种填充。如需对填充颜色进行参数化,目前仅支持对参数使用纯色。
  • 阴影:
    • 阴影目前不适用于以下层:
      • 非矩形矢量
      • 旋转矩形矢量
    • 系统不支持为每个图层添加多个阴影。
    • 除“常规”之外的阴影混合模式仅适用于 Android 10 及更高版本(否则会被忽略)。
    • 图层上的阴影仅适用于 Android 9 及更高版本,但文本除外,文本适用于 Compose 支持的所有 Android 版本。
    • 在 Compose 中,阴影将始终显示在透明图层后面。
  • 自动布局中的绝对定位:
    • 绝对定位的对象必须位于框架中所有自动布局元素的后面或前面。位于自动布局元素之间的所有绝对定位的对象都将被推送到这些对象的前面。
    • 如果将嵌套自动布局框架嵌套具有位于其他自动布局框架内部的绝对定位对象,则可能会导致布局不正确,因为嵌套框架的边界框会受到该框架中的已定位项的影响。

传入只有一种样式的文本参数会导致丢失多种样式

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

系统需要通过这种降级来避免因类型不一致而导致所生成的代码无法编译。如果组件中的文本有多种样式,则生成的可组合项将具有一个 AnnotatedText 参数。如果组件中的文本只有一种样式,则生成的可组合项将具有一个纯 String 参数。在上述场景中,我们需要将父组件的富文本从 AnnotatedText 转换为 String,这将丢失多种样式,以便将其传递给嵌套组件实例。

与父组件具有相同变体属性的嵌套组件无法编译

如果两个组件具有具有属性名称相同的 [design variant]{:.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 文件夹中的界面软件包文件夹,然后撤消了删除操作,那么该文件夹内任何未在删除前打开的文件都可能无法正确恢复。

权宜解决方法:依次选择 File > New > Import UI Packages…,重新导入您所需要的 Figma 文件版本。您也可以在导入时点击界面软件包文件夹中的各个文件,以确保文件能正确恢复。

更新 ui-packages 之外的资源不会强制构建新代码

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

权宜解决方法:如需强制更新到生成的代码,请清理项目(依次选择 Build > Clean Project)或删除与需要更新的界面软件包相关联的已生成代码文件夹。然后重新构建。

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

在某些情况下,Relay for Android Studio 插件生成的文件夹不会显示在 Android 项目浏览器中。

权宜解决方法:如需重新加载项目文件夹,请右键点击顶级文件夹,然后选择“从磁盘重新加载”。

子组件的应用主题不会更新

当使用新的应用主题重新导入父组件时,其子组件(在 DEPS.txt 中列出)将不会选择新的主题。

权宜解决方法:从父组件的 config.json 中复制预览主题,并在每个 config.json 中将子组件的预览主题替换为该主题。重新构建后,子组件的已生成代码中的主题将得到修复。

界面软件包名称必须以字母开头

如果界面软件包名称未以字母开头,Relay 将生成无法编译的 Compose 代码,并显示错误消息:The resource name must start with a letter

权宜解决方法:在 Figma 中,重命名界面软件包名称,使其以字母开头。

Compose 中的字体内边距与 Figma 不匹配

Figma 和 Compose 采用不同的方式来布局边界框内的文本。Compose 会沿着边界框顶部添加更多内边距。

权宜解决方法:您需要将 Figma 中的文本位置向上移动几个像素,使其在 Compose 中正确对齐。我们正在努力永久性修复这一问题。