Symfony UX 图标

编辑此页

symfony/ux-icons 软件包提供了在您的 Symfony 应用程序中渲染 SVG 图标的简单直观的方法。它提供了一个 Twig 函数，用于包含来自您模板的任何本地或远程图标。

UX Icons 让您可以直接访问超过 200,000 个来自流行的图标集的矢量图标，例如 FontAwesome、Bootstrap Icons、Tabler Icons、Google Material Design Icons 等。

安装

1
$ composer require symfony/ux-icons

SVG 图标

SVG（可缩放矢量图形）是一种基于 XML 的矢量图像格式，允许分辨率独立的图形，同时保持较小的文件大小。SVG 图标可以嵌入在 HTML 代码中，使用 CSS 进行样式设置，并使用 JavaScript 进行动画处理。

UX Icons 允许您使用来自最流行的图标集的图标，但也让您可以灵活地组合自己的集合，将来自不同集合的图标与您自己的图标混合使用。

图标名称

图标使用唯一的标识符引用，该标识符遵循以下语法之一

  • prefix:name (例如 mdi:check, bi:check, editor:align-left)
  • name 仅 (例如 check, close, menu)

图标 name 与不带文件扩展名的文件名相同 (例如 check.svg -> check)。

注意

名称必须匹配标准的 slug 格式：[a-z0-9-]+(-[0-9a-z])+。

根据您的配置，prefix 可以是图标集的名称、图标所在目录，或两者的组合。

例如，bi 前缀指的是 Bootstrap Icons 集，而 header 前缀指的是位于 header 目录中的图标。

加载图标

