添加自定义图标

自定义图标以独立 SVG 文件、SVG 精灵图（Sprite）或图标字体的形式添加。

选择格式

格式 最适合 特点

独立 SVG 文件

少量自定义图标

每个图标存储在单独的文件中。浏览器只加载 UI 中使用的图标。

SVG 精灵图

一组自定义图标

多个图标作为符号存储在一个文件中，并通过标识符选择。

图标字体

已有的基于字体的图标库

需要字体文件和 CSS 配置。图标通过 CSS 类、连字或字符代码选择。

有关使用属性、XML 元素或 Java 配置图标的信息，请参见 使用图标。

独立 SVG 文件

SVG 文件可以添加到静态内容目录中。默认情况下，Spring Boot 从类路径中的以下位置提供静态资源：/static、/public、/resources 或 /META-INF/resources。为了组织图标，可以使用子文件夹，例如 META-INF/resources/icons。

如需显示 SVG 文件，请使用 svgIcon 组件：

<svgIcon resource="/icons/tree.svg"/>

也可以通过编程方式创建 SVG 图标：

SvgIcon treeIcon = new SvgIcon();
treeIcon.setSrc(DownloadHandler.forClassResource(
        getClass(),
        "/META-INF/resources/icons/tree.svg",
        "tree.svg"
));
standaloneIconButton.setIcon(treeIcon);

SVG 精灵图

一个 SVG 精灵图是一组图像，作为符号存储在单个 SVG 文件中。每个符号都有一个标识符，用于选择相应的图标。

添加 SVG 精灵图：

  1. 在 /frontend/icons/ 目录中为图标集创建一个 JavaScript 文件。以下代码定义了一个包含三个图标的 sprite：

    my-icons.js
    import '@vaadin/icon/vaadin-iconset.js';

const template = document.createElement('template');

template.innerHTML = `<vaadin-iconset name="my-icons" size="24">
  <svg><defs>
    <g id="star"><path d="M12 .587l3.668 7.568 8.332 1.207-6 5.848 1.416 8.263L12 18.896l-7.416 3.895L6 14.162l-6-5.848 8.332-1.207z" fill="#FFD700"/></g>
    <g id="heart"><path d="M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z" fill="#FF69B4"/></g>
    <g id="circle"><circle cx="12" cy="12" r="10" fill="#1E90FF"/></g>
  </defs></svg>
</vaadin-iconset>`;

document.head.appendChild(template.content);

  2. 创建一个 Java 枚举，实现 IconFactory，并添加 @JsModule 注解，引用那个 JavaScript 文件：

    MyIcons.java
    package com.company.onboarding.icons;

import com.vaadin.flow.component.dependency.JsModule;
import com.vaadin.flow.component.icon.Icon;
import com.vaadin.flow.component.icon.IconFactory;
import java.util.Locale;

@JsModule("./icons/my-icons.js")
public enum MyIcons implements IconFactory {
    STAR,
    HEART,
    CIRCLE;

    public Icon create() {
        return new Icon("my-icons",
                name().toLowerCase(Locale.ENGLISH).replace('_', '-'));
    }
}

图标集注册后，通过图标集名称和符号标识符使用图标：

<icon icon="my-icons:star"/>
<icon icon="my-icons:heart"/>
<icon icon="my-icons:circle"/>
sprite icons

或通过编程方式创建图标：

spriteIconButton.setIcon(MyIcons.STAR.create());

图标字体

图标字体是一组以字体形式提供的图标。图标被渲染为该字体中的字符。

添加自定义图标字体后，可以用自定义图标覆盖默认的图标。详情请参见 覆盖默认图标。

添加图标字体时，需要以下内容：

  • 一个或多个字体文件 - 通常是 .woff2，其他格式如 .woff、.ttf 或 .otf。

  • 全局 @font-face 声明 - 通常放在一个需要导入到主样式表（styles.css）的样式表中。

  • 可选地，包含图标 CSS 类的样式表 - 通常与 @font-face 声明一起添加，并同样导入到 styles.css 中。

添加 Material Icons 字体

此示例展示如何将 Material Icons 字体添加到的 应用程序主题 中。

使用本地字体文件

要在不使用外部服务的情况下使用 Material Icons，请在激活的 应用主题 目录中创建一个 material 子目录。

添加以下文件：

  • material-icons.woff2

  • material-icons.woff

  • material-icons.ttf

  • material-icons.css – 包含 @font-face 声明和图标的 CSS 类：

    material-icons.css
    @font-face {
  font-family: "Material Icons";
  font-style: normal;
  font-weight: 400;
  font-display: block;
  src:
    url("./material-icons.woff2") format("woff2"),
    url("./material-icons.woff") format("woff"),
    url("./material-icons.ttf") format("truetype");
}
.material-icons {
  font-family: "Material Icons";
  font-weight: normal;
  font-style: normal;
  font-size: 24px;
  line-height: 1;
  letter-spacing: normal;
  text-transform: none;
  display: inline-block;
  white-space: nowrap;
  word-wrap: normal;
  direction: ltr;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-rendering: optimizeLegibility;
  font-feature-settings: "liga";
}

浏览器会使用它支持的第一种字体格式。因此，src 中声明的每个字体文件都必须下载并放在 material-icons.css 同级目录。

将样式表导入到主题的主样式表中：

styles.css
@import url('material/material-icons.css');

使用 Google Fonts

还可以从 Google Fonts 在线加载 Material Icons，而不是将字体文件存储在本地。此选项要求用户的浏览器能够通过网络访问 Google Fonts。

从主题的 styles.css 中移除对 material/material-icons.css 的导入，改为添加以下导入：

styles.css
@import url("https://fonts.googleapis.com/css2?family=Material+Icons&display=swap");

导入的 Google Fonts 样式表提供了 Material Icons 的 @font-face 声明和 CSS 类，因此不需要本地字体文件或额外的 @font-face 声明。

使用字体图标

使用任何方式配置字体后，使用 fontIcon 组件创建图标。

根据字体及其样式表的不同，fontIcon 组件可以通过两种方式识别图标：

  • 连字，例如 calendar，通过 ligature 属性设置。这需要支持连字的字体。

  • 十六进制字符代码，例如 f199，通过 charCode 属性设置。

    示例：

    <fontIcon fontFamily="Material Icons" ligature="search"/>
<fontIcon fontFamily="Material Icons" charCode="e8b6"/>