Icons Preset

Verwenden Sie jedes Icon mit Pure CSS für UnoCSS.

TIP

Folgen Sie den folgenden Konventionen, um die Icons zu verwenden

<prefix><collection>-<icon>
<prefix><collection>:<icon>

Zum Beispiel:

html

<!-- Ein grundlegendes Anker-Icon von Phosphor Icons -->
<div class="i-ph-anchor-simple-thin" />
<!-- Ein oranges Alarm-Icon von Material Design Icons -->
<div class="i-mdi-alarm text-orange-400" />
<!-- Ein großes Vue-Logo -->
<div class="i-logos-vue text-3xl" />
<!-- Sonne im hellen Modus, Mond im dunklen Modus, von Carbon -->
<button class="i-carbon-sun dark:i-carbon-moon" />
<!-- Twemoji von Lachen, wird zu Tränen beim Hovern -->
<div class="i-twemoji-grinning-face-with-smiling-eyes hover:i-twemoji-face-with-tears-of-joy" />

Darüber hovern

Überprüfen Sie alle verfügbaren Icons.

Installation

pnpmyarnnpmbun

bash

pnpm add -D @unocss/preset-icons @iconify-json/[die-collection-die-sie-wollen]

bash

yarn add -D @unocss/preset-icons @iconify-json/[die-collection-die-sie-wollen]

bash

npm install -D @unocss/preset-icons @iconify-json/[die-collection-die-sie-wollen]

bash

bun add -D @unocss/preset-icons @iconify-json/[die-collection-die-sie-wollen]

Wir verwenden Iconify als unsere Datenquelle für Icons. Sie müssen das entsprechende Icon-Set in devDependencies installieren, indem Sie dem @iconify-json/* Muster folgen. Zum Beispiel @iconify-json/mdi für Material Design Icons, @iconify-json/tabler für Tabler. Sie können sich auf Icônes oder Iconify beziehen, um alle verfügbaren Sammlungen zu sehen.

import presetIcons from '@unocss/preset-icons'
import { defineConfig } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({ /* Optionen */ }),
    // ...andere Presets
  ],
})

TIP

Dieses Preset ist im unocss Paket enthalten, Sie können es auch von dort importieren:

import { presetIcons } from 'unocss'

INFO

Sie können dieses Preset auch allein als Ergänzung zu Ihren vorhandenen UI-Frameworks verwenden, um reine CSS-Icons zu haben!

Wenn Sie es vorziehen, alle auf Iconify verfügbaren Icon-Sets auf einmal zu installieren (~130MB):

pnpmyarnnpmbun

bash

pnpm add -D @iconify/json

bash

yarn add -D @iconify/json

bash

npm install -D @iconify/json

bash

bun add -D @iconify/json

Zusätzliche Eigenschaften

Sie können zusätzliche CSS-Eigenschaften bereitstellen, um das Standardverhalten der Icons zu steuern. Das Folgende ist ein Beispiel dafür, Icons standardmäßig inline zu machen:

presetIcons({
  extraProperties: {
    'display': 'inline-block',
    'vertical-align': 'middle',
    // ...
  },
})

Modus-Überschreibung

Standardmäßig wählt dieses Preset die Rendering-Modi automatisch für jedes Icon basierend auf den Eigenschaften der Icons aus. Sie können mehr in diesem Blog-Post lesen. In einigen Fällen möchten Sie möglicherweise die Rendering-Modi für jedes Icon explizit setzen.

?bg für background-img - rendert das Icon als Hintergrundbild
?mask für mask - rendert das Icon als Maskenbild

Zum Beispiel vscode-icons:file-type-light-pnpm, ein Icon mit Farben (das svg enthält kein currentColor), das als Hintergrundbild gerendert wird. Verwenden Sie vscode-icons:file-type-light-pnpm?mask, um es als Maskenbild zu rendern und seine Farben zu umgehen.

html

