Symfony UX 圖示

安裝

1

$ composer require symfony/ux-icons

SVG 圖示

SVG (可縮放向量圖形) 是一種基於 XML 的向量圖像格式，允許解析度獨立的圖形，同時保持檔案大小較小。SVG 圖示可以嵌入在 HTML 程式碼中，使用 CSS 設定樣式，並使用 JavaScript 動畫化。

UX 圖示讓您可以使用來自最熱門圖示集的圖示，同時也讓您能夠彈性地組合自己的集合，混合來自不同集合和您自己的圖示。

載入圖示

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') }}

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

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

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]:
 >

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" />

下載圖示

此套件不包含任何圖示，但提供超過 200,000 個開放原始碼圖示的存取權。

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
│     └─ ...
└─ ...

匯入圖示

雖然隨需圖示在開發期間很棒，但它們需要 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

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') }}

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" />

1
2
3
4

# config/packages/ux_icons.yaml
ux_icons:
    default_icon_attributes:
        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'}) }}

1
2
3
4
5

# config/packages/ux_icons.yaml
ux_icons:
    # ...
    aliases:
        dots: 'clarity:ellipsis-horizontal-line'

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。

1

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

效能

UX 圖示元件旨在快速。以下是一些為確保最佳效能而進行的最佳化。

快取

1

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

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]) }}

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 圖示與 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

瞭解更多

• 建立和使用模板
• 如何在 Symfony 應用程式中管理 CSS 和 JavaScript 資產