Icons preset

Používajte akúkoľvek ikonu s Pure CSS pre UnoCSS.

TIP

Nasledujte nasledujúce konvencie na používanie ikon

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

Napríklad:

html

<!-- A basic anchor icon from Phosphor icons -->
<div class="i-ph-anchor-simple-thin" />
<!-- An orange alarm from Material Design Icons -->
<div class="i-mdi-alarm text-orange-400" />
<!-- A large Vue logo -->
<div class="i-logos-vue text-3xl" />
<!-- Sun in light mode, Moon in dark mode, from Carbon -->
<button class="i-carbon-sun dark:i-carbon-moon" />
<!-- Twemoji of laugh, turns to tear on hovering -->
<div class="i-twemoji-grinning-face-with-smiling-eyes hover:i-twemoji-face-with-tears-of-joy" />

Hover it

Skontrolujte všetky dostupné ikony.

Inštalácia

pnpmyarnnpmbun

bash

pnpm add -D @unocss/preset-icons @iconify-json/[the-collection-you-want]

bash

yarn add -D @unocss/preset-icons @iconify-json/[the-collection-you-want]

bash

npm install -D @unocss/preset-icons @iconify-json/[the-collection-you-want]

bash

bun add -D @unocss/preset-icons @iconify-json/[the-collection-you-want]

Používame Iconify ako náš dátový zdroj ikon. Musíte nainštalovať zodpovedajúcu sadu ikon v devDependencies podľa vzoru @iconify-json/*. Napríklad, @iconify-json/mdi pre Material Design Icons, @iconify-json/tabler pre Tabler. Všetky dostupné kolekcie nájdete v Icônes alebo Iconify.

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

export default defineConfig({
  presets: [
    presetIcons({ /* možnosti */ }),
    // ...ostatné presety
  ],
})

TIP

Tento preset je zahrnutý v balíku unocss, môžete ho tiež importovať odtiaľ:

import { presetIcons } from 'unocss'

INFO

Tento preset môžete tiež používať samostatne ako doplnok k vašim existujúcim UI frameworkom na získanie Pure CSS ikon!

Ak preferujete nainštalovať všetky sady ikon dostupné na Iconify naraz (~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

Extra Properties

Môžete poskytnúť extra CSS vlastnosti na ovládanie predvoleného správania ikon. Nasledujúci príklad ukazuje, ako urobiť ikony inline predvolene:

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

Prepísanie režimov

Predvolene tento preset automaticky vyberie režimy vykresľovania pre každú ikonu na základe charakteristík ikon. Viac si môžete prečítať v tomto blogovom príspevku. V niektorých prípadoch môžete chcieť explicitne nastaviť režimy vykresľovania pre každú ikonu.

?bg pre background-img - vykreslí ikonu ako obrázok na pozadí
?mask pre mask - vykreslí ikonu ako masku

Napríklad, vscode-icons:file-type-light-pnpm, ikona s farbami (svg neobsahuje currentColor), ktorá bude vykreslená ako obrázok na pozadí. Použite vscode-icons:file-type-light-pnpm?mask na vykreslenie ako maska a obídenie jej farieb.

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>

Konfigurácia kolekcií a riešiteľov ikon

Môžete poskytnúť kolekcie cez @iconify-json/[the-collection-you-want], @iconify/json alebo používať vaše vlastné pomocou možnosti collections vo vašej konfigurácii UnoCSS.

Prehliadač

Na načítanie kolekcií iconify by ste mali používať @iconify-json/[the-collection-you-want] a nie @iconify/json, keďže json súbor je obrovský.

Bundler

Pri používaní bundlerov môžete poskytnúť kolekcie pomocou dynamic imports, takže budú bundlované ako async chunk a načítané na požiadanie.

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

Alebo ak preferujete načítať ich z CDN, môžete určiť možnosť cdn od verzie v0.32.10. Odporúčame esm.sh ako poskytovateľa CDN.

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

Prispôsobenie

Môžete tiež poskytnúť vaše vlastné vlastné kolekcie pomocou CustomIconLoader alebo InlineCollection, napríklad použitím 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),
    /* ... */
  }
})

A potom ju môžete použiť vo vašom HTML: <span class="i-custom:circle"></span>

Node.js

V Node.js bude preset automaticky hľadať nainštalovanú sadu ikon, takže nemusíte registrovať kolekcie iconify.

Môžete tiež poskytnúť vaše vlastné vlastné kolekcie pomocou CustomIconLoader alebo InlineCollection.

FileSystemIconLoader

