การแยก (Extracting)

UnoCSS ทำงานโดยการค้นหาการใช้งาน utilities จาก codebase ของคุณและสร้าง CSS ที่สอดคล้องกันแบบ on-demand เราเรียกกระบวนการนี้ว่า extracting

แหล่งที่มาของเนื้อหา

UnoCSS รองรับการแยกการใช้งาน utilities จากหลายแหล่ง:

• Pipeline - แยกโดยตรงจาก pipeline ของเครื่องมือสร้างของคุณ
• Filesystem - แยกจาก filesystem ของคุณโดยการอ่านและเฝ้าดูไฟล์
• Inline - แยกจากข้อความ plain text แบบ inline

การใช้งาน utilities ที่มาจากแหล่งต่างๆ จะถูกรวมเข้าด้วยกันและสร้าง CSS สุดท้าย

การแยกจาก Build Tools Pipeline

นี่ได้รับการสนับสนุนในการผสานรวม Vite และ Webpack

UnoCSS จะอ่านเนื้อหาที่ผ่าน pipeline ของเครื่องมือสร้างของคุณและแยกการใช้งาน utilities จากมัน นี่เป็นวิธีที่มีประสิทธิภาพและแม่นยำที่สุดในการแยก เนื่องจากเราแยกเฉพาะการใช้งานที่ถูกใช้จริงในแอปของคุณอย่างชาญฉลาดโดยไม่มีการทำ I/O ไฟล์เพิ่มเติมในระหว่างการแยก

โดยค่าเริ่มต้น UnoCSS จะแยกการใช้งาน utilities จากไฟล์ใน pipeline การสร้างของคุณด้วยนามสกุล .jsx, .tsx, .vue, .md, .html, .svelte, .astro และสร้าง CSS ที่เหมาะสมแบบ on demand ไฟล์ .js และ .ts ไม่รวมโดยค่าเริ่มต้น

เพื่อกำหนดค่า คุณสามารถอัปเดต uno.config.ts ของคุณ:

export default defineConfig({
  content: {
    pipeline: {
      include: [
        // ค่าเริ่มต้น
        /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
        // รวมไฟล์ js/ts
        'src/**/*.{js,ts}',
      ],
      // ยกเว้นไฟล์
      // exclude: []
    },
  },
})

คุณยังสามารถเพิ่มคอมเมนต์ magic @unocss-include ได้ ต่อไฟล์ ที่ใดก็ได้ในไฟล์ที่คุณต้องการให้ UnoCSS สแกน หากคุณต้องการสแกนไฟล์ *.js หรือ *.ts เพิ่มมันในการกำหนดค่าเพื่อรวมไฟล์ js/ts ทั้งหมดเป็นเป้าหมายการสแกน

// ./some-utils.js

// เนื่องจากไฟล์ `.js` ไม่รวมโดยค่าเริ่มต้น
// คอมเมนต์ต่อไปนี้บอกให้ UnoCSS บังคับสแกนไฟล์นี้
// @unocss-include
export const classes = {
  active: 'bg-primary text-white',
  inactive: 'bg-gray-200 text-gray-500',
}

ในทำนองเดียวกัน คุณยังสามารถเพิ่ม @unocss-ignore เพื่อข้ามการสแกนและการแปลงสำหรับทั้งไฟล์ได้

หากคุณต้องการให้ UnoCSS ข้ามบล็อกของโค้ดโดยไม่ถูกแยกในไฟล์การแยกใดๆ คุณสามารถใช้ @unocss-skip-start @unocss-skip-end เป็นคู่ โปรดทราบว่าต้องใช้ เป็นคู่ จึงจะมีประสิทธิภาพ

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

<!-- @unocss-skip-start -->
<!-- `text-red` จะไม่ถูกแยก -->
<p class="text-red">Red</p>
<!-- @unocss-skip-end -->

การแยกจาก Filesystem

