3.5.8.2. 扩展现有主题
平台主题可以在项目中被修改。在修改后的主题中,可以:
改变品牌 Logo 图片。
在可视化组件中添加图标并使用它们。请参阅下面的图标部分。
为可视化组件创建新样式,并在stylename属性中使用它们。这需要一些 CSS 专业知识。
修改可视化组件的现有样式。
修改常用参数,例如背景颜色 、 边距 、间距等。
- 文件结构和构建脚本
主题在 SCSS 中定义。要修改(扩展)项目中的主题,应该在 web 模块中创建特定的文件结构。
一种便捷的方法是使用 CUBA Studio:在主菜单中,单击 CUBA > Advanced > Manage themes > Create theme extension。在弹出窗口中选择要扩展的主题。另一种方法是使用 CUBA CLI 中的theme
命令。
最终,以下目录结构将在modules/web
目录中被创建(对于 Halo 主题扩展):themes/
halo/
branding/
app-icon-login.png
app-icon-menu.png
com.company.application/
app-component.scss
halo-ext.scss
halo-ext-defaults.scss
favicon.ico
styles.scss
除此之外,build.gradle脚本将会添加进buildScssThemes
任务,该任务在每次构建 web 模块时自动执行。可选的deployThemes任务可用于将主题中的更改快速应用于正在运行的应用程序。
如果项目包含带有扩展主题的应用程序组件,并且希望此扩展用于整个项目,那么也应该为项目创建主题扩展。有关如何继承组件主题的详细信息,请参阅使用应用程序组件中的主题部分。
- 更改品牌
可以配置一些品牌相关的属性,例如图标、登录和主应用程序窗口标题以及网站图标(favicon.ico
)。
要使用自定义图片,请替换modules/web/themes/halo/branding
目录中的默认图片。
要设置窗口标题和登录窗口欢迎文本,请在 web 模块的主消息包中设置窗口标题和登录窗口欢迎文本(即modules/web/<root_package>/web/messages.properties
文件及其针对不同语言环境的变体)。消息包允许为不同的用户区域设置使用不同的图像文件。示例messages.properties
文件:application.caption = MyApp
application.logoImage = branding/myapp-menu.png
loginWindow.caption = MyApp Login
loginWindow.welcomeLabel = Welcome to MyApp!
loginWindow.logoImage = branding/myapp-login.png
favicon.ico
的路径没有被指定,因为它必须位于主题的根目录中。
- 添加字体
可以为 Web 主题添加自定义字体。添加一个 Font Family,将其导入styles.scss
文件的第一行,例如:@import url(http://fonts.googleapis.com/css?family=Roboto);
- 创建新样式
为显示客户名称的字段设置黄色背景颜色的示例。
在 XML 描述中, 定义了 FieldGroup组件:<fieldGroup id="fieldGroup" datasource="customerDs">
<field property="name"/>
<field property="address"/>
</fieldGroup>
FieldGroup
的field
元素没有stylename属性,因此我们必须在控制器中设置字段的样式名称:@Named("fieldGroup.name")
private TextField nameField;
@Override
public void init(Map<String, Object> params) {
nameField.setStyleName("name-field");
}
在halo-ext.scss
文件中,将新样式定义添加到halo-ext
mixin:@mixin com_company_application-halo-ext {
.name-field {
background-color: lightyellow;
}
}
重建项目后,字段将如下所示:
- 修改可视化组件的现有样式
要修改现有组件的样式参数,请将相应的 CSS 代码添加到halo-ext.scss
文件的halo-ext
mixin 中。使用 Web 浏览器的开发人员工具查找分配给可视化组件元素的 CSS 类。例如,要以粗体显示应用程序菜单项,halo-ext.scss
文件的内容应如下所示:@mixin com_company_application-halo-ext {
.v-menubar-menuitem-caption {
font-weight: bold;
}
}
- 修改通用参数
主题包含许多控制应用程序背景颜色、组件大小、边距和其它参数的 SCSS 变量。
以下是 Halo 主题扩展的示例,因为它基于来自 Vaadin 的 Valo 主题,并提供最广泛的自定义选项。themes/halo/halo-ext-defaults.scss
文件用于覆盖主题变量。大多数 Halo 变量对应于 Valo 文档 中描述的变量。以下是最常见的变量:$v-background-color: #fafafa; / component background colour /
$v-app-background-color: #e7ebf2; / application background colour /
$v-panel-background-color: #fff; / panel background colour /
$v-focus-color: #3b5998; / focused element colour /
$v-error-indicator-color: #ed473b; / empty required fields colour /
$v-line-height: 1.35; / line height /
$v-font-size: 14px; / font size /
$v-font-weight: 400; / font weight /
$v-unit-size: 30px; / base theme size, defines the height for buttons, fields and other elements /
$v-font-size—h1: 24px; / h1-style Label size /
$v-font-size—h2: 20px; / h2-style Label size /
$v-font-size—h3: 16px; / h3-style Label size /
/ margins for containers /
$v-layout-margin-top: 10px;
$v-layout-margin-left: 10px;
$v-layout-margin-right: 10px;
$v-layout-margin-bottom: 10px;
/ spacing between components in a container (if enabled) /
$v-layout-spacing-vertical: 10px;
$v-layout-spacing-horizontal: 10px;
/ whether filter search button should have "friendly" style/
$cuba-filter-friendly-search-button: true;
/ whether button that has primary action or marked as primary itself should be highlighted/
$cuba-highlight-primary-action: false;
/ basic table and datagrid settings /
$v-table-row-height: 30px;
$v-table-header-font-size: 13px;
$v-table-cell-padding-horizontal: 7px;
$v-grid-row-height
$v-grid-row-selected-background-color
$v-grid-cell-padding-horizontal
/ input field focus style /
$v-focus-style: inset 0px 0px 5px 1px rgba($v-focus-color, 0.5);
/ required fields focus style /
$v-error-focus-style: inset 0px 0px 5px 1px rgba($v-error-indicator-color, 0.5);
/ animation for elements is enabled by default /
$v-animations-enabled: true;
/ popup window animation is disabled by default /
$v-window-animations-enabled: false;
/ inverse header is controlled by cuba.web.useInverseHeader property /
$v-support-inverse-menu: true;
/ show "required" indicators for components /
$v-show-required-indicators: false !default;
下面提供了具有深色背景和略微减少外边距的示例主题halo-ext-defaults.scss
:$v-background-color: #444D50;
$v-font-size—h1: 22px;
$v-font-size—h2: 18px;
$v-font-size—h3: 16px;
$v-layout-margin-top: 8px;
$v-layout-margin-left: 8px;
$v-layout-margin-right: 8px;
$v-layout-margin-bottom: 8px;
$v-layout-spacing-vertical: 8px;
$v-layout-spacing-horizontal: 8px;
$v-table-row-height: 25px;
$v-table-header-font-size: 13px;
$v-table-cell-padding-horizontal: 5px;
$v-support-inverse-menu: false;
另外一个示例展示了使用一组变量使得 Halo 主题看上去跟旧的 Havana 主题差不多,Havana 主题从框架 7.0 版本开始已经移除了。$cuba-menubar-background-color: #315379;
$cuba-menubar-border-color: #315379;
$v-table-row-height: 25px;
$v-selection-color: rgb(77, 122, 178);
$v-table-header-font-size: 12px;
$v-textfield-border: 1px solid #A5C4E0;
$v-selection-item-selection-color: #4D7AB2;
$v-app-background-color: #E3EAF1;
$v-font-size: 12px;
$v-font-weight: 400;
$v-unit-size: 25px;
$v-border-radius: 0px;
$v-border: 1px solid #9BB3D3 !default;
$v-font-family: Verdana,tahoma,arial,geneva,helvetica,sans-serif,"Trebuchet MS";
$v-panel-background-color: #ffffff;
$v-background-color: #ffffff;
$cuba-menubar-menuitem-text-color: #ffffff;
$cuba-app-menubar-padding-top: 8px;
$cuba-app-menubar-padding-bottom: 8px;
$cuba-menubar-text-color: #ffffff;
$cuba-menubar-submenu-padding: 1px;
- 更改应用程序标题
Halo 主题支持cuba.web.useInverseHeader属性,该属性控制应用程序标题的颜色。默认情况下,此属性设置为true
,它设置一个暗色(高对比)标题。只需将此属性设置为false
,即可不需要对主题进行任何更改而创建一个亮色标题。