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