GSS 迁移指南

摘要

随着 GWT 2.8 Css 在 CssResource 中被弃用,取而代之的是 GSS,强烈建议应用程序迁移到 GSS。

为了帮助 GWT 2.8 的采用,CssResource 的默认值仍然是 CSS。在应用程序迁移到 2.8 之后,可以分多个步骤过渡到 GSS。

GSS 开源 项目概述了 GSS 的功能,这里有一个 CSS 和 GSS 之间的差异列表

本文档概述了从 CSS 迁移到 GSS 所需的步骤。

小型应用程序希望使用一次性迁移,而大型应用程序可能希望使用逐步迁移路径。

配置属性

启用 GSS

启用 GSS 将告诉 GWT 编译器为所有 CssResource 接口使用 GSS。此标志可以是 ?false?(默认值)或 ?true?。

<set-configuration-property name="CssResource.enableGss" value="true" />

启用自动转换

如果启用了 GSS,并且 GWT 编译器找到了一个 .css 文件,它将首先将此文件转换为 gss,然后将其动态馈送到 GSS。

<set-configuration-property name="CssResource.conversionMode" value="strict" />

自动转换模式

自动转换有三种模式

  • 严格 - 在严格模式下,CSS 中的任何错误都会导致编译失败。这是您应该使用的模式
  • 宽松 - 有时您无法一次修复应用程序的所有 CSS,我们添加了一个宽松模式,它会尝试将 CSS 转换为有效的格式。当然,这很容易出错,您应该使用严格模式。
  • 关闭 - 在将所有 CSS 转换为 GSS 之后,您可以关闭自动转换。

GSS 在 GWT 中的测试情况如何

自 2015 年年中以来,Google 的所有应用程序都使用 GSS 代替 CSS。

先决条件

  • 您不能在同一个方法(@Source 注释)中混合使用 css 和 gss。这将是无效的:
// Invalid use since css and gss are mixed one method
@Source({"def.css", "converted.gss"})
MyCssResource css();
  • 对于 SDK 中的基本类型,每个 css 文件都有一个 gss 等效文件。

逐步迁移

  1. 在应用程序的某个子目录上运行转换工具,这将为每个 .css 文件创建一个 .gss 文件。
  2. 将 ClientBundle 上的所有扩展名更改为 .gss 以使用新文件。
  3. 验证应用程序的这一部分没有视觉上的问题
  4. 提交您的更改
  5. 继续,直到所有内容都更改完成
  6. 验证整个应用程序是否正常工作,并且不再使用 CSS 解析器,关闭自动转换
<set-configuration-property name="CssResource.conversionMode" value="off" />
  1. 删除所有 .css
  2. 在 CSS3 世界里幸福地生活

一步迁移

  1. 在应用程序的主目录上运行转换工具,这将为每个 .css 文件创建一个 .gss 文件。
  2. 将 ClientBundle 上的所有扩展名更改为 .gss 以使用新文件
  3. 删除所有 .css 文件
  4. 验证您的应用程序
  5. 提交您的代码更改
  6. 关闭应用程序的自动转换
<set-configuration-property name="CssResource.conversionMode" value="off" />
  1. 在 CSS3 世界里幸福地生活

UiBinder

由于 UiBinder 没有文件扩展名的概念,因此我们扩展了 UiBinder 以允许在 style 标签上添加一个额外的属性。要在 UiBinder 中使用 GSS,您必须添加 gss=?true?

<ui:style gss="true" >
  /* In here you can now use GSS */
</ui:style>

注意:与 CssResource 一样,这里不能混合使用 css 和 gss。如果您在 UiBinder 文件中导入 .gss 文件,您需要启用 gss,并在 style 元素中编写 Gss

<ui:style gss="true" src="foo.gss">
  /* Need to use GSS here now! */
</ui:style>
/* This is invalid! */
<ui:style gss="true" src="foo.css">
</ui:style>

在 UiBinder 中设置默认值

您还可以通过设置配置属性来控制所有 UiBinder 字段的 CSS/GSS 默认值

<set-configuration-property name="CssResource.gssDefaultInUiBinder" value="true" />

注意:这仅适用于给定 style 元素上没有 gss 属性的情况。

Css 转换工具 - Css2Gss

Css 转换工具 Css2Gss 允许您自动将 css 文件转换为 gss。GWT 编译器使用相同的底层工具动态将 css 转换为 gss。

注意:Css2Gss 仅支持转换中的严格模式,并且无法转换无效的 css 文件。我们无法在所有情况下准确地转换损坏的 css,因此我们宁愿根本不尝试转换。

您可以像这样运行该工具

$ java -cp gwt-user.jar com.google.gwt.resources.converter.Css2Gss
fileToConvert.css

已知的转换工具问题

注释已删除

由于旧的长笛 css 解析器无法让我们访问这些注释,因此我们对此无能为力。您需要根据需要手动重新添加注释。

依赖于其他文件的 @def?s 会导致转换失败

由于转换器需要将所有变量转换为 GSS 兼容格式,因此它需要了解作用域内定义的所有变量。因此,如果遇到未定义的变量,它会拒绝转换。

为了解决此限制,转换器允许您指定一个 css 文件列表,用于解析以建立作用域

$ java -cp gwt-user.jar com.google.gwt.resources.converter.Css2Gss -scope
foo.css,bar.css fileToConvert.css

已知的 GSS 问题

在怪癖模式下运行您的 gwt 主机页面

在怪癖模式下运行主机页面会导致 GSS 失败。如果浏览器在怪癖模式下运行,它们会将 .a 和 .A 视为相同的选择器。GSS 使用大小写不同的字符来区分不同的类,由于这一点,您会在怪癖模式下看到冲突。由于在很长一段时间内,在怪癖模式下运行 GWT 应用程序都是非法的,因此您需要通过在主机页面中添加 <!doctype html> 来将应用程序迁移到“HTML 5”。