ux-icons

UX Icons

在 Twig 模板中渲染本地和远程 SVG 图标。图标可以来自本地文件、Iconify.design（200 多个图标集，200,000 多个图标）或自定义图标集。图标会以内联 <svg> 元素的形式呈现——无需图标字体，运行时也不会发出外部请求。

安装

composer require symfony/ux-icons

快速参考

ux_icon('name')                        Twig function
ux_icon('name', {class: 'w-4 h-4'})   with HTML attributes
<twig:ux:icon name="name" />           Twig component (requires ux-twig-component)
<twig:ux:icon name="set:name" />       icon from a specific set

渲染图标

Twig 函数

{{ ux_icon('menu') }}
{# renders <svg ...>...</svg> #}

{{ 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> #}

Twig 组件（HTML 语法）

需要 symfony/ux-twig-component。

<twig:ux:icon name="user-profile" class="w-4 h-4" />

<twig:ux:icon name="flowbite:user-solid" />

<twig:ux:icon name="user-profile" height="16" width="16" aria-hidden="true" />

添加到组件或传递给函数的任何 HTML 属性都会渲染在 <svg> 元素上。

图标名称

本地图标

默认存储在 assets/icons/ 中。文件路径（去掉 .svg 后缀）会成为图标名称：

assets/icons/
  ├─ close.svg           → ux_icon('close')
  ├─ menu.svg            → ux_icon('menu')
  └─ header/
     └─ logo.svg         → ux_icon('header:logo')

子目录会成为前缀，并以 : 分隔。对于项目专属的 SVG（应用徽标、自定义插图），请使用本地图标。

Iconify（按需加载）

使用 prefix:name 语法从任意 Iconify 图标集中获取图标：

{# UI icons #}
{{ ux_icon('lucide:arrow-right') }}     {# Lucide #}
{{ ux_icon('tabler:heart') }}           {# Tabler #}
{{ ux_icon('heroicons:star-solid') }}   {# Heroicons #}
{{ ux_icon('mdi:check') }}              {# Material Design Icons #}

{# Country flags #}
<twig:ux:icon name="flagpack:fr" />
<twig:ux:icon name="flagpack:{{ country.code|lower }}" />

{# Brand logos #}
<twig:ux:icon name="simple-icons:symfony" />
<twig:ux:icon name="simple-icons:github" />

{# File type icons #}
<twig:ux:icon name="bi:filetype-pdf" />
<twig:ux:icon name="bi:filetype-{{ file.extension }}" />

按需加载的图标会从 Iconify API 获取、缓存在本地，并以内联 SVG 形式呈现。生产环境中不会发出运行时 HTTP 请求。

浏览所有可用图标集：https://icon-sets.iconify.design/

配置

# config/packages/ux_icons.yaml
ux_icons:
    # Local directory for icon SVG files
    icon_dir: '%kernel.project_dir%/assets/icons'

    # Default HTML attributes added to every icon
    default_icon_attributes:
        fill: currentColor
        'font-size': '1.25em'

    # Aliases: shortcut name => full icon name
    aliases:
        dots: 'clarity:ellipsis-horizontal-line'
        'tabler:save': 'tabler:device-floppy'

    # Iconify integration
    iconify:
        enabled: true
        on_demand: true
        endpoint: 'https://api.iconify.design'

    # Silently ignore missing icons (renders nothing instead of throwing)
    ignore_not_found: false

图标集

定义拥有独立前缀、来源和默认属性的自定义图标集：

ux_icons:
    icon_sets:
        # Local directory with custom attributes
        flags:
            path: '%kernel.project_dir%/assets/images/flags'
            icon_attributes:
                class: 'flag'
                fill: false           # "false" removes a default attribute

        # Alias an entire Iconify set under a shorter prefix
        icons:
            alias: 'lucide'           # ux_icon('icons:arrow-right') → lucide:arrow-right

别名

为常用图标创建快捷方式：

ux_icons:
    aliases:
        dots: 'clarity:ellipsis-horizontal-line'
        save: 'lucide:save'
        delete: 'lucide:trash-2'
        'tabler:save': 'tabler:device-floppy'   # can also remap within a set

{{ ux_icon('dots') }}    {# resolves to clarity:ellipsis-horizontal-line #}
{{ ux_icon('save') }}    {# resolves to lucide:save #}

CLI 命令

在本地导入图标

从 Iconify 下载图标到本地 assets/icons/ 目录：

# Import a single icon
php bin/console ux:icons:import flowbite:user-solid

# Import multiple icons
php bin/console ux:icons:import flowbite:user-solid flowbite:home-solid

# Force overwrite existing files
php bin/console ux:icons:import flowbite:user-solid --force

锁定所有按需加载的图标

将当前通过按需加载使用的所有图标下载为本地文件（类似于依赖锁定）：

php bin/console ux:icons:lock

# Force overwrite
php bin/console ux:icons:lock --force

# Verbose output (helps spot invalid icon names)
php bin/console ux:icons:lock -v

无障碍

图标默认用于装饰。对于具有实际含义的图标，请添加 aria-label：

{# Decorative (hidden from screen readers) #}
{{ ux_icon('lucide:star', {'aria-hidden': true}) }}

{# Meaningful (announced by screen readers) #}
{{ ux_icon('lucide:star', {'aria-label': 'Favorite', role: 'img'}) }}

核心原则

图标以内联 SVG 呈现。 无需图标字体，无需 <img> 标签，运行时也不会发出外部 HTTP 请求。SVG 标记会直接嵌入 HTML。这意味着图标会继承 currentColor，可以使用 CSS 设置样式，并且支持离线使用。

按需加载适用于开发环境。 开发期间，按需模式会根据需要从 Iconify 获取图标。生产环境中，请运行 ux:icons:lock 将所有已使用的图标下载到本地。

属性会层叠应用。 配置中的默认属性 < 图标集属性 < 单个图标属性。使用 false 可移除特定图标集或图标的默认属性。

优先使用 HTML 语法。 <twig:ux:icon name="..." /> 在模板中更易读，并且与其他 UX 组件保持一致。

参考资料

• API 与配置（所有选项、属性和图标集）：references/api.md
• 模式（常见用法、样式设置、动态图标）：references/patterns.md
• 注意事项（常见错误、调试和缓存）：references/gotchas.md