ในกรณีที่คุณใช้การผสานรวมที่ไม่มีการเข้าถึง pipeline ของเครื่องมือสร้าง (ตัวอย่างเช่น PostCSS plugin) หรือคุณกำลังผสานรวมกับเฟรมเวิร์ก backend เพื่อให้โค้ดไม่ผ่าน pipeline คุณสามารถระบุไฟล์ที่จะแยกได้ด้วยตนเอง

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

ไฟล์ที่ตรงกันจะถูกอ่านโดยตรงจาก filesystem และเฝ้าดูการเปลี่ยนแปลงในโหมด dev

การแยกจาก Inline Text

นอกจากนี้ คุณยังสามารถแยกการใช้งาน utilities จากข้อความ inline ที่คุณอาจดึงมาจากที่อื่นได้

คุณยังสามารถส่งฟังก์ชัน async เพื่อส่งคืนเนื้อหาได้ แต่โปรดทราบว่าฟังก์ชันจะถูกเรียกเพียงครั้งเดียวในเวลาสร้าง

export default defineConfig({
  content: {
    inline: [
      // ข้อความ plain
      '<div class="p-4 text-red">Some text</div>',
      // async getter
      async () => {
        const response = await fetch('https://example.com')
        return response.text()
      },
    ],
  },
})

ข้อจำกัด

เนื่องจาก UnoCSS ทำงาน ในเวลาสร้าง ซึ่งหมายความว่ามีเฉพาะ utilities ที่แสดงแบบ static เท่านั้นที่จะถูกสร้างและส่งไปยังแอปของคุณ Utilities ที่ใช้แบบไดนามิกหรือดึงมาจากแหล่งภายนอกในเวลารันไทม์อาจ ไม่ ถูกตรวจพบหรือนำไปใช้

Safelist

บางครั้งคุณอาจต้องการใช้การต่อข้อความแบบไดนามิก เช่น:

<div class="p-${size}"></div>
<!-- นี่จะไม่ทำงาน! -->

เนื่องจาก UnoCSS ทำงานในเวลาสร้างโดยใช้การแยกแบบ static ในเวลาคอมไพล์ มันไม่สามารถรู้ทุกการรวมกันของ utilities ได้ สำหรับสิ่งนั้น คุณสามารถกำหนดค่าตัวเลือก safelist

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

CSS ที่สอดคล้องกันจะถูกสร้างเสมอ:

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

หรือยืดหยุ่นมากขึ้น:

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

หากคุณกำลังมองหาการสร้างแบบไดนามิกที่แท้จริงในเวลารันไทม์ คุณอาจต้องการดูแพ็คเกจ @unocss/runtime

การรวมกันแบบรายการ Static

วิธีอื่นในการแก้ไขข้อจำกัดของ utilities ที่สร้างแบบไดนามิกคือคุณสามารถใช้อ็อบเจกต์ที่แสดงรายการการรวมกันทั้งหมด แบบ static ตัวอย่างเช่น หากคุณต้องการมีสิ่งนี้:

<div class="text-${color} border-${color}"></div>
<!-- นี่จะไม่ทำงาน! -->

คุณสามารถสร้างอ็อบเจกต์ที่แสดงรายการการรวมกันทั้งหมด (สมมติว่าคุณรู้ค่าที่เป็นไปได้ทั้งหมดของ color ที่คุณต้องการใช้)

// เนื่องจากพวกมันเป็นแบบ static UnoCSS จะสามารถแยกพวกมันได้ในเวลาสร้าง
const classes = {
  red: 'text-red border-red',
  green: 'text-green border-green',
  blue: 'text-blue border-blue',
}

และจากนั้นใช้มันในเทมเพลตของคุณ:

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

Blocklist

คล้ายกับ safelist คุณยังสามารถกำหนดค่า blocklist เพื่อยกเว้น utilities บางตัวจากการสร้าง นี่มีประโยชน์ในการยกเว้น false positives ของการแยก แตกต่างจาก safelist blocklist ยอมรับทั้งสตริงสำหรับการจับคู่ที่แน่นอนและ regular expression สำหรับการจับคู่รูปแบบ

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

นี่จะยกเว้น p-1 และ p-2, p-3, p-4 จากการสร้าง