图标 Icon

icon 概览

mat-icon 让你在应用中使用矢量图标变得更容易。 该指令支持字体图标和 SVG 图标,但不支持位图格式(png、jpg 等)。

mat-icon makes it easier to use vector-based icons in your app. This directive supports both icon fonts and SVG icons, but not bitmap-based formats (png, jpg, etc.).

Basic icons
home

MatIconRegistry 是一个可注入的服务,它允许你把图标名称和 SVG 的 URL、HTML 字符串 关联起来,还可以为 CSS 字体类定义别名。 具体方式稍后会进行讨论,并列在 API 摘要中。

MatIconRegistry is an injectable service that allows you to associate icon names with SVG URLs, HTML strings and to define aliases for CSS font classes. Its methods are discussed below and listed in the API summary.

有些字体是设计来用合字的方式显示图标的,比如把文本格式的 "home" 显示为家的图标。要使用合字图标,请把它对应的文本放进 mat-icon 组件的内容中。

Some fonts are designed to show icons by using ligatures, for example by rendering the text "home" as a home image. To use a ligature icon, put its text in the content of the mat-icon component.

默认情况下,<mat-icon> 需要 Material 字体图标。 (你可能还要在 HTML 中加载该字体及其 CSS 文件,像链接中所描述的那样)。 你可以将输入属性 fontSet 设置为要应用的 CSS 所依赖的字体,也可以设置为以前通过 MatIconRegistry.registerFontClassAlias 注册的某个别名。

By default, <mat-icon> expects the Material icons font. (You will still need to include the HTML to load the font and its CSS, as described in the link). You can specify a different font by setting the fontSet input to either the CSS class to apply to use the desired font, or to an alias previously registered with MatIconRegistry.registerFontClassAlias.

字体还可以通过为每个图标字符定义 CSS 类来显示图标,它通常使用 :before 选择器来显示图标。 FontAwesome 就是通过这种方式显示图标的。 要使用这类字体,请把输入属性 fontSet 设置为该字体的 CSS 类(或者它本身的定义类或者通过 MatIconRegistry.registerFontClassAlias 注册的别名),并且把输入属性 fontIcon 设置为要显示的图标的专有类。

Fonts can also display icons by defining a CSS class for each icon glyph, which typically uses a :before selector to cause the icon to appear. FontAwesome uses this approach to display its icons. To use such a font, set the fontSet input to the font's CSS class (either the class itself or an alias registered with MatIconRegistry.registerFontClassAlias), and set the fontIcon input to the class for the specific icon to show.

无论对于哪种字体图标,你都可以通过调用 MatIconRegistry.setDefaultFontSetClass 来指定一个默认字体类。当没有指定 fontSet 时就会使用它。

For both types of font icons, you can specify the default font class to use when fontSet is not explicitly set by calling MatIconRegistry.setDefaultFontSetClass.

<mat-icon> 会把 SVG 内容直接内联到 DOM 中,作为自己的子级,来显示 SVG 图标。这种方法比 <img> 标签或 CSS background-image 更有优势,因为它允许使用 CSS 来为 SVG 指定样式。例如,SVG 内容的默认颜色是 CSS 的 currentColor 值。这会使 SVG 图标默认使用与周围文本相同的颜色,并让你能通过设置 mat-icon 元素 color 样式来改变其颜色。

<mat-icon> displays SVG icons by directly inlining the SVG content into the DOM as a child of itself. This approach offers an advantage over an <img> tag or a CSS background-image because it allows styling the SVG with CSS. For example, the default color of the SVG content is the CSS currentColor value. This makes SVG icons by default have the same color as surrounding text, and allows you to change the color by setting the color style on the mat-icon element.

为了防范 XSS 漏洞,传给 MatIconRegistry 的 SVG URL 和 HTML 字符串都必须使用 Angular 的 DomSanitizer 服务标记为可信的。

In order to guard against XSS vulnerabilities, any SVG URLs and HTML strings passed to the MatIconRegistry must be marked as trusted by using Angular's DomSanitizer service.

MatIconRegistry 通过 Angular 的 HttpClient 服务获取所有的远程 SVG 图标。如果你没有在 NgModuleimports 里包含 @angular/common/http 包里 HttpClientModule,那么运行时就会出错。

MatIconRegistry fetches all remote SVG icons via Angular's HttpClient service. If you haven't included HttpClientModule from the @angular/common/http package in your NgModule imports, you will get an error at runtime.

注意,HttpClient 要借助 XmlHttpRequest 来获取通过 URL 注册的 SVG 图标,它必须遵循同源策略。这意味着图标的 URL 必须与容器页面具有相同的源,或者必须将该应用服务器配置为允许跨域请求。

Note that HttpClient fetches SVG icons registered with a URL via XmlHttpRequest, subject to the Same-origin policy. This means that icon URLs must have the same origin as the containing page or that the application's server must be configured to allow cross-origin requests.

要把一个名字和图标的 URL 关联起来,请使用 MatIconRegistryaddSvgIconaddSvgIconInNamespaceaddSvgIconLiteraladdSvgIconLiteralInNamespace 方法。 在注册了图标之后,它可以通过设置输入属性 svgIcon 进行显示。 对于默认命名空间中的图标,可以直接使用其名字。对于非默认命名空间,可以使用 [namespace]:[name] 格式。

To associate a name with an icon URL, use the addSvgIcon, addSvgIconInNamespace, addSvgIconLiteral or addSvgIconLiteralInNamespace methods of MatIconRegistry. After registering an icon, it can be displayed by setting the svgIcon input. For an icon in the default namespace, use the name directly. For a non-default namespace, use the format [namespace]:[name].

