Preset Icons

Sử dụng bất kỳ biểu tượng nào với CSS Thuần cho UnoCSS.

TIP

Đọc được đề nghị: Icons in Pure CSS

Thực hiện theo các quy ước sau để sử dụng các biểu tượng

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

Ví dụ:

html

<!-- Một biểu tượng neo cơ bản từ biểu tượng Phosphor -->
<div class="i-ph-anchor-simple-thin" />
<!-- Một chiếc đồng hồ báo thức màu cam từ Material Design Icons -->
<div class="i-mdi-alarm text-orange-400" />
<!-- Một logo Vue lớn -->
<div class="i-logos-vue text-3xl" />
<!-- Mặt trời ở chế độ sáng, Mặt trăng ở chế độ tối, từ Carbon -->
<button class="i-carbon-sun dark:i-carbon-moon" />
<!-- Twemoji của cười, chuyển thành nước mắt khi di chuột qua -->
<div class="i-twemoji-grinning-face-with-smiling-eyes hover:i-twemoji-face-with-tears-of-joy" />

Hover it

Kiểm tra tất cả các biểu tượng có sẵn.

Cài đặt

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]

Chúng tôi sử dụng Iconify làm nguồn dữ liệu biểu tượng của chúng tôi. Bạn cần cài đặt bộ biểu tượng tương ứng trong devDependencies bằng cách làm theo mẫu @iconify-json/*. Ví dụ, @iconify-json/mdi cho Material Design Icons, @iconify-json/tabler cho Tabler. Bạn có thể tham khảo Icônes hoặc Iconify cho tất cả các bộ sưu tập có sẵn.

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

export default defineConfig({
  presets: [
    presetIcons({ /* các tùy chọn */ }),
    // ...các preset khác
  ],
})

TIP

Preset này được bao gồm trong gói unocss, bạn cũng có thể nhập nó từ đó:

import { presetIcons } from 'unocss'

INFO

Bạn cũng có thể sử dụng preset này một mình như một bổ sung cho các framework UI hiện có của bạn để có các biểu tượng CSS thuần!

Nếu bạn muốn cài đặt tất cả các bộ biểu tượng có sẵn trên Iconify cùng một lúc (~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

Thuộc tính Bổ sung

Bạn có thể cung cấp các thuộc tính CSS bổ sung để kiểm soát hành vi mặc định của các biểu tượng. Sau đây là một ví dụ làm cho các biểu tượng được nội tuyến theo mặc định:

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

Ghi đè Chế độ

Theo mặc định, preset này sẽ tự động chọn các chế độ kết xuất cho mỗi biểu tượng dựa trên các đặc điểm của biểu tượng. Bạn có thể đọc thêm trong bài viết blog này. Trong một số trường hợp, bạn có thể muốn đặt rõ ràng các chế độ kết xuất cho mỗi biểu tượng.

?bg cho background-img - kết xuất biểu tượng như một hình ảnh nền
?mask cho mask - kết xuất biểu tượng như một hình ảnh mặt nạ

Ví dụ, vscode-icons:file-type-light-pnpm, một biểu tượng có màu sắc (điều đó svg không chứa currentColor) sẽ được kết xuất như một hình ảnh nền. Sử dụng vscode-icons:file-type-light-pnpm?mask để kết xuất nó như một hình ảnh mặt nạ và bỏ qua màu sắc của nó.

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>

Cấu hình các bộ sưu tập và trình giải biểu tượng

Bạn có thể cung cấp các bộ sưu tập thông qua @iconify-json/[the-collection-you-want], @iconify/json hoặc sử dụng các bộ sưu tập tùy chỉnh của bạn bằng tùy chọn collections trong cấu hình UnoCSS của bạn.

Trình duyệt

Để tải các bộ sưu tập iconify bạn nên sử dụng @iconify-json/[the-collection-you-want] và không phải @iconify/json vì tệp json rất lớn.

Bundler

Khi sử dụng các bundler, bạn có thể cung cấp các bộ sưu tập sử dụng dynamic imports để chúng sẽ được bundler như một chunk không đồng bộ và được tải theo yêu cầu.

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

Hoặc nếu bạn muốn tìm nạp chúng từ CDN, bạn có thể chỉ định tùy chọn cdn kể từ v0.32.10. Chúng tôi khuyên esm.sh làm nhà cung cấp CDN.

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

Tùy chỉnh

Bạn cũng có thể cung cấp các bộ sưu tập tùy chỉnh của riêng mình bằng cách sử dụng CustomIconLoader hoặc InlineCollection, ví dụ sử dụng 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),
    /* ... */
  }
})