Dodatočne môžete tiež použiť FileSystemIconLoader na načítanie vašich vlastných ikon z vášho súborového systému. Budete musieť nainštalovať balík @iconify/utils ako dev dependency.

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

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        // key ako názov kolekcie
        'my-icons': {
          account: '<svg><!-- ... --></svg>',
          // načítajte vašu vlastnú ikonu lenivo
          settings: () => fs.readFile('./path/to/my-icon.svg', 'utf-8'),
          /* ... */
        },
        'my-other-icons': async (iconName) => {
          // váš vlastný loader tu. Robte čo chcete.
          // napríklad, fetch z remote servera:
          return await fetch(`https://example.com/icons/${iconName}.svg`).then(res => res.text())
        },
        // helper na načítanie ikon zo súborového systému
        // súbory pod `./assets/icons` s príponou `.svg` budú načítané ako ich názov súboru
        // môžete tiež poskytnúť transform callback na zmenu každej ikony (voliteľné)
        'my-yet-other-icons': FileSystemIconLoader(
          './assets/icons',
          svg => svg.replace(/#fff/, 'currentColor')
        )
      }
    })
  ]
})

ExternalPackageIconLoader

Od @iconify/utils v2.1.20 môžete používať iné balíky na načítanie ikon od iných autorov pomocou nového helpera createExternalPackageIconLoader.

WARNING

Externé balíky musia obsahovať súbor icons.json s dátami icons vo formáte IconifyJSON, ktoré môžu byť exportované pomocou Iconify Tools. Pozrite si Exporting icon set as JSON package pre viac detailov.

Napríklad, môžete použiť an-awesome-collection alebo @my-awesome-collections/some-collection na načítanie vašich vlastných alebo third party ikon:

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

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

Môžete ju tiež kombinovať s inými vlastnými loadermi ikon, napríklad:

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

Prispôsobenie ikon

Môžete prispôsobiť všetky ikony pomocou možnosti konfigurácie customizations.

Dostupné funkcie prispôsobenia:

transform: transformuje raw svg, bude aplikované iba pri používaní vlastnej kolekcie ikon (iconify kolekcie vylúčené).
customize: zmení predvolené hodnoty prispôsobenia ikon.
iconCustomizer: zmení predvolené hodnoty prispôsobenia ikon.

Pre každú načítanú ikonu budú prispôsobenia aplikované v tomto poradí:

aplikovať transform na raw svg, ak je poskytnuté a používa vlastnú kolekciu ikon
aplikovať customize s predvolenými prispôsobeniami, ak je poskytnuté
aplikovať iconCustomizer s prispôsobeniami customize, ak je poskytnuté

Globálna transformácia vlastných ikon

Pri načítavaní vašich vlastných ikon ich môžete transformovať, napríklad pridaním atribútu fill s currentColor:

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

Od verzie 0.30.8 poskytuje transform názvy collection a icon:

presetIcons({
  customizations: {
    transform(svg, collection, icon) {
      // neaplikovať fill na tieto ikony v tejto kolekcii
      if (collection === 'custom' && icon === 'my-icon')
        return svg
      return svg.replace(/#fff/, 'currentColor')
    }
  }
})

Globálne prispôsobenie ikon

Pri načítavaní akejkoľvek ikony môžete prispôsobiť spoločné vlastnosti všetkým z nich, napríklad nastavením rovnakej veľkosti:

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

Prispôsobenie ikony/kolekcie

Môžete prispôsobiť každú ikonu pomocou možnosti konfigurácie iconCustomizer.

iconCustomizer bude mať prednosť pred konfiguráciou.

iconCustomizer bude aplikovaný na akúkoľvek kolekciu, to znamená pre každú ikonu z custom loadera, inlined vo vlastných kolekciách alebo z @iconify.

Napríklad, môžete nakonfigurovať iconCustomizer na zmenu všetkých ikon pre kolekciu alebo jednotlivé ikony v kolekcii:

presetIcons({
  customizations: {
    iconCustomizer(collection, icon, props) {
      // prispôsobiť všetky ikony v tejto kolekcii
      if (collection === 'my-other-icons') {
        props.width = '4em'
        props.height = '4em'
      }
      // prispôsobiť túto ikonu v tejto kolekcii
      if (collection === 'my-icons' && icon === 'account') {
        props.width = '6em'
        props.height = '6em'
      }
      // prispôsobiť túto @iconify ikonu v tejto kolekcii
      if (collection === 'mdi' && icon === 'account') {
        props.width = '2em'
        props.height = '2em'
      }
    }
  }
})

Direktívy

Môžete použiť direktívu icon() vo vašom CSS na získanie metadát ikony.

css

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

WARNING

icon() závisí na @unocss/preset-icons a bude používať konfiguráciu, uistite sa, že ste pridali tento preset.

Viac o direktíve icon(), skontrolujte Directives.

Možnosti

scale

Type: number
Default: 1

Mierka vzhľadom na aktuálnu veľkosť písma (1em).

mode

Type: 'mask' | 'bg' | 'auto'
Default: 'auto'
See: https://antfu.me/posts/icons-in-pure-css

Režim generovaných CSS ikon.

TIP

mask - používa farbu pozadia a vlastnosť mask pre monochromatické ikony
bg - používa obrázok na pozadí pre ikony, farby sú statické
auto - inteligentne rozhoduje režim medzi mask a bg pre každú ikonu na základe jej štýlu

prefix

Type: string | string[]
Default: 'i-'

Prefix triedy pre párovanie pravidiel ikon.

extraProperties

Type: Record<string, string>
Default: {}

Extra CSS vlastnosti aplikované na generované CSS.

warn

Type: boolean
Default: false

Vypísať varovanie, keď chýbajúce ikony sú spárované.

iconifyCollectionsNames

Type: string[]
Default: undefined

Dodatočné kolekcie @iconify-json na použitie. Táto možnosť by sa mala používať, keď sú nové kolekcie @iconify-json neuvedené v predvolených názvoch kolekcií ikon presetu.

collections

Type: Record<string, (() => Awaitable<IconifyJSON>) | undefined | CustomIconLoader | InlineCollection>
Default: undefined

V prostredí Node.js bude preset automaticky hľadať nainštalovanú sadu ikon. Pri používaní v prehliadači je táto možnosť poskytnutá na poskytnutie datasetu s vlastným mechanizmom načítavania.

layer

Type: string
Default: 'icons'

Vrstva pravidla.

customizations

Type: Omit<IconCustomizations, 'additionalProps' | 'trimCustomSvg'>
Default: undefined

Vlastné prispôsobenia ikon.

autoInstall

Type: boolean
Default: false

Automaticky nainštalovať balík zdroja ikon, keď je detegované použitie.

WARNING

Iba v prostredí node, v browser bude táto možnosť ignorovaná.

unit

Type: string
Default: 'em'

Vlastná jednotka ikony.

cdn

Type: string
Default: undefined

Načítať ikony z CDN. Malo by začínať https:// a končiť /.

Odporúčania:

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

customFetch

Type: (url: string) => Promise<any>
Default: undefined

Preset používa ofetch ako predvolený fetcher, môžete tiež poskytnúť vlastnú fetch funkciu na poskytnutie dát ikon.

processor

Type: (cssObject: CSSObject, meta: Required<IconMeta>) => void
Default: undefined

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

Procesor pre CSS objekt pred stringifikáciou. Pozrite príklad.

Pokročilé čistenie vlastnej sady ikon

Pri používaní tohto presetu s vašimi vlastnými ikonami zvážte použitie procesu čistenia podobného tomu, ktorý robí Iconify pre akékoľvek sady ikon. Všetky nástroje, ktoré potrebujete, sú dostupné v Iconify Tools.

Môžete skontrolovať toto repo, používajúce tento preset v projekte Vue 3: @iconify/tools/@iconify-demo/unocss.

Pre viac detailov si prečítajte článok Cleaning up icons od Iconify.

Problémy s prístupnosťou

Pri používaní ikon je dôležité brať do úvahy všetkých vašich potenciálnych používateľov. Niektorí z nich môžu používať čítačky obrazovky a budú potrebovať alternatívny text na pochopenie významu ikony. Môžete použiť atribút aria-label na poskytnutie popisu ikony:

html

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

Ak je ikona čisto dekoratívna a nepotrebuje textovú alternatívu, môžete použiť aria-hidden="true" na skrytie pred čítačkami obrazovky:

html

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

Existuje mnoho ďalších techník na poskytnutie hint textu pre čítačky obrazovky, napríklad Wind3 preset obsahuje sr-only na vizuálne skrytie prvkov, ale udržanie ich prístupných pre čítačky obrazovky.

Na webe nájdete dobré zdroje o prístupnosti ikon a CSS ikony sa správajú ako ikonové fonty, takže môžete používať rovnaké techniky ako pri ikonových fontoch.

Kredity

Tento preset je inšpirovaný týmto issue vytvoreným @husayt.
Založené na práci tohto PR od @userquin.

Icons preset ​

Inštalácia ​

Extra Properties ​

Prepísanie režimov ​

Konfigurácia kolekcií a riešiteľov ikon ​

Prehliadač ​

Bundler ​

CDN ​

Prispôsobenie ​

Node.js ​

FileSystemIconLoader ​

ExternalPackageIconLoader ​

Prispôsobenie ikon ​

Globálna transformácia vlastných ikon ​

Globálne prispôsobenie ikon ​

Prispôsobenie ikony/kolekcie ​

Direktívy ​

Možnosti ​

scale ​

mode ​

prefix ​

extraProperties ​

warn ​

iconifyCollectionsNames ​

collections ​

layer ​

customizations ​

autoInstall ​

unit ​

cdn ​

customFetch ​

processor ​

Pokročilé čistenie vlastnej sady ikon ​

Problémy s prístupnosťou ​

Kredity ​

Icons preset

Inštalácia

Extra Properties

Prepísanie režimov

Konfigurácia kolekcií a riešiteľov ikon

Prehliadač

Bundler

CDN

Prispôsobenie

Node.js

FileSystemIconLoader

ExternalPackageIconLoader

Prispôsobenie ikon

Globálna transformácia vlastných ikon

Globálne prispôsobenie ikon

Prispôsobenie ikony/kolekcie

Direktívy

Možnosti

scale

mode

prefix

extraProperties

warn

iconifyCollectionsNames

collections

layer

customizations

autoInstall

unit

cdn

customFetch

processor

Pokročilé čistenie vlastnej sady ikon

Problémy s prístupnosťou

Kredity