Trích xuất

UnoCSS hoạt động bằng cách tìm kiếm các cách sử dụng tiện ích từ cơ sở mã của bạn và tạo CSS tương ứng theo yêu cầu. Chúng tôi gọi quy trình này là trích xuất.

Nguồn nội dung

UnoCSS hỗ trợ trích xuất các cách sử dụng tiện ích từ nhiều nguồn:

• Pipeline - Trích xuất ngay từ pipeline của công cụ xây dựng của bạn
• Filesystem - Trích xuất từ hệ thống tệp của bạn bằng cách đọc và theo dõi các tệp
• Inline - Trích xuất từ văn bản thuần nội tuyến

Các cách sử dụng tiện ích đến từ các nguồn khác nhau sẽ được hợp nhất lại và tạo CSS cuối cùng.

Trích xuất từ Pipeline công cụ xây dựng

Điều này được hỗ trợ trong các tích hợp Vite và Webpack.

UnoCSS sẽ đọc nội dung đi qua pipeline của công cụ xây dựng của bạn và trích xuất các cách sử dụng tiện ích từ chúng. Đây là cách trích xuất hiệu quả và chính xác nhất vì chúng tôi chỉ trích xuất các cách sử dụng thực sự được sử dụng trong ứng dụng của bạn một cách thông minh mà không cần thực hiện I/O tệp bổ sung trong quá trình trích xuất.

Theo mặc định, UnoCSS sẽ trích xuất cách sử dụng tiện ích từ các tệp trong pipeline xây dựng của bạn có phần mở rộng .jsx, .tsx, .vue, .md, .html, .svelte, .astro và sau đó tạo CSS phù hợp theo yêu cầu. Các tệp .js và .ts không được bao gồm theo mặc định.

Để cấu hình chúng, bạn có thể cập nhật uno.config.ts của mình:

export default defineConfig({
  content: {
    pipeline: {
      include: [
        // mặc định
        /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
        // bao gồm các tệp js/ts
        'src/**/*.{js,ts}',
      ],
      // loại trừ các tệp
      // exclude: []
    },
  },
})

Bạn cũng có thể thêm bình luận ma thuật @unocss-include, theo từng tệp, bất cứ đâu trong tệp mà bạn muốn UnoCSS quét. Nếu bạn cần quét các tệp *.js hoặc *.ts, hãy thêm chúng vào cấu hình để bao gồm tất cả các tệp js/ts làm mục tiêu quét.

// ./some-utils.js

// vì các tệp `.js` không được bao gồm theo mặc định,
// bình luận sau đây cho UnoCSS biết để buộc quét tệp này.
// @unocss-include
export const classes = {
  active: 'bg-primary text-white',
  inactive: 'bg-gray-200 text-gray-500',
}

Tương tự, bạn cũng có thể thêm @unocss-ignore để bỏ qua việc quét và biến đổi cho toàn bộ tệp.

Nếu bạn muốn UnoCSS bỏ qua một khối mã mà không bị trích xuất trong bất kỳ tệp trích xuất nào, bạn có thể sử dụng @unocss-skip-start @unocss-skip-end theo cặp. Lưu ý rằng nó phải được sử dụng theo cặp để có hiệu lực.

<p class="text-green text-xl">Green Large</p>

<!-- @unocss-skip-start -->
<!-- `text-red` sẽ không được trích xuất -->
<p class="text-red">Red</p>
<!-- @unocss-skip-end -->

Trích xuất từ Hệ thống tệp

Trong trường hợp bạn đang sử dụng các tích hợp không có quyền truy cập vào pipeline công cụ xây dựng (ví dụ: plugin PostCSS), hoặc bạn đang tích hợp với các framework backend sao cho mã không đi qua pipeline, bạn có thể chỉ định thủ công các tệp cần trích xuất.

export default defineConfig({
  content: {
    filesystem: [
      'src/**/*.php',
      'public/*.html',
    ],
  },
})

Các tệp khớp sẽ được đọc trực tiếp từ hệ thống tệp và được theo dõi thay đổi ở chế độ phát triển.

Trích xuất từ Văn bản nội tuyến

Ngoài ra, bạn cũng có thể trích xuất các cách sử dụng tiện ích từ văn bản nội tuyến, mà bạn có thể truy xuất từ nơi khác.

Bạn cũng có thể truyền một hàm không đồng bộ để trả về nội dung. Nhưng lưu ý rằng hàm sẽ chỉ được gọi một lần tại thời điểm xây dựng.

export default defineConfig({
  content: {
    inline: [
      // văn bản thuần
      '<div class="p-4 text-red">Some text</div>',
      // getter không đồng bộ
      async () => {
        const response = await fetch('https://example.com')
        return response.text()
      },
    ],
  },
})

Hạn chế

Vì UnoCSS hoạt động tại thời điểm xây dựng, điều đó có nghĩa là chỉ các tiện ích được trình bày tĩnh sẽ được tạo và gửi đến ứng dụng của bạn. Các tiện ích được sử dụng động hoặc được tìm nạp từ các nguồn bên ngoài tại thời gian chạy có thể không được phát hiện hoặc áp dụng.

Danh sách an toàn

Đôi khi bạn có thể muốn sử dụng các phép nối động như:

<div class="p-${size}"></div>
<!-- điều này sẽ không hoạt động! -->

Do thực tế UnoCSS hoạt động tại thời điểm xây dựng bằng cách sử dụng trích xuất tĩnh, tại thời điểm biên dịch nó không thể biết tất cả các kết hợp của các tiện ích sau đó. Đối với điều đó, bạn có thể cấu hình tùy chọn safelist.

safelist: 'p-1 p-2 p-3 p-4'.split(' ')

CSS tương ứng sẽ luôn được tạo:

.p-1 { padding: 0.25rem; }
.p-2 { padding: 0.5rem; }
.p-3 { padding: 0.75rem; }
.p-4 { padding: 1rem; }

Hoặc linh hoạt hơn:

safelist: [
  ...Array.from({ length: 4 }, (_, i) => `p-${i + 1}`),
]

Nếu bạn đang tìm kiếm việc tạo động thực sự tại thời gian chạy, bạn có thể muốn xem gói @unocss/runtime.

Kết hợp Danh sách Tĩnh

Một cách khác để giải quyết hạn chế của các tiện ích được xây dựng động là bạn có thể sử dụng một đối tượng liệt kê tất cả các kết hợp tĩnh. Ví dụ, nếu bạn muốn có cái này:

<div class="text-${color} border-${color}"></div>
<!-- điều này sẽ không hoạt động! -->

Bạn có thể tạo một đối tượng liệt kê tất cả các kết hợp (giả sử bạn biết bất kỳ giá trị có thể có của color mà bạn muốn sử dụng)

// Vì chúng là tĩnh, UnoCSS sẽ có thể trích xuất chúng tại thời điểm xây dựng
const classes = {
  red: 'text-red border-red',
  green: 'text-green border-green',
  blue: 'text-blue border-blue',
}

Và sau đó sử dụng nó trong mẫu của bạn:

<div class="${classes[color]}"></div>

Danh sách chặn

Tương tự như safelist, bạn cũng có thể cấu hình blocklist để loại trừ một số tiện ích khỏi việc được tạo. Điều này hữu ích để loại trừ một số dương giả trích xuất. Khác với safelist, blocklist chấp nhận cả chuỗi cho khớp chính xác và biểu thức chính quy cho khớp mẫu.

blocklist: [
  'p-1',
  /^p-[2-4]$/,
]

Điều này sẽ loại trừ p-1 và p-2, p-3, p-4 khỏi việc được tạo.