扩展现有主题 - CUBA 框架开发者手册

3.5.9.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，即可不需要对主题进行任何更改而创建一个亮色标题。