<div class="w-full flex items-center justify-center gap-x-4 text-4xl p-2 mt-4">
  <div class="i-vscode-icons:file-type-light-pnpm" />
  <div class="i-vscode-icons:file-type-light-pnpm?mask text-red-300" />
</div>

Konfigurieren von Sammlungen und Icon-Resolvern

Sie können Sammlungen über @iconify-json/[die-collection-die-sie-wollen], @iconify/json oder mit Ihren benutzerdefinierten über die collections Option in Ihrer UnoCSS Konfiguration bereitstellen.

Browser

Um iconify Sammlungen zu laden, sollten Sie @iconify-json/[die-collection-die-sie-wollen] verwenden und nicht @iconify/json, da die json Datei riesig ist.

Bundler

Bei Verwendung von Bundlern können Sie die Sammlungen mit dynamic imports bereitstellen, sodass sie als asynchroner Chunk gebündelt und bei Bedarf geladen werden.

import presetIcons from '@unocss/preset-icons/browser'

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        carbon: () => import('@iconify-json/carbon/icons.json').then(i => i.default),
        mdi: () => import('@iconify-json/mdi/icons.json').then(i => i.default),
        logos: () => import('@iconify-json/logos/icons.json').then(i => i.default),
      }
    })
  ]
})

CDN

Oder wenn Sie es vorziehen, sie von CDN abzurufen, können Sie die cdn Option seit v0.32.10 angeben. Wir empfehlen esm.sh als CDN-Anbieter.

presetIcons({
  cdn: 'https://esm.sh/'
})

Anpassung

Sie können auch Ihre eigenen benutzerdefinierten Sammlungen mit CustomIconLoader oder InlineCollection bereitstellen, zum Beispiel mit InlineCollection:

presetIcons({
  collections: {
    custom: {
      circle: '<svg viewBox="0 0 120 120"><circle cx="60" cy="60" r="50"></circle></svg>',
      /* ... */
    },
    carbon: () => import('@iconify-json/carbon/icons.json').then(i => i.default as any),
    /* ... */
  }
})

Und dann können Sie es in Ihrem HTML verwenden: <span class="i-custom:circle"></span>

Node.js

In Node.js sucht das Preset automatisch nach dem installierten Iconify-Datensatz, sodass Sie die iconify Sammlungen nicht registrieren müssen.

Sie können auch Ihre eigenen benutzerdefinierten Sammlungen mit CustomIconLoader oder InlineCollection bereitstellen.

FileSystemIconLoader

Zusätzlich können Sie auch FileSystemIconLoader verwenden, um Ihre benutzerdefinierten Icons aus Ihrem Dateisystem zu laden. Sie müssen das @iconify/utils Paket als dev dependency installieren.

import fs from 'node:fs/promises'
// Loader-Helfer
import { FileSystemIconLoader } from '@iconify/utils/lib/loader/node-loaders'
import { defineConfig, presetIcons } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        // Schlüssel als Sammlungsname
        'my-icons': {
          account: '<svg><!-- ... --></svg>',
          // Laden Sie Ihr benutzerdefiniertes Icon träge
          settings: () => fs.readFile('./path/to/my-icon.svg', 'utf-8'),
          /* ... */
        },
        'my-other-icons': async (iconName) => {
          // Ihr benutzerdefinierter Loader hier. Tun Sie, was Sie wollen.
          // zum Beispiel von einem Remote-Server abrufen:
          return await fetch(`https://example.com/icons/${iconName}.svg`).then(res => res.text())
        },
        // ein Helfer zum Laden von Icons aus dem Dateisystem
        // Dateien unter `./assets/icons` mit `.svg` Erweiterung werden als Dateiname geladen
        // Sie können auch einen Transform-Callback bereitstellen, um jedes Icon zu ändern (optional)
        'my-yet-other-icons': FileSystemIconLoader(
          './assets/icons',
          svg => svg.replace(/#fff/, 'currentColor')
        )
      }
    })
  ]
})

ExternalPackageIconLoader

