إعداد الأيقونات المسبق

استخدام أي أيقونة مع CSS الخالص لـ UnoCSS.

TIP

اتبع الاتفاقيات التالية لاستخدام الأيقونات

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

على سبيل المثال:

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

تحقق من جميع الأيقونات المتاحة.

التثبيت

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]

نستخدم Iconify كمصدر بياناتنا للأيقونات. تحتاج إلى تثبيت مجموعة الأيقونات المقابلة في devDependencies باتباع نمط @iconify-json/*. على سبيل المثال، @iconify-json/mdi لـ Material Design Icons، @iconify-json/tabler لـ Tabler. يمكنك الرجوع إلى Icônes أو Iconify لجميع المجموعات المتاحة.

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

export default defineConfig({
  presets: [
    presetIcons({ /* options */ }),
    // ...other presets
  ],
})

TIP

يتم تضمين هذا الإعداد المسبق في حزمة unocss، يمكنك أيضاً استيراده من هناك:

import { presetIcons } from 'unocss'

INFO

يمكنك أيضاً استخدام هذا الإعداد المسبق بمفرده كمكمل لأطر UI الموجودة لديك للحصول على أيقونات CSS خالصة!

إذا كنت تفضل تثبيت جميع مجموعات الأيقونات المتاحة على Iconify دفعة واحدة (~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

الخصائص الإضافية

يمكنك توفير خصائص CSS الإضافية للتحكم في السلوك الافتراضي للأيقونات. فيما يلي مثال لجعل الأيقونات مضمنة افتراضياً:

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

تجاوز الأوضاع

افتراضياً، سيختار هذا الإعداد المسبق أوضاع العرض تلقائياً لكل أيقونة بناءً على خصائص الأيقونات. يمكنك قراءة المزيد في منشور المدونة هذا. في بعض الحالات، قد ترغب في تعيين أوضاع العرض صراحة لكل أيقونة.

?bg لـ background-img - يعرض الأيقونة كصورة خلفية
?mask لـ mask - يعرض الأيقونة كصورة قناع

على سبيل المثال، vscode-icons:file-type-light-pnpm، أيقونة بألوان (لا يحتوي svg على currentColor) سيتم عرضها كصورة خلفية. استخدم vscode-icons:file-type-light-pnpm?mask لعرضها كصورة قناع وتجاوز ألوانها.

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>

تكوين المجموعات وحلول الأيقونات

يمكنك توفير المجموعات عبر @iconify-json/[the-collection-you-want] أو @iconify/json أو استخدام المجموعات المخصصة الخاصة بك باستخدام خيار collections في تكوين UnoCSS الخاص بك.

المتصفح

لتحميل مجموعات iconify يجب عليك استخدام @iconify-json/[the-collection-you-want] وليس @iconify/json نظراً لأن ملف json ضخم.

Bundler

عند استخدام bundlers، يمكنك توفير المجموعات باستخدام dynamic imports بحيث يتم تجميعها كـ async chunk وتحميلها عند الطلب.

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

أو إذا كنت تفضل جلبها من CDN، يمكنك تحديد خيار cdn منذ v0.32.10. نوصي بـ esm.sh كمزود CDN.

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

التخصيص

يمكنك أيضاً توفير مجموعاتك المخصصة الخاصة باستخدام CustomIconLoader أو InlineCollection، على سبيل المثال استخدام 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),
    /* ... */
  }
})

وبعد ذلك، يمكنك استخدامه في HTML الخاص بك: <span class="i-custom:circle"></span>

Node.js

في Node.js سيبحث الإعداد المسبق تلقائياً عن مجموعة بيانات iconify المثبتة، لذا لا تحتاج إلى تسجيل مجموعات iconify.

يمكنك أيضاً توفير مجموعاتك المخصصة الخاصة باستخدام CustomIconLoader أو InlineCollection.

FileSystemIconLoader

بالإضافة إلى ذلك، يمكنك أيضاً استخدام FileSystemIconLoader لتحميل أيقوناتك المخصصة من نظام الملفات الخاص بك. ستحتاج إلى تثبيت حزمة @iconify/utils كتبعية تطوير.

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

من @iconify/utils v2.1.20 يمكنك استخدام حزم أخرى لتحميل الأيقونات من مؤلفين آخرين باستخدام المساعد الجديد createExternalPackageIconLoader.

تحذير

يجب أن تتضمن الحزم الخارجية ملف icons.json مع بيانات icons بتنسيق IconifyJSON، والذي يمكن تصديره باستخدام Iconify Tools. راجع تصدير مجموعة الأيقونات كحزمة JSON لمزيد من التفاصيل.

على سبيل المثال، يمكنك استخدام an-awesome-collection أو @my-awesome-collections/some-collection لتحميل أيقوناتك المخصصة أو التابعة لجهات خارجية:

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

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

You can also combine it with other custom icon loaders, for example:

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

تخصيصات الأيقونات

يمكنك تخصيص جميع الأيقونات باستخدام خيار تكوين customizations.

الدوال المتاحة للتخصيص:

transform: تحويل svg الخام، سيتم تطبيقه فقط عند استخدام مجموعة أيقونات custom (مجموعات iconify مستبعدة).
customize: تغيير قيم تخصيصات الأيقونة الافتراضية.
iconCustomizer: تغيير قيم تخصيصات الأيقونة الافتراضية.

لكل أيقونة محملة، سيتم تطبيق التخصيصات بهذا الترتيب:

تطبيق transform على svg الخام، إذا تم توفيره واستخدام مجموعة أيقونات مخصصة
تطبيق customize مع التخصيصات الافتراضية، إذا تم توفيره
تطبيق iconCustomizer مع تخصيصات customize، إذا تم توفيره

تحويل الأيقونات المخصصة العالمية

عند تحميل أيقوناتك المخصصة، يمكنك تحويلها، على سبيل المثال إضافة سمة fill مع currentColor:

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

من الإصدار 0.30.8 يوفر transform أسماء collection و 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')
    }
  }
})

تخصيص الأيقونة العالمية

عند تحميل أي أيقونة يمكنك تخصيص الخصائص المشتركة لجميعها، على سبيل المثال تكوين نفس الحجم:

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

تخصيص الأيقونة/المجموعة

يمكنك تخصيص كل أيقونة باستخدام خيار تكوين iconCustomizer.

سيأخذ iconCustomizer الأولوية على التكوين.

سيتم تطبيق iconCustomizer على أي مجموعة، أي لكل أيقونة من محمل custom، inlined على custom collections أو من @iconify.

على سبيل المثال، يمكنك تكوين iconCustomizer لتغيير جميع الأيقونات لمجموعة أو أيقونات فردية في مجموعة:

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

التوجيهات

يمكنك استخدام توجيه icon() في CSS الخاص بك للحصول على بيانات وصفية للأيقونة.

css

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

WARNING

icon() يعتمد على @unocss/preset-icons وسيستخدم التكوين، تأكد من إضافة هذا الإعداد المسبق.

المزيد حول توجيه icon()، راجع التوجيهات.

الخيارات

scale

النوع: number
افتراضي: 1

المقياس المتعلق بحجم الخط الحالي (1em).

mode

النوع: 'mask' | 'bg' | 'auto'
افتراضي: 'auto'
راجع: https://antfu.me/posts/icons-in-pure-css

وضع أيقونات CSS المُنشأة.

TIP

mask - استخدام لون الخلفية وخاصية mask للأيقونات أحادية اللون
bg - استخدام صورة الخلفية للأيقونات، الألوان ثابتة
auto - تحديد الوضع بذكاء بين mask و bg لكل أيقونة بناءً على نمطها

prefix

النوع: string | string[]
افتراضي: 'i-'

بادئة الفئة لمطابقة قواعد الأيقونة.

extraProperties

النوع: Record<string, string>
افتراضي: {}

خصائص CSS إضافية مطبقة على CSS المُنشأ.

warn

النوع: boolean
افتراضي: false

إصدار تحذير عند مطابقة الأيقونات المفقودة.

iconifyCollectionsNames

النوع: string[]
افتراضي: undefined

مجموعات @iconify-json إضافية للاستخدام. يجب استخدام هذا الخيار عندما تكون هناك مجموعات @iconify-json جديدة غير مدرجة في أسماء مجموعات إعداد الأيقونات الافتراضي.

collections

النوع: Record<string, (() => Awaitable<IconifyJSON>) | undefined | CustomIconLoader | InlineCollection>
افتراضي: undefined

في بيئة Node.js، سيبحث الإعداد المسبق تلقائياً عن مجموعة بيانات iconify المثبتة. عند الاستخدام في المتصفح، يتم توفير هذا الخيار لتوفير مجموعة البيانات مع آلية تحميل مخصصة.

layer

النوع: string
افتراضي: 'icons'

طبقة القاعدة.

customizations

النوع: Omit<IconCustomizations, 'additionalProps' | 'trimCustomSvg'>
افتراضي: undefined

تخصيصات الأيقونة المخصصة.

autoInstall

النوع: boolean
افتراضي: false

تثبيت حزمة مصادر الأيقونات تلقائياً عند اكتشاف الاستخدامات.

WARNING

فقط في بيئة node، في browser سيتم تجاهل هذا الخيار.

unit

النوع: string
افتراضي: 'em'

وحدة الأيقونة المخصصة.

cdn

النوع: string
افتراضي: undefined

تحميل الأيقونات من CDN. يجب أن يبدأ بـ https:// وينتهي بـ /.

موصى به:

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

customFetch

النوع: (url: string) => Promise<any>
افتراضي: undefined

يستخدم الإعداد المسبق ofetch كجالب افتراضي، يمكنك أيضاً تخصيص دالة الجلب لتوفير بيانات الأيقونة.

processor

النوع: (cssObject: CSSObject, meta: Required<IconMeta>) => void
افتراضي: undefined

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

معالج لكائن CSS قبل التحويل إلى سلسلة. راجع المثال.

تنظيف مجموعة الأيقونات المخصصة المتقدم

عند استخدام هذا الإعداد المسبق مع أيقوناتك المخصصة، فكر في استخدام عملية تنظيف مشابهة لتلك التي يقوم بها Iconify لأي مجموعات أيقونات. جميع الأدوات التي تحتاجها متاحة في Iconify Tools.

يمكنك التحقق من هذا المستودع، باستخدام هذا الإعداد المسبق في مشروع Vue 3: @iconify/tools/@iconify-demo/unocss.

اقرأ مقالة تنظيف الأيقونات من Iconify لمزيد من التفاصيل.

مخاوف إمكانية الوصول

عند استخدام الأيقونات، من المهم مراعاة جميع المستخدمين المحتملين. قد يستخدم بعضهم قارئات الشاشة، وسيحتاجون إلى نص بديل لفهم معنى الأيقونة. يمكنك استخدام سمة aria-label لتوفير وصف للأيقونة:

html

<a href="/profile" aria-label="الملف الشخصي" class="i-ph:user-duotone"></a>

إذا كانت الأيقونة زخرفية بحتة ولا تحتاج إلى نص بديل، يمكنك استخدام aria-hidden="true" لإخفائها عن قارئات الشاشة:

html

<a href="/profile">
  <span aria-hidden="true" class="i-ph:user-duotone"></span>
  ملفي الشخصي
</a>

هناك العديد من التقنيات الأخرى لتوفير نص تلميح لقارئات الشاشة، على سبيل المثال، يتضمن إعداد Wind3 المسبق sr-only لإخفاء العناصر بصرياً ولكن الحفاظ على إمكانية الوصول إليها لقارئات الشاشة.

يمكنك العثور على بعض الموارد الجيدة على الويب حول إمكانية الوصول للأيقونات، وتتصرف أيقونات CSS مثل خطوط الأيقونات، لذا يمكنك استخدام نفس التقنيات كما تفعل مع خطوط الأيقونات.

الاعتمادات

هذا الإعداد المسبق مستوحى من هذه المشكلة التي أنشأها @husayt.
يعتمد على عمل هذا PR بواسطة @userquin.

إعداد الأيقونات المسبق ​

التثبيت ​

الخصائص الإضافية ​

تجاوز الأوضاع ​

تكوين المجموعات وحلول الأيقونات ​

المتصفح ​

Bundler ​

CDN ​

التخصيص ​

Node.js ​

FileSystemIconLoader ​

ExternalPackageIconLoader ​

تخصيصات الأيقونات ​

تحويل الأيقونات المخصصة العالمية ​

تخصيص الأيقونة العالمية ​

تخصيص الأيقونة/المجموعة ​

التوجيهات ​

الخيارات ​

scale ​

mode ​

prefix ​

extraProperties ​

warn ​

iconifyCollectionsNames ​

collections ​

layer ​

customizations ​

autoInstall ​

unit ​

cdn ​

customFetch ​

processor ​

تنظيف مجموعة الأيقونات المخصصة المتقدم ​

مخاوف إمكانية الوصول ​

الاعتمادات ​

إعداد الأيقونات المسبق

التثبيت

الخصائص الإضافية

تجاوز الأوضاع

تكوين المجموعات وحلول الأيقونات

المتصفح

Bundler

CDN

التخصيص

Node.js

FileSystemIconLoader

ExternalPackageIconLoader

تخصيصات الأيقونات

تحويل الأيقونات المخصصة العالمية

تخصيص الأيقونة العالمية

تخصيص الأيقونة/المجموعة

التوجيهات

الخيارات

scale

mode

prefix

extraProperties

warn

iconifyCollectionsNames

collections

layer

customizations

autoInstall

unit

cdn

customFetch

processor

تنظيف مجموعة الأيقونات المخصصة المتقدم

مخاوف إمكانية الوصول

الاعتمادات