图标集允许把多个图标分组到一个单一的 SVG 文件中。它可以通过创建一个单根 <svg> 标记来完成,该标记在其 <defs> 部分包含多个内嵌的 <svg> 标记。 每个内嵌标记都带有一个 id 属性,该属性就会用作图标的名字。

Icon sets allow grouping multiple icons into a single SVG file. This is done by creating a single root <svg> tag that contains multiple nested <svg> tags in its <defs> section. Each of these nested tags is identified with an id attribute. This id is used as the name of the icon.

图标集使用 MatIconRegistryaddSvgIconSetaddSvgIconSetInNamespaceaddSvgIconSetLiteraladdSvgIconSetLiteralInNamespace 方法进行注册。 当注册了图标集之后,每个内嵌的图标都可以通过它们的 id 属性进行访问。要显示图标集中的某个图标, 只要像单独注册的图标那样使用输入属性 svgIcon 就可以了。

Icon sets are registered using the addSvgIconSet, addSvgIconSetInNamespace, addSvgIconSetLiteral or addSvgIconSetLiteralInNamespace methods of MatIconRegistry. After an icon set is registered, each of its embedded icons can be accessed by their id attributes. To display an icon from an icon set, use the svgIcon input in the same way as for individually registered icons.

多个图标集可以注册进同一个命名空间。如果一个图标的 id 出现在多个图标集中,就会使用最近注册的图标集中的图标。

Multiple icon sets can be registered in the same namespace. Requesting an icon whose id appears in more than one icon set, the icon from the most recently registered set will be used.

默认情况下,图标会使用当前字体颜色(currentColor)。该颜色可以使用 color 属性设置为当前主题中的颜色。 它可以修改为 'primary''accent''warn' 之一。

By default, icons will use the current font color (currentColor). this color can be changed to match the current theme's colors using the color attribute. This can be changed to 'primary', 'accent', or 'warn'.

像任何 <img> 元素一样,图标本身并不会想屏幕阅读器用户传达任何有用的信息。 <mat-icon> 的使用者必须提供一些关于本图标用途的额外信息。根据稍后描述的用例,mat-icon 默认标记为 aria-hidden="true",但是可以通过网元素上添加 aria-hidden="false" 来覆盖默认行为。

Similar to an <img> element, an icon alone does not convey any useful information for a screen-reader user. The user of <mat-icon> must provide additional information pertaining to how the icon is used. Based on the use-cases described below, mat-icon is marked as aria-hidden="true" by default, but this can be overridden by adding aria-hidden="false" to the element.

在考察无障碍性时,可以将图标归入下面三种类别之一:

In thinking about accessibility, it is useful to place icon use into one of three categories:

  1. 装饰性的:该图标不传达有意义的信息,是个纯粹的点缀。

    Decorative: the icon conveys no real semantic meaning and is purely cosmetic.

  2. 交互式的:用户会点击它或用其它方式与此图标互动以执行某些操作。

    Interactive: a user will click or otherwise interact with the icon to perform some action.

  3. 指示符:该图标不是交互式的,但传达某些信息,比如状态。这种情况也包括在大型消息的文本中使用图标。

    Indicator: the icon is not interactive, but it conveys some information, such as a status. This includes using the icon in place of text inside of a larger message.

当该图标纯粹是点缀,并且没有传达有意义的信息时,<mat-icon> 元素要标记为 aria-hidden="true"

When the icon is purely cosmetic and conveys no real semantic meaning, the <mat-icon> element is marked with aria-hidden="true".

图标本身对屏幕阅读器用户不是交互式元素。当用户要和页面中的某个图标交互时,应该让更合适的元素来负责交互:

Icons alone are not interactive elements for screen-reader users; when the user would interact with some icon on the page, a more appropriate element should "own" the interaction:

  • <mat-icon> 元素应该是 <button><a> 元素之一。

    The <mat-icon> element should be a child of a <button> or <a> element.

  • 父元素 <button><a> 应该通过文本内容、aria-labelaria-labelledby 提供一个有意义的标签。

    The parent <button> or <a> should either have a meaningful label provided either through direct text content, aria-label, or aria-labelledby.

如果某个图标的存在是为了给用户传达一些信息,那么无论它是作为指示符还是内联到文本块中,该信息都必须可以供屏幕阅读器使用。最直接的实现方式有:

When the presence of an icon communicates some information to the user whether as an indicator or by being inlined into a block of text, that information must also be made available to screen-readers. The most straightforward way to do this is to

  1. <mat-icon> 元素添加一个相邻的兄弟 <span>,用它传达与图标相同的信息。

    Add a <span> as an adjacent sibling to the <mat-icon> element with text that conveys the same information as the icon.

  2. <span> 添加一个 cdk-visually-hidden 类,这会导致在屏幕上看不见该信息,但屏幕阅读器用户仍然可以读取它。

    Add the cdk-visually-hidden class to the <span>. This will make the message invisible on-screen but still available to screen-reader users.

默认情况下,在 RTL 布局下的图标和 LTR 布局下是完全一样的,不过某些图标必须为 RTL 用户进行镜像处理。 如果你只想在 RTL 布局下镜像某个图标,可以使用 mat-icon-rtl-mirror 类。

By default icons in an RTL layout will look exactly the same as in LTR, however certain icons have to be mirrored for RTL users. If you want to mirror an icon only in an RTL layout, you can use the mat-icon-rtl-mirror CSS class.

<mat-icon class="mat-icon-rtl-mirror" svgIcon="thumb-up"></mat-icon>