1
2
3
4
5
6
7
8
9
10
{# includes the contents of the 'assets/icons/user-profile.svg' file in the template #}
{{ ux_icon('user-profile') }}

{# icons stored in subdirectories must use the 'subdirectory_name:file_name' syntax
   (e.g. this includes 'assets/icons/admin/user-profile.svg') #}
{{ ux_icon('admin:user-profile') }}

{# this downloads the 'user-solid.svg' icon from the 'Flowbite' icon set via ux.symfony.com
   and embeds the downloaded SVG contents in the template #}
{{ ux_icon('flowbite:user-solid') }}

注意

要通过 ux.symfony.com/icons 搜索和下载图标，必须在您的应用程序中安装 symfony/http-client 软件包

1
$ composer require symfony/http-client

ux_icon() 函数定义了第二个可选参数，您可以在其中定义添加到 <svg> 元素的 HTML 属性

1
2
3
4
5
{{ ux_icon('user-profile', {class: 'w-4 h-4'}) }}
{# renders <svg class="w-4 h-4"> ... </svg> #}

{{ ux_icon('user-profile', {height: '16px', width: '16px', 'aria-hidden': true}) }}
{# renders <svg height="16" width="16" aria-hidden="true"> ... </svg> #}

图标集

有许多可用的图标集，每个图标集都有自己独特的风格和图标集，为不同的用途提供了广泛的图标，同时在您的应用程序中保持一致的外观和感觉。以下是一些最流行的可用图标集

图标集 图标 许可证 前缀 示例
Bootstrap 图标 2000 MIT bi bi:check
Boxicons 1700 MIT bx bx:check
Flowbite 1000 MIT flowbite flowbite:check
FontAwesome 图标 7000 CC BY 4.0 fa6-regular fa6-regular:check
Heroicons 300 MIT heroicons heroicons:check
Iconoir 1500 MIT iconoir iconoir:check
Ionicons 1300 MIT ion ion:check
Lucide 图标 1500 MIT lucide lucide:check
Material Design 图标 5000 Apache 2 mdi mdi:check
Octicons 600 MIT octicon octicon:check
Phosphor 图标 7000 MIT ph ph:check
Tabler 图标 5200 MIT tabler tabler:check

要查看可用图标集的完整列表，请访问 ux.symfony.com/icons。

搜索图标集

您可以使用 ux:icons:search 命令来搜索图标集，或查找特定图标集的前缀

1
2
3
4
5
6
7
8
9
10
11
$ php bin/console ux:icons:search tabler

 -------------- ------- --------- -------- --------------
  Icon set       Icons   License   Prefix   Example
 -------------- ------- --------- -------- --------------
  Tabler Icons    5219   MIT       tabler   tabler:alien
 -------------- ------- --------- -------- --------------

Search "arrow" in Tabler Icons icons:

 php bin/console ux:icons:search tabler arrow

搜索图标

您还可以在特定的图标集中搜索图标。要在“Tabler Icons”集中搜索“箭头”图标，请使用以下命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
$ php bin/console ux:icons:search tabler arrow

Searching Tabler Icons icons "arrow"...
Found 64 icons.
 ------------------------------------------ ------------------------------------------
  tabler:archery-arrow                       tabler:arrow-autofit-up
  tabler:arrow-back                          tabler:arrow-back-up
  tabler:arrow-badge-down                    tabler:arrow-badge-up
  tabler:arrow-badge-up-filled               tabler:arrow-bar-both
  tabler:arrow-bar-down                      tabler:arrow-bar-left
  tabler:arrow-bar-right                     tabler:arrow-bar-to-up
  tabler:arrow-bar-up                        tabler:arrow-bear-left
  tabler:arrow-big-down                      tabler:arrow-big-down-filled
  tabler:arrow-big-down-line                 tabler:arrow-big-left
  tabler:arrow-big-left-filled               tabler:arrow-big-left-line
  tabler:arrow-big-right                     tabler:arrow-big-right-filled
  tabler:arrow-big-right-line                tabler:arrow-big-up
 ------------------------------------------ ------------------------------------------

 Page 1/3. Continue? (yes/no) [yes]:
 >

HTML 语法

除了前面章节中解释的 ux_icon() 函数之外，此软件包还支持基于 <twig:ux:icon> 标签的替代 HTML 语法

1
2
3
4
5
6
7
8
9
<!-- renders "user-profile.svg" -->
<twig:ux:icon name="user-profile" class="w-4 h-4" />
<!-- renders "admin/user-profile.svg" -->
<twig:ux:icon name="admin:user-profile" class="w-4 h-4" />
<!-- renders 'user-solid.svg' icon from 'Flowbite' icon set via ux.symfony.com -->
<twig:ux:icon name="flowbite:user-solid" />

<!-- you can also add any HTML attributes -->
<twig:ux:icon name="user-profile" height="16" width="16" aria-hidden="true" />

提示

要使用 HTML 语法，必须在您的项目中安装 symfony/ux-twig-component 软件包。

下载图标

此软件包不包含任何图标，但提供对超过 200,000 个开源图标的访问。

本地 SVG 图标

如果您已经有要在项目中使用的 SVG 图标文件，请将它们存储在 assets/icons/ 目录中并提交它们。文件名用作图标的名称（icon_name.svg 将被命名为 icon_name）。如果位于子目录中，则名称将为 subdirectory:icon_name。

1
2
3
4
5
6
7
8
9
10
11
12
13
your-project/
├─ assets/
│  └─ icons/
│     ├─ bi/
│     │  └─ pause-circle.svg
│     │  └─ play-circle.svg
│     ├─ header/
│     │  ├─ logo.svg
│     │  └─ menu.svg
│     ├─ close.svg
│     ├─ menu.svg
│     └─ ...
└─ ...

按需图标

ux.symfony.com/icons 拥有来自许多不同集合的大量可搜索图标存储库。此软件包提供了一种按需包含在此站点上找到的任何图标的方法

  1. 访问 ux.symfony.com/icons 并搜索您想要使用的图标。找到您喜欢的图标后，复制提供的代码片段之一。
  2. 将代码片段粘贴到您的 Twig 模板中，图标将自动获取（并缓存）。

就这样。这通过使用 Iconify API（ux.symfony.com/icons 是其前端）来获取图标并将其渲染到位。然后，此图标将被缓存，以便将来请求相同的图标。

注意

同名的本地 SVG 图标将优先于按需图标。

导入图标

虽然按需图标在开发期间非常棒，但它们需要 HTTP 请求来获取图标，并且始终使用图标的最新版本。图标将来可能会更改或删除。此外，如果使用许多按需图标，缓存预热过程将花费更长的时间。

这就是为什么此软件包提供了一个命令，用于将开源图标下载到 assets/icons/ 目录中。您可以将导入图标视为锁定它（类似于 composer.lock 如何锁定您的依赖项）

1
2
3
4
5
6
# icon will be saved in `assets/icons/flowbite/user-solid.svg` and you can
# use it with the name: `flowbite:user-solid`
$ php bin/console ux:icons:import flowbite:user-solid

# it's also possible to import several icons at once
$ php bin/console ux:icons:import flowbite:user-solid flowbite:home-solid

注意

导入的图标必须提交到您的存储库。

锁定按需图标

您可以通过运行以下命令来锁定（导入）您在项目中使用的所有按需图标

1
$ php bin/console ux:icons:lock

此命令仅导入本地尚不存在的图标。您可以使用 --force 选项强制报告覆盖现有图标

1
$ php bin/console ux:icons:lock --force

渲染图标

1
2
3
4
5
6
7
8
9
10
{# includes the contents of the 'assets/icons/user-profile.svg' file in the template #}
{{ ux_icon('user-profile') }}

{# icons stored in subdirectories must use the 'subdirectory_name:file_name' syntax
   (e.g. this includes 'assets/icons/admin/user-profile.svg') #}
{{ ux_icon('admin:user-profile') }}

{# this downloads the 'user-solid.svg' icon from the 'Flowbite' icon set via ux.symfony.com
   and embeds the downloaded SVG contents in the template #}
{{ ux_icon('flowbite:user-solid') }}

HTML 语法

1
2
3
4
5
6
7
8
9
10
<twig:ux:icon name="user-profile" />

{# Renders "user-profile.svg" #}
<twig:ux:icon name="user-profile" class="w-4 h-4" />

{# Renders "sub-dir/user-profile.svg" (sub-directory) #}
<twig:ux:icon name="sub-dir:user-profile" class="w-4 h-4" />

{# Renders "flowbite:user-solid" from ux.symfony.com #}
<twig:ux:icon name="flowbite:user-solid" />

注意

使用 HTML 语法需要 symfony/ux-twig-component。

默认属性

您可以在配置中为所有图标设置默认属性。这些属性将添加到所有图标，除非被 ux_icon 函数的第二个参数覆盖。

1
2
3
4
# config/packages/ux_icons.yaml
ux_icons:
    default_icon_attributes:
        fill: currentColor

现在，默认情况下，所有图标的 fill 属性都设置为 currentColor。

1
2
3
4
5
# renders "user-profile.svg" with fill="currentColor"
{{ ux_icon('user-profile') }}

# renders "user-profile.svg" with fill="red"
{{ ux_icon('user-profile', {fill: 'red'}) }}

图标别名

2.20

图标别名功能在 2.20 中添加。

别名是您可以定义的用于引用任何图标的自定义名称。它们对于为您在模板中经常使用的图标创建快捷方式非常有用

1
2
3
4
5
# config/packages/ux_icons.yaml
ux_icons:
    # ...
    aliases:
        dots: 'clarity:ellipsis-horizontal-line'

现在，您可以在模板中使用 dots 别名

1
2
3
4
5
6
7
8
{{ ux_icon('dots') }}
{# with the previous configuration, this is the same as: #}
{{ ux_icon('clarity:ellipsis-horizontal-line') }}

{# using the HTML syntax #}
<twig:ux:icon name="dots" />
{# same as: #}
<twig:ux:icon name="clarity:ellipsis-horizontal-line" />

错误

如果未找到图标，则会抛出异常。这在开发期间很有用，但在生产环境中，您可能希望渲染错误消息。您可以通过将 ignore_not_found 配置选项设置为 true 来做到这一点

1
2
3
# config/packages/ux_icons.yaml
ux_icons:
    ignore_not_found: true

可访问性

图标为您的网站添加视觉元素，它们可能对可访问性构成挑战。根据 W3C 关于 SVG 图标可访问性的指南，根据上下文，有三种方法可以提高图标的可访问性。

信息性图标

它们传达信息或功能。它们应定义一个文本替代方案，通过屏幕阅读器和其他辅助技术使用的 aria-label 属性来呈现相同的内容或功能

1
2
Today's weather:
{{ ux_icon('cloud-rain', {'aria-label': 'Rainy weather'}) }}
功能性图标

它们是交互式的并执行功能。它们应定义一个文本替代方案，通过屏幕阅读器和其他辅助技术使用的 aria-label 属性来呈现相同的内容或功能

1
{{ ux_icon('user-profile', {class: 'w-4 h-4', 'aria-label': 'User Profile'}) }}
装饰性图标

它们纯粹是装饰性的，不传达任何含义或功能。应使用 aria-hidden 属性将它们从屏幕阅读器中隐藏起来。

1
2
3
4
5
6
<a href="/profile">
    <svg viewBox="0 0 24 24" class="w-4 h-4" aria-hidden="true">
        <!-- ... -->
    </svg>
    Back to profile
</a>

这就是为什么 ux_icon() 函数和 <twig:ux:icon> 组件自动将 aria-hidden="true" 属性添加到未至少具有以下属性之一的图标：aria-label、aria-labelledby 或 title。

注意

如果您不想为特定图标设置 aria-hidden="true"，您可以显式地将 aria-hidden 属性设置为 false

1
<twig:ux:icon name="user-profile" aria-hidden="false" />

性能

UX Icons 组件旨在快速运行。以下是一些为确保最佳性能而进行的优化。

缓存

按需 VS 导入

虽然按需图标在开发期间非常棒，但它们需要 HTTP 请求来获取图标，并且始终使用图标的最新版本。图标将来可能会更改或删除。此外，如果使用许多_按需_图标，缓存预热过程将花费更长的时间。您可以将导入图标视为锁定它（类似于 composer.lock _锁定_您的依赖项）。

图标缓存

为了避免在每次请求时都必须解析图标文件，图标会被缓存。在生产环境中，您可以通过运行以下命令来预热缓存

1
$ php bin/console ux:icons:warm-cache

此命令在您的所有 Twig 模板中查找 ux_icon() 调用和 <twig:ux:icon> 标签，并缓存它找到的图标。

注意

名称动态构建的图标将不会被缓存。建议在您的模板中将图标名称作为字符串文字。

1
2
3
4
5
6
7
8
9
{# This will be cached #}
{{ ux_icon('flag-fr') }}

{# This will NOT be cached #}
{{ ux_icon('flag-' ~ locale) }}

{# in this example, both "flag-fr" and "flag-de" will be cached #}
{% set flags = {fr: 'flag-fr', de: 'flag-de'} %}
{{ ux_icon(flags[locale]) }}

注意

在开发期间，如果您修改了图标，您需要清除缓存 (bin/console cache:clear) 才能看到更改。

提示

如果使用 symfony/asset-mapper，则在运行 asset-map:compile 时会自动预热缓存。

TwigComponent

ux_icon() 函数经过优化，尽可能快。为了在使用 HTML 语法 (<twig:ux:icon name="..." />) 时提供相同的性能水平，通过立即调用 IconRenderer 并返回 HTML 输出，减少了 TwigComponent 的开销。

警告

<twig:ux:icon> 组件不支持嵌入内容。

1
2
3
4
5
6
7
{# The 🧸 will be ignored in the HTML output #}
<twig:ux:icon name="user-profile" class="w-4 h-4">🧸</twig:ux:icon>

{# Renders "user-profile.svg" #}
<svg viewBox="0 0 24 24" class="w-4 h-4">
    <path fill="currentColor" d="M21 7L9 19l-5.5-5.5l1.41-1.41L9 16.17L19.59 5.59z"/>
</svg>

配置

UX Icons 无缝集成到 Symfony 应用程序中。所有这些选项都在您的应用程序配置中的 ux_icons 键下配置。

1
2
3
# config/packages/ux_icons.yaml
ux_icons:
    {# ... #}

调试配置

1
2
3
4
5
# Displays the default config values
$ php bin/console config:dump-reference ux_icons

# Displays the actual config values used by your application
$ php bin/console debug:config ux_icons

完整配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# config/packages/ux_icons.yaml
ux_icons:
    # The local directory where icons are stored
    icon_dir: '%kernel.project_dir%/assets/icons'

    # Default attributes to add to all icons
    default_icon_attributes:
        fill: currentColor
        'font-size': '1.25em'

    # Icon aliases (alias => icon name)
    aliases:
        dots: 'clarity:ellipsis-horizontal-line'
        'tabler:save': 'tabler:device-floppy'

    # Configuration for the "on demand" icons powered by Iconify.design
    iconify:
       enabled: true

       # Whether to use the "on demand" icons powered by Iconify.design
       on_demand: true

       # The endpoint for the Iconify API
       endpoint: 'https://api.iconify.design'

    # Whether to ignore errors when an icon is not found
    ignore_not_found: false

了解更多

这项工作，包括代码示例，根据 Creative Commons BY-SA 3.0 许可获得许可。
目录
    版本