Ab @iconify/utils v2.1.20 können Sie andere Pakete verwenden, um Icons von anderen Autoren zu laden, indem Sie den neuen createExternalPackageIconLoader Helfer verwenden.

WARNUNG

Externe Pakete müssen eine icons.json Datei mit den icons Daten im IconifyJSON Format enthalten, die mit Iconify Tools exportiert werden kann. Überprüfen Sie Icon-Set als JSON-Paket exportieren für weitere Details.

Zum Beispiel können Sie an-awesome-collection oder @my-awesome-collections/some-collection verwenden, um Ihre benutzerdefinierten oder Drittanbieter-Icons zu laden:

import { createExternalPackageIconLoader } from '@iconify/utils/lib/loader/external-pkg'
import { defineConfig, presetIcons } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({
      collections: createExternalPackageIconLoader('an-awesome-collection')
    })
  ]
})

Sie können es auch mit anderen benutzerdefinierten Icon-Loadern kombinieren, zum Beispiel:

import { createExternalPackageIconLoader } from '@iconify/utils/lib/loader/external-pkg'
import { defineConfig, presetIcons } from 'unocss'
import { FileSystemIconLoader } from 'unplugin-icons/loaders'

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        ...createExternalPackageIconLoader('other-awesome-collection'),
        ...createExternalPackageIconLoader('@my-awesome-collections/some-collection'),
        ...createExternalPackageIconLoader('@my-awesome-collections/some-other-collection'),
        'my-yet-other-icons': FileSystemIconLoader(
          './assets/icons',
          svg => svg.replace(/^<svg /, '<svg fill="currentColor" ')
        )
      }
    })
  ]
})

Icon-Anpassungen

Sie können alle Icons mit der customizations Konfigurationsoption anpassen.

Verfügbare Anpassungsfunktionen:

transform: transformiert rohes svg, wird nur angewendet, wenn die custom Icon-Sammlung verwendet wird (iconify Sammlungen ausgeschlossen).
customize: ändert Standard-Icon-Anpassungswerte.
iconCustomizer: ändert Standard-Icon-Anpassungswerte.

Für jedes geladene Icon werden die Anpassungen in dieser Reihenfolge angewendet:

wenden Sie transform auf rohes svg an, wenn bereitgestellt und benutzerdefinierte Icon-Sammlung verwendet wird
wenden Sie customize mit Standard-Anpassungen an, wenn bereitgestellt
wenden Sie iconCustomizer mit customize Anpassungen an, wenn bereitgestellt

Globale benutzerdefinierte Icon-Transformation

Beim Laden Ihrer benutzerdefinierten Icons können Sie sie transformieren, zum Beispiel das fill Attribut mit currentColor hinzufügen:

presetIcons({
  customizations: {
    transform(svg) {
      return svg.replace(/#fff/, 'currentColor')
    }
  }
})

Ab Version 0.30.8 stellt transform die collection und icon Namen bereit:

presetIcons({
  customizations: {
    transform(svg, collection, icon) {
      // wenden Sie fill nicht auf diese Icons in dieser Sammlung an
      if (collection === 'custom' && icon === 'my-icon')
        return svg
      return svg.replace(/#fff/, 'currentColor')
    }
  }
})

Globale Icon-Anpassung

Beim Laden eines beliebigen Icons können Sie gemeinsame Eigenschaften für alle anpassen, zum Beispiel die gleiche Größe konfigurieren:

presetIcons({
  customizations: {
    customize(props) {
      props.width = '2em'
      props.height = '2em'
      return props
    }
  }
})

Icon/Sammlung-Anpassung

Sie können jedes Icon mit der iconCustomizer Konfigurationsoption anpassen.

Der iconCustomizer hat Vorrang vor der Konfiguration.

Der iconCustomizer wird auf jede Sammlung angewendet, das heißt, für jedes Icon vom custom Loader, inlined auf custom collections oder von @iconify.

Zum Beispiel können Sie iconCustomizer konfigurieren, um alle Icons für eine Sammlung oder einzelne Icons in einer Sammlung zu ändern:

presetIcons({
  customizations: {
    iconCustomizer(collection, icon, props) {
      // passen Sie alle Icons in dieser Sammlung an
      if (collection === 'my-other-icons') {
        props.width = '4em'
        props.height = '4em'
      }
      // passen Sie dieses Icon in dieser Sammlung an
      if (collection === 'my-icons' && icon === 'account') {
        props.width = '6em'
        props.height = '6em'
      }
      // passen Sie dieses @iconify Icon in dieser Sammlung an
      if (collection === 'mdi' && icon === 'account') {
        props.width = '2em'
        props.height = '2em'
      }
    }
  }
})

Direktiven

Sie können die icon() Direktive in Ihrem CSS verwenden, um die Metadaten des Icons zu erhalten.

css

.icon {
  background-image: icon('i-carbon-sun');
}

WARNING

icon() hängt von @unocss/preset-icons ab und verwendet die Konfiguration. Stellen Sie sicher, dass Sie dieses Preset hinzugefügt haben.

Mehr über die icon() Direktive, siehe Direktiven.

Optionen

scale

Typ: number
Standard: 1

Skalierung bezogen auf die aktuelle Schriftgröße (1em).

mode

Typ: 'mask' | 'bg' | 'auto'
Standard: 'auto'
Siehe: https://antfu.me/posts/icons-in-pure-css

Modus der generierten CSS-Icons.

TIP

mask - verwenden Sie Hintergrundfarbe und die mask Eigenschaft für monochrome Icons
bg - verwenden Sie Hintergrundbild für die Icons, Farben sind statisch
auto - entscheidet intelligent den Modus zwischen mask und bg pro Icon basierend auf seinem Stil

prefix

Typ: string | string[]
Standard: 'i-'

Klassen-Präfix zum Abgleichen von Icon-Regeln.

extraProperties

Typ: Record<string, string>
Standard: {}

Zusätzliche CSS-Eigenschaften, die auf das generierte CSS angewendet werden.

warn

Typ: boolean
Standard: false

Warnung ausgeben, wenn fehlende Icons abgeglichen werden.

iconifyCollectionsNames

Typ: string[]
Standard: undefined

Zusätzliche @iconify-json Sammlungen zu verwenden. Diese Option sollte verwendet werden, wenn es neue @iconify-json Sammlungen gibt, die nicht in den Standard-Icon-Preset-Sammlungsnamen aufgeführt sind.

collections

Typ: Record<string, (() => Awaitable<IconifyJSON>) | undefined | CustomIconLoader | InlineCollection>
Standard: undefined

In der Node.js-Umgebung sucht das Preset automatisch nach dem installierten Iconify-Datensatz. Bei Verwendung im Browser wird diese Option bereitgestellt, um Datensätze mit benutzerdefiniertem Lademechanismus bereitzustellen.

layer

Typ: string
Standard: 'icons'

Regel-Ebene.

customizations

Typ: Omit<IconCustomizations, 'additionalProps' | 'trimCustomSvg'>
Standard: undefined

Benutzerdefinierte Icon-Anpassungen.

autoInstall

Typ: boolean
Standard: false

Automatisch Icon-Quellenpaket installieren, wenn Verwendungen erkannt werden.

WARNING

Nur in der node Umgebung, im browser wird diese Option ignoriert.

unit

Typ: string
Standard: 'em'

Benutzerdefinierte Icon-Einheit.

cdn

Typ: string
Standard: undefined

Icons von CDN laden. Sollte mit https:// beginnen und mit / enden.

Empfehlungen:

https://esm.sh/
https://cdn.skypack.dev/

customFetch

Typ: (url: string) => Promise<any>
Standard: undefined

Preset verwendet ofetch als Standard-Fetcher, Sie können auch eine benutzerdefinierte Fetch-Funktion bereitstellen, um die Icon-Daten bereitzustellen.

processor

Typ: (cssObject: CSSObject, meta: Required<IconMeta>) => void
Standard: undefined

interface IconMeta {
  collection: string
  icon: string
  svg: string
  mode?: IconsOptions['mode']
}

Prozessor für das CSS-Objekt vor dem Stringify. Siehe Beispiel.

Erweiterte benutzerdefinierte Icon-Set-Bereinigung

Wenn Sie dieses Preset mit Ihren benutzerdefinierten Icons verwenden, sollten Sie einen Bereinigungsprozess verwenden, der dem ähnelt, der von Iconify für Icon-Sets durchgeführt wird. Alle Tools, die Sie benötigen, sind in Iconify Tools verfügbar.

Sie können dieses Repo überprüfen, das dieses Preset in einem Vue 3 Projekt verwendet: @iconify/tools/@iconify-demo/unocss.

Lesen Sie den Artikel Icons bereinigen von Iconify für weitere Details.

Barrierefreiheitsbedenken

Bei der Verwendung von Icons ist es wichtig, alle Ihre potenziellen Benutzer zu berücksichtigen. Einige von ihnen verwenden möglicherweise Bildschirmleser und benötigen einen alternativen Text, um zu verstehen, was ein Icon bedeutet. Sie können das aria-label Attribut verwenden, um eine Beschreibung des Icons bereitzustellen:

html

<a href="/profile" aria-label="Profil" class="i-ph:user-duotone"></a>

Wenn das Icon rein dekorativ ist und keinen Textalternativ benötigt, können Sie aria-hidden="true" verwenden, um es vor Bildschirmlesern zu verbergen:

html

<a href="/profile">
  <span aria-hidden="true" class="i-ph:user-duotone"></span>
  Mein Profil
</a>

Es gibt viele andere Techniken, um Hinweistext für Bildschirmleser bereitzustellen. Zum Beispiel enthält das Wind3 Preset sr-only, um Elemente visuell zu verbergen, aber für Bildschirmleser zugänglich zu halten.

Sie können einige gute Ressourcen im Web über Icon-Barrierefreiheit finden, und CSS-Icons verhalten sich wie Icon-Schriften, sodass Sie die gleichen Techniken verwenden können, wie Sie es mit Icon-Schriften tun würden.

Credits

Dieses Preset ist inspiriert von diesem Issue, erstellt von @husayt.
Basierend auf der Arbeit von diesem PR von @userquin.

Icons Preset ​

Installation ​

Zusätzliche Eigenschaften ​

Modus-Überschreibung ​

Konfigurieren von Sammlungen und Icon-Resolvern ​

Browser ​

Bundler ​

CDN ​

Anpassung ​

Node.js ​

FileSystemIconLoader ​

ExternalPackageIconLoader ​

Icon-Anpassungen ​

Globale benutzerdefinierte Icon-Transformation ​

Globale Icon-Anpassung ​

Icon/Sammlung-Anpassung ​

Direktiven ​

Optionen ​

scale ​

mode ​

prefix ​

extraProperties ​

warn ​

iconifyCollectionsNames ​

collections ​

layer ​

customizations ​

autoInstall ​

unit ​

cdn ​

customFetch ​

processor ​

Erweiterte benutzerdefinierte Icon-Set-Bereinigung ​

Barrierefreiheitsbedenken ​

Credits ​

Icons Preset

Installation

Zusätzliche Eigenschaften

Modus-Überschreibung

Konfigurieren von Sammlungen und Icon-Resolvern

Browser

Bundler

CDN

Anpassung

Node.js

FileSystemIconLoader

ExternalPackageIconLoader

Icon-Anpassungen

Globale benutzerdefinierte Icon-Transformation

Globale Icon-Anpassung

Icon/Sammlung-Anpassung

Direktiven

Optionen

scale

mode

prefix

extraProperties

warn

iconifyCollectionsNames

collections

layer

customizations

autoInstall

unit

cdn

customFetch

processor

Erweiterte benutzerdefinierte Icon-Set-Bereinigung

Barrierefreiheitsbedenken

Credits