Icons prednastavitev

Uporabite poljubno ikono s čistim CSS za UnoCSS.

TIP

Sledite naslednjim konvencijam za uporabo ikon:

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

Na primer:

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

Preverite vse razpoložljive ikone.

Namestitev

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]

Uporabljamo Iconify kot naš vir podatkov za ikone. Namestiti morate ustrezno zbirko ikon v devDependencies po vzorcu @iconify-json/*. Na primer, @iconify-json/mdi za Material Design Icons, @iconify-json/tabler za Tabler. Za vse razpoložljive zbirke si oglejte Icônes ali Iconify.

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

export default defineConfig({
  presets: [
    presetIcons({ /* možnosti */ }),
    // ...druge prednastavitve
  ],
})

TIP

Ta prednastavitev je vključena v paket unocss, lahko jo tudi uvozite od tam:

import { presetIcons } from 'unocss'

INFO

To prednastavitev lahko uporabite tudi samostojno kot dopolnilo vašim obstoječim UI frameworkom za pridobivanje ikon s čistim CSS!

Če želite namestiti vse zbirke ikon, ki so na voljo na Iconify hkrati (~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

Dodatne lastnosti

Lahko zagotovite dodatne CSS lastnosti za nadzor privzetega vedenja ikon. Sledi primer, kako narediti ikone privzeto v vrstici:

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

Prekrivanje načinov

Privzeto bo ta prednastavitev samodejno izbrala načine upodabljanja za vsako ikono na podlagi značilnosti ikon. Več si lahko preberete v tem blogu. V nekaterih primerih boste morda želeli eksplicitno nastaviti načine upodabljanja za vsako ikono.

?bg za background-img - upodobi ikono kot sliko v ozadju
?mask za mask - upodobi ikono kot masko

Na primer, vscode-icons:file-type-light-pnpm, ikona z barvami (svg ne vsebuje currentColor), ki bo upodobljena kot slika v ozadju. Uporabite vscode-icons:file-type-light-pnpm?mask za upodabljanje kot masko in obidite njene barve.

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>

Konfiguriranje zbirk in razreševalnikov ikon

Zbirke lahko zagotovite prek @iconify-json/[the-collection-you-want], @iconify/json ali uporabite svoje prilagojene z uporabo možnosti collections v vaši konfiguraciji UnoCSS.

Brskalnik

Za nalaganje zbirk iconify uporabite @iconify-json/[the-collection-you-want] in ne @iconify/json, saj je json datoteka ogromna.

Bundler

Pri uporabi bundlerjev lahko zagotovite zbirke z uporabo dynamic imports, tako da bodo združene kot asinhroni del in naložene na zahtevo.

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

Ali če jih želite prenesti s CDN, lahko določite možnost cdn od različice v0.32.10. Priporočamo esm.sh kot ponudnika CDN.

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

Prilagoditev

Svoje prilagojene zbirke lahko zagotovite tudi z uporabo CustomIconLoader ali InlineCollection, na primer z uporabo 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),
    /* ... */
  }
})

In nato jo lahko uporabite v vašem html: <span class="i-custom:circle"></span>

Node.js

V Node.js bo prednastavitev samodejno poiskala nameščeni nabor podatkov iconify, zato vam ni treba registrirati zbirk iconify.

Svoje prilagojene zbirke lahko zagotovite tudi z uporabo CustomIconLoader ali InlineCollection.

FileSystemIconLoader

Poleg tega lahko uporabite tudi FileSystemIconLoader za nalaganje vaših prilagojenih ikon iz vašega datotečnega sistema. Namestiti boste morali paket @iconify/utils kot 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 as the collection name
        'my-icons': {
          account: '<svg><!-- ... --></svg>',
          // load your custom icon lazily
          settings: () => fs.readFile('./path/to/my-icon.svg', 'utf-8'),
          /* ... */
        },
        'my-other-icons': async (iconName) => {
          // your custom loader here. Do whatever you want.
          // for example, fetch from a remote server:
          return await fetch(`https://example.com/icons/${iconName}.svg`).then(res => res.text())
        },
        // a helper to load icons from the file system
        // files under `./assets/icons` with `.svg` extension will be loaded as it's file name
        // you can also provide a transform callback to change each icon (optional)
        'my-yet-other-icons': FileSystemIconLoader(
          './assets/icons',
          svg => svg.replace(/#fff/, 'currentColor')
        )
      }
    })
  ]
})

ExternalPackageIconLoader

Od @iconify/utils v2.1.20 lahko uporabite druge pakete za nalaganje ikon od drugih avtorjev z uporabo novega helperja createExternalPackageIconLoader.

OPOZORILO

Zunanji paketi morajo vključevati datoteko icons.json s podatki icons v formatu IconifyJSON, ki se lahko izvozi z orodji Iconify. Za več podrobnosti si oglejte Exporting icon set as JSON package.

Na primer, lahko uporabite an-awesome-collection ali @my-awesome-collections/some-collection za nalaganje vaših prilagojenih ali ikon tretjih oseb:

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

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

Lahko jih tudi kombinirate z drugimi nalagalniki ikon, na primer:

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

Prilagoditve ikon

Vse ikone lahko prilagodite z uporabo konfiguracijske možnosti customizations.

Razpoložljive funkcije prilagoditev:

transform: transformira surovi svg, bo uporabljen le pri uporabi zbirke ikon custom (razen zbirk iconify).
customize: spremeni privzete vrednosti prilagoditev ikon.
iconCustomizer: spremeni privzete vrednosti prilagoditev ikon.

Za vsako naloženo ikono bodo prilagoditve uporabljene v tem vrstnem redu:

uporabi transform na surovem svg, če je zagotovljeno in uporablja zbirko ikon po meri
uporabi customize s privzetimi prilagoditvami, če je zagotovljeno
uporabi iconCustomizer s prilagoditvami customize, če je zagotovljeno

Globalna transformacija ikon po meri

Pri nalaganju vaših prilagojenih ikon jih lahko transformirate, na primer z dodajanjem atributa fill z currentColor:

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

Od različice 0.30.8 transform zagotavlja imeni collection in icon:

presetIcons({
  customizations: {
    transform(svg, collection, icon) {
      // do not apply fill to this icons on this collection
      if (collection === 'custom' && icon === 'my-icon')
        return svg
      return svg.replace(/#fff/, 'currentColor')
    }
  }
})

Globalna prilagoditev ikon

Pri nalaganju katerekoli ikone lahko prilagodite skupne lastnosti vsem, na primer konfigurirate enako velikost:

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

Prilagoditev ikone/zbirke

Vsako ikono lahko prilagodite z uporabo konfiguracijske možnosti iconCustomizer.

iconCustomizer bo imel prednost pred konfiguracijo.

iconCustomizer bo uporabljen za katerokoli zbirko, to je za vsako ikono iz nalagalnika custom, inlined v custom collections ali iz @iconify.

Na primer, lahko konfigurirate iconCustomizer za spremembo vseh ikon za zbirko ali posamezne ikone v zbirki:

presetIcons({
  customizations: {
    iconCustomizer(collection, icon, props) {
      // customize all icons in this collection
      if (collection === 'my-other-icons') {
        props.width = '4em'
        props.height = '4em'
      }
      // customize this icon in this collection
      if (collection === 'my-icons' && icon === 'account') {
        props.width = '6em'
        props.height = '6em'
      }
      // customize this @iconify icon in this collection
      if (collection === 'mdi' && icon === 'account') {
        props.width = '2em'
        props.height = '2em'
      }
    }
  }
})

Direktive

V vašem CSS lahko uporabite direktivo icon() za pridobivanje metapodatkov ikone.

css

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

WARNING

icon() je odvisen od @unocss/preset-icons in bo uporabil konfiguracijo, prepričajte se, da ste dodali to prednastavitev.

Več o direktivi icon(), preverite Directives.

Možnosti

scale

Tip: number
Privzeto: 1

Merilo glede na trenutno velikost pisave (1em).

mode

Tip: 'mask' | 'bg' | 'auto'
Privzeto: 'auto'
Glej: https://antfu.me/posts/icons-in-pure-css

Način generiranih CSS ikon.

TIP

mask - uporaba barve ozadja in lastnosti mask za monokromatske ikone
bg - uporaba slike ozadja za ikone, barve so statične
auto - pametno odloči način med mask in bg za ikono na podlagi njenega sloga

prefix

Tip: string | string[]
Privzeto: 'i-'

Predpona razreda za ujemanje pravil ikon.

extraProperties

Tip: Record<string, string>
Privzeto: {}

Dodatne CSS lastnosti, uporabljene za generirani CSS.

warn

Tip: boolean
Privzeto: false

Emitiraj opozorilo, ko se ujemajo manjkajoče ikone.

iconifyCollectionsNames

Tip: string[]
Privzeto: undefined

Dodatne zbirke @iconify-json za uporabo. To možnost je treba uporabiti, ko so nove zbirke @iconify-json, ki niso navedene v privzetih imenih zbirk prednastavitve ikon.

collections

Tip: Record<string, (() => Awaitable<IconifyJSON>) | undefined | CustomIconLoader | InlineCollection>
Privzeto: undefined

V okolju Node.js bo prednastavitev samodejno poiskala nameščeni nabor podatkov iconify. Pri uporabi v brskalniku je ta možnost zagotovljena za zagotavljanje nabora podatkov s prilagojenim mehanizmom nalaganja.

layer

Tip: string
Privzeto: 'icons'

Sloj pravila.

customizations

Tip: Omit<IconCustomizations, 'additionalProps' | 'trimCustomSvg'>
Privzeto: undefined

Prilagoditve ikon po meri.

autoInstall

Tip: boolean
Privzeto: false

Samodejno namesti paket vira ikon, ko je zaznana uporaba.

WARNING

Samo v okolju node, v browser bo ta možnost prezrta.

unit

Tip: string
Privzeto: 'em'

Prilagojena enota ikone.

cdn

Tip: string
Privzeto: undefined

Naloži ikone s CDN. Mora se začeti s https:// in končati z /.

Priporočila:

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

customFetch

Tip: (url: string) => Promise<any>
Privzeto: undefined

Prednastavitev uporablja ofetch kot privzeti fetcher, lahko tudi prilagodite funkcijo fetch za zagotavljanje podatkov ikon.

processor

Tip: (cssObject: CSSObject, meta: Required<IconMeta>) => void
Privzeto: undefined

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

Procesor za CSS objekt pred stringifikacijo. Glej primer.

Napredno čiščenje prilagojenega nabora ikon

Pri uporabi te prednastavitve z vašimi prilagojenimi ikonami razmislite o uporabi postopka čiščenja, podobnega tistemu, ki ga izvaja Iconify za vse zbirke ikon. Vsa orodja, ki jih potrebujete, so na voljo v Iconify Tools.

Lahko preverite to repo, ki uporablja to prednastavitev v projektu Vue 3: @iconify/tools/@iconify-demo/unocss.

Za več podrobnosti preberite članek Cleaning up icons od Iconify.

Vprašanja dostopnosti

Pri uporabi ikon je pomembno upoštevati vse potencialne uporabnike. Nekateri od njih morda uporabljajo bralnike zaslona in potrebovali bodo alternativno besedilo za razumevanje pomena ikone. Uporabite lahko atribut aria-label za zagotavljanje opisa ikone:

html

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

Če je ikona zgolj dekorativna in ne potrebuje besedilne alternative, lahko uporabite aria-hidden="true" za skrivanje pred bralniki zaslona:

html

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

Obstaja še veliko drugih tehnik za zagotavljanje namigov za bralnike zaslona, na primer, Wind3 prednastavitev vključuje sr-only za skrivanje elementov vizualno, vendar jih ohranja dostopne bralnikom zaslona.

Na spletu lahko najdete veliko dobrih virov o dostopnosti ikon, CSS ikone se obnašajo kot pisave ikon, zato lahko uporabite iste tehnike, kot bi jih pri pisavah ikon.

Zahvale

Ta prednastavitev je navdihnjena iz tega issue, ki ga je ustvaril @husayt.
Temelji na delu tega PR od @userquin.

Icons prednastavitev ​

Namestitev ​

Dodatne lastnosti ​

Prekrivanje načinov ​

Konfiguriranje zbirk in razreševalnikov ikon ​

Brskalnik ​

Bundler ​

CDN ​

Prilagoditev ​

Node.js ​

FileSystemIconLoader ​

ExternalPackageIconLoader ​

Prilagoditve ikon ​

Globalna transformacija ikon po meri ​

Globalna prilagoditev ikon ​

Prilagoditev ikone/zbirke ​

Direktive ​

Možnosti ​

scale ​

mode ​

prefix ​

extraProperties ​

warn ​

iconifyCollectionsNames ​

collections ​

layer ​

customizations ​

autoInstall ​

unit ​

cdn ​

customFetch ​

processor ​

Napredno čiščenje prilagojenega nabora ikon ​

Vprašanja dostopnosti ​

Zahvale ​

Icons prednastavitev

Namestitev

Dodatne lastnosti

Prekrivanje načinov

Konfiguriranje zbirk in razreševalnikov ikon

Brskalnik

Bundler

CDN

Prilagoditev

Node.js

FileSystemIconLoader

ExternalPackageIconLoader

Prilagoditve ikon

Globalna transformacija ikon po meri

Globalna prilagoditev ikon

Prilagoditev ikone/zbirke

Direktive

Možnosti

scale

mode

prefix

extraProperties

warn

iconifyCollectionsNames

collections

layer

customizations

autoInstall

unit

cdn

customFetch

processor

Napredno čiščenje prilagojenega nabora ikon

Vprašanja dostopnosti

Zahvale