3.5.8.2. 扩展现有主题

平台主题可以在项目中被修改。在修改后的主题中,可以:

  • 改变品牌 Logo 图片。

  • 在可视化组件中添加图标并使用它们。请参阅下面的图标部分。

  • 为可视化组件创建新样式,并在stylename属性中使用它们。这需要一些 CSS 专业知识。

  • 修改可视化组件的现有样式。

  • 修改常用参数,例如背景颜色 、 边距 、间距等。

文件结构和构建脚本




主题在 SCSS 中定义。要修改(扩展)项目中的主题,应该在 web 模块中创建特定的文件结构。



一种便捷的方法是使用 CUBA Studio:在主菜单中,单击 CUBA > Advanced > Manage themes > Create theme extension。在弹出窗口中选择要扩展的主题。另一种方法是使用 CUBA CLI 中的 theme 命令。



最终,以下目录结构将在 modules/web 目录中被创建(对于 Halo 主题扩展):





  1. 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 文件:





  1. 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 文件的第一行,例如:





  1. @import url(http://fonts.googleapis.com/css?family=Roboto);






创建新样式




为显示客户名称的字段设置黄色背景颜色的示例。



在 XML 描述中, 定义了 FieldGroup组件:





  1. <fieldGroup id="fieldGroup" datasource="customerDs">
    <field property="name"/>
    <field property="address"/>
    </fieldGroup>






FieldGroupfield 元素没有stylename属性,因此我们必须在控制器中设置字段的样式名称:





  1. @Named("fieldGroup.name")
    private TextField nameField;

    @Override
    public void init(Map<String, Object> params) {
    nameField.setStyleName("name-field");
    }






halo-ext.scss 文件中,将新样式定义添加到 halo-ext mixin:





  1. @mixin com_company_application-halo-ext {
    .name-field {
    background-color: lightyellow;
    }
    }






重建项目后,字段将如下所示:



gui themes fieldgroup 1



修改可视化组件的现有样式




要修改现有组件的样式参数,请将相应的 CSS 代码添加到 halo-ext.scss 文件的 halo-ext mixin 中。使用 Web 浏览器的开发人员工具查找分配给可视化组件元素的 CSS 类。例如,要以粗体显示应用程序菜单项,halo-ext.scss 文件的内容应如下所示:





  1. @mixin com_company_application-halo-ext {
    .v-menubar-menuitem-caption {
    font-weight: bold;
    }
    }






修改通用参数




主题包含许多控制应用程序背景颜色、组件大小、边距和其它参数的 SCSS 变量。



以下是 Halo 主题扩展的示例,因为它基于来自 VaadinValo 主题,并提供最广泛的自定义选项。



themes/halo/halo-ext-defaults.scss 文件用于覆盖主题变量。大多数 Halo 变量对应于 Valo 文档 中描述的变量。以下是最常见的变量:





  1. $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-sizeh1: 24px; / h1-style Label size /
    $v-font-sizeh2: 20px; / h2-style Label size /
    $v-font-sizeh3: 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





  1. $v-background-color: #444D50;

    $v-font-sizeh1: 22px;
    $v-font-sizeh2: 18px;
    $v-font-sizeh3: 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 版本开始已经移除了。





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