Và sau đó, bạn có thể sử dụng nó trong html của mình: <span class="i-custom:circle"></span>

Node.js

Trong Node.js preset sẽ tự động tìm kiếm bộ dữ liệu iconify đã cài đặt, vì vậy bạn không cần đăng ký các bộ sưu tập iconify.

Bạn cũng có thể cung cấp các bộ sưu tập tùy chỉnh của riêng mình bằng cách cũng sử dụng CustomIconLoader hoặc InlineCollection.

FileSystemIconLoader

Ngoài ra, bạn cũng có thể sử dụng FileSystemIconLoader để tải các biểu tượng tùy chỉnh của bạn từ hệ thống tệp của bạn. Bạn sẽ cần cài đặt gói @iconify/utils như dev dependency.

import fs from 'node:fs/promises'
// trình trợ giúp loader
import { FileSystemIconLoader } from '@iconify/utils/lib/loader/node-loaders'
import { defineConfig, presetIcons } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({
      collections: {
        // key như tên bộ sưu tập
        'my-icons': {
          account: '<svg><!-- ... --></svg>',
          // tải biểu tượng tùy chỉnh của bạn một cách lười biếng
          settings: () => fs.readFile('./path/to/my-icon.svg', 'utf-8'),
          /* ... */
        },
        'my-other-icons': async (iconName) => {
          // trình tải tùy chỉnh của bạn ở đây. Làm bất cứ thứ gì bạn muốn.
          // ví dụ, tìm nạp từ một máy chủ từ xa:
          return await fetch(`https://example.com/icons/${iconName}.svg`).then(res => res.text())
        },
        // một trình trợ giúp để tải các biểu tượng từ hệ thống tệp
        // các tệp trong `./assets/icons` với phần mở rộng `.svg` sẽ được tải như tên tệp của nó
        // bạn cũng có thể cung cấp một callback biến đổi để thay đổi mỗi biểu tượng (tùy chọn)
        'my-yet-other-icons': FileSystemIconLoader(
          './assets/icons',
          svg => svg.replace(/#fff/, 'currentColor')
        )
      }
    })
  ]
})

ExternalPackageIconLoader

Từ @iconify/utils v2.1.20 bạn có thể sử dụng các gói khác để tải các biểu tượng từ các tác giả khác bằng trình trợ giúp createExternalPackageIconLoader mới.

CẢNH BÁO

Các gói bên ngoài phải bao gồm tệp icons.json với dữ liệu icons ở định dạng IconifyJSON, có thể được xuất bằng Iconify Tools. Kiểm tra Xuất bộ biểu tượng như gói JSON để biết thêm chi tiết.

Ví dụ, bạn có thể sử dụng an-awesome-collection hoặc @my-awesome-collections/some-collection để tải các biểu tượng tùy chỉnh hoặc của bên thứ ba:

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

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

Bạn cũng có thể kết hợp nó với các trình tải biểu tượng tùy chỉnh khác, ví dụ:

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

Tùy chỉnh Biểu tượng

Bạn có thể tùy chỉnh tất cả các biểu tượng bằng tùy chọn cấu hình customizations.

Các hàm tùy chỉnh có sẵn:

transform: biến đổi svg thô, sẽ chỉ được áp dụng khi sử dụng bộ sưu tập biểu tượng custom (các bộ sưu tập iconify bị loại trừ).
customize: thay đổi các giá trị tùy chỉnh biểu tượng mặc định.
iconCustomizer: thay đổi các giá trị tùy chỉnh biểu tượng mặc định.

Đối với mỗi biểu tượng đã tải, các tùy chỉnh sẽ được áp dụng theo thứ tự này:

áp dụng transform cho svg thô, nếu được cung cấp và sử dụng bộ sưu tập biểu tượng tùy chỉnh
áp dụng customize với các tùy chỉnh mặc định, nếu được cung cấp
áp dụng iconCustomizer với các tùy chỉnh customize, nếu được cung cấp

Biến đổi Biểu tượng Tùy chỉnh Toàn cầu

Khi tải các biểu tượng tùy chỉnh của bạn, bạn có thể biến đổi chúng, ví dụ thêm thuộc tính fill với currentColor:

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

Từ phiên bản 0.30.8 transform cung cấp các tên collection và icon:

presetIcons({
  customizations: {
    transform(svg, collection, icon) {
      // không áp dụng fill cho các biểu tượng này trong bộ sưu tập này
      if (collection === 'custom' && icon === 'my-icon')
        return svg
      return svg.replace(/#fff/, 'currentColor')
    }
  }
})

Tùy chỉnh Biểu tượng Toàn cầu

Khi tải bất kỳ biểu tượng nào bạn có thể tùy chỉnh các thuộc tính phổ biến cho tất cả chúng, ví dụ cấu hình cùng kích thước:

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

Tùy chỉnh Biểu tượng/Bộ sưu tập

Bạn có thể tùy chỉnh mỗi biểu tượng bằng tùy chọn cấu hình iconCustomizer.

iconCustomizer sẽ có ưu tiên hơn cấu hình.

iconCustomizer sẽ được áp dụng cho bất kỳ bộ sưu tập nào, đó là, đối với mỗi biểu tượng từ trình tải custom, inlined trên custom collections hoặc từ @iconify.

Ví dụ, bạn có thể cấu hình iconCustomizer để thay đổi tất cả các biểu tượng cho một bộ sưu tập hoặc các biểu tượng riêng lẻ trên một bộ sưu tập:

presetIcons({
  customizations: {
    iconCustomizer(collection, icon, props) {
      // tùy chỉnh tất cả các biểu tượng trong bộ sưu tập này
      if (collection === 'my-other-icons') {
        props.width = '4em'
        props.height = '4em'
      }
      // tùy chỉnh biểu tượng này trong bộ sưu tập này
      if (collection === 'my-icons' && icon === 'account') {
        props.width = '6em'
        props.height = '6em'
      }
      // tùy chỉnh biểu tượng @iconify này trong bộ sưu tập này
      if (collection === 'mdi' && icon === 'account') {
        props.width = '2em'
        props.height = '2em'
      }
    }
  }
})

Chỉ thị

Bạn có thể sử dụng chỉ thị icon() trong CSS của mình để lấy siêu dữ liệu của biểu tượng.

css

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

WARNING

icon() phụ thuộc vào @unocss/preset-icons và sẽ sử dụng cấu hình, hãy đảm bảo bạn đã thêm preset này.

Thêm về chỉ thị icon(), kiểm tra Chỉ thị.

Tùy chọn

scale

Type: number
Default: 1

Quy mô liên quan đến kích thước phông chữ hiện tại (1em).

mode

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

Chế độ của các biểu tượng CSS được tạo.

TIP

mask - sử dụng màu nền và thuộc tính mask cho các biểu tượng đơn sắc
bg - sử dụng hình ảnh nền cho các biểu tượng, màu sắc tĩnh
auto - quyết định thông minh chế độ giữa mask và bg mỗi biểu tượng dựa trên phong cách của nó

prefix

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

Tiền tố lớp để khớp các quy tắc biểu tượng.

extraProperties

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

Các thuộc tính CSS bổ sung được áp dụng cho CSS được tạo.

warn

Type: boolean
Default: false

Phát ra cảnh báo khi các biểu tượng bị thiếu được khớp.

iconifyCollectionsNames

Type: string[]
Default: undefined

Các bộ sưu tập @iconify-json bổ sung để sử dụng. Tùy chọn này nên được sử dụng khi có các bộ sưu tập @iconify-json mới không được liệt kê trong các tên bộ sưu tập preset biểu tượng mặc định.

collections

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

Trong môi trường Node.js, preset sẽ tự động tìm kiếm bộ dữ liệu iconify đã cài đặt. Khi sử dụng trong trình duyệt, tùy chọn này được cung cấp để cung cấp bộ dữ liệu với cơ chế tải tùy chỉnh.

layer

Type: string
Default: 'icons'

Layer quy tắc.

customizations

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

Tùy chỉnh biểu tượng tùy chỉnh.

autoInstall

Type: boolean
Default: false

Tự động cài đặt gói nguồn biểu tượng khi các cách sử dụng được phát hiện.

WARNING

Chỉ trên môi trường node, trên browser tùy chọn này sẽ bị bỏ qua.

unit

Type: string
Default: 'em'

Đơn vị biểu tượng tùy chỉnh.

cdn

Type: string
Default: undefined

Tải các biểu tượng từ CDN. Nên bắt đầu bằng https:// và kết thúc bằng /.

Đề nghị:

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

customFetch

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

Preset sử dụng ofetch làm trình tìm nạp mặc định, bạn cũng có thể tùy chỉnh hàm tìm nạp để cung cấp dữ liệu biểu tượng.

processor

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

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

Trình xử lý cho đối tượng CSS trước khi stringify. Xem ví dụ.

Dọn dẹp Bộ Biểu tượng Tùy chỉnh Nâng cao

Khi sử dụng preset này với các biểu tượng tùy chỉnh của bạn, hãy xem xét sử dụng một quy trình dọn dẹp tương tự như được thực hiện bởi Iconify cho bất kỳ bộ biểu tượng nào. Tất cả các công cụ bạn cần đều có sẵn trong Iconify Tools.

Bạn có thể kiểm tra repo này, sử dụng preset này trên một dự án Vue 3: @iconify/tools/@iconify-demo/unocss.

Đọc bài viết Dọn dẹp các biểu tượng từ Iconify để biết thêm chi tiết.

Vấn đề về Trả phí

Khi sử dụng các biểu tượng, điều quan trọng là phải tính đến tất cả người dùng tiềm năng của bạn. Một số người trong số họ có thể đang sử dụng trình đọc màn hình, và họ sẽ cần một văn bản thay thế để hiểu một biểu tượng có nghĩa là gì. Bạn có thể sử dụng thuộc tính aria-label để cung cấp một mô tả về biểu tượng:

html

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

Nếu biểu tượng hoàn toàn trang trí và không cần một văn bản thay thế, bạn có thể sử dụng aria-hidden="true" để ẩn nó khỏi các trình đọc màn hình:

html

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

Có nhiều kỹ thuật khác để cung cấp văn bản gợi ý cho các trình đọc màn hình, ví dụ, preset Wind3 bao gồm sr-only để ẩn các phần tử trực quan nhưng giữ chúng có thể truy cập được cho các trình đọc màn hình.

Bạn có thể tìm thấy một số tài nguyên tốt trên web về khả năng truy cập biểu tượng, và các biểu tượng CSS hoạt động như các phông chữ biểu tượng, vì vậy bạn có thể sử dụng cùng các kỹ thuật như bạn sẽ làm với các phông chữ biểu tượng.

Tín nhiệm

Preset này lấy cảm hứng từ vấn đề này được tạo bởi @husayt.
Dựa trên công việc của PR này bởi @userquin.

Preset Icons ​

Cài đặt ​

Thuộc tính Bổ sung ​

Ghi đè Chế độ ​

Cấu hình các bộ sưu tập và trình giải biểu tượng ​

Trình duyệt ​

Bundler ​

CDN ​

Tùy chỉnh ​

Node.js ​

FileSystemIconLoader ​

ExternalPackageIconLoader ​

Tùy chỉnh Biểu tượng ​

Biến đổi Biểu tượng Tùy chỉnh Toàn cầu ​

Tùy chỉnh Biểu tượng Toàn cầu ​

Tùy chỉnh Biểu tượng/Bộ sưu tập ​

Chỉ thị ​

Tùy chọn ​

scale ​

mode ​

prefix ​

extraProperties ​

warn ​

iconifyCollectionsNames ​

collections ​

layer ​

customizations ​

autoInstall ​

unit ​

cdn ​

customFetch ​

processor ​

Dọn dẹp Bộ Biểu tượng Tùy chỉnh Nâng cao ​

Vấn đề về Trả phí ​

Tín nhiệm ​

Preset Icons

Cài đặt

Thuộc tính Bổ sung

Ghi đè Chế độ

Cấu hình các bộ sưu tập và trình giải biểu tượng

Trình duyệt

Bundler

CDN

Tùy chỉnh

Node.js

FileSystemIconLoader

ExternalPackageIconLoader

Tùy chỉnh Biểu tượng

Biến đổi Biểu tượng Tùy chỉnh Toàn cầu

Tùy chỉnh Biểu tượng Toàn cầu

Tùy chỉnh Biểu tượng/Bộ sưu tập

Chỉ thị

Tùy chọn

scale

mode

prefix

extraProperties

warn

iconifyCollectionsNames

collections

layer

customizations

autoInstall

unit

cdn

customFetch

processor

Dọn dẹp Bộ Biểu tượng Tùy chỉnh Nâng cao

Vấn đề về Trả phí

Tín nhiệm