الاستخراج

يعمل UnoCSS من خلال البحث عن استخدامات الأدوات من قاعدة الكود الخاصة بك وإنشاء CSS المقابل عند الطلب. نسمي هذه العملية الاستخراج.

مصادر المحتوى

يدعم UnoCSS استخراج استخدامات الأدوات من مصادر متعددة:

• خط أنابيب - استخراج مباشرة من خط أنابيب أدوات البناء الخاصة بك
• نظام الملفات - استخراج من نظام الملفات الخاص بك عن طريق قراءة ومراقبة الملفات
• مضمن - استخراج من نص عادي مضمن

سيتم دمج استخدامات الأدوات التي تأتي من مصادر مختلفة معاً وإنشاء CSS النهائي.

الاستخراج من خط أنابيب أدوات البناء

هذا مدعوم في تكاملات Vite و Webpack.

سوف يقرأ UnoCSS المحتوى الذي يمر عبر خط أنابيب أدوات البناء الخاصة بك ويستخرج استخدامات الأدوات منها. هذه هي الطريقة الأكثر كفاءة ودقة للاستخراج حيث نستخرج فقط الاستخدامات التي يتم استخدامها فعلياً في تطبيقك بذكاء دون إجراء أي I/O ملف إضافي أثناء الاستخراج.

افتراضياً، سوف يستخرج UnoCSS استخدام الأدوات من الملفات في خط أنابيب البناء الخاص بك بامتداد .jsx و .tsx و .vue و .md و .html و .svelte و .astro ثم ينشئ CSS المناسب عند الطلب. ملفات .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: []
    },
  },
})

يمكنك أيضاً إضافة تعليق سحري @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">أخضر كبير</p>

<!-- @unocss-skip-start -->
<!-- لن يتم استخراج `text-red` -->
<p class="text-red">أحمر</p>
<!-- @unocss-skip-end -->

الاستخراج من نظام الملفات

في الحالات التي تستخدم فيها تكاملات لا تحتوي على وصول إلى خط أنابيب أدوات البناء (على سبيل المثال، مكون PostCSS الإضافي)، أو تقوم بالتكامل مع أطر الخلفية بحيث لا يمر الكود عبر خط الأنابيب، يمكنك تحديد الملفات المراد استخراجها يدوياً.

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

سيتم قراءة الملفات المطابقة مباشرة من نظام الملفات ومراقبتها للتغييرات في وضع التطوير.

الاستخراج من النص المضمن

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

يمكنك أيضاً تمرير دالة غير متزامنة لإرجاع المحتوى. لكن لاحظ أن الدالة سيتم استدعاؤها مرة واحدة فقط في وقت البناء.

export default defineConfig({
  content: {
    inline: [
      // نص عادي
      '<div class="p-4 text-red">بعض النص</div>',
      // getter غير متزامن
      async () => {
        const response = await fetch('https://example.com')
        return response.text()
      },
    ],
  },
})

القيود

نظراً لأن UnoCSS يعمل في وقت البناء، فهذا يعني أنه سيتم إنشاء وتوصيل الأدوات المقدمة بشكل ثابت فقط إلى تطبيقك. قد لا يتم اكتشاف أو تطبيق الأدوات المستخدمة ديناميكياً أو المسترجعة من موارد خارجية في وقت التشغيل.

قائمة الأمان

أحياناً قد ترغب في استخدام عمليات سلسلة ديناميكية مثل:

<div class="p-${size}"></div>
<!-- هذا لن يعمل! -->

نظراً لحقيقة أن UnoCSS يعمل في وقت البناء باستخدام الاستخراج الثابت، في وقت التجميع لا يمكنه معرفة جميع مجموعات الأدوات. لذلك، يمكنك تكوين خيار 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.

مجموعات القائمة الثابتة

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

<div class="text-${color} border-${color}"></div>
<!-- هذا لن يعمل! -->

يمكنك إنشاء كائن يسرد جميع المجموعات (بافتراض أنك تعرف أي قيم محتملة لـ color تريد استخدامها)

// نظراً لأنها ثابتة، سيكون UnoCSS قادراً على استخراجها في وقت البناء
const classes = {
  red: 'text-red border-red',
  green: 'text-green border-green',
  blue: 'text-blue border-blue',
}

ثم استخدمه في القالب الخاص بك:

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

قائمة الحظر

مشابه لـ safelist، يمكنك أيضاً تكوين blocklist لاستبعاد بعض الأدوات من التوليد. هذا مفيد لاستبعاد بعض الإيجابيات الخاطئة للاستخراج. على عكس safelist، يقبل blocklist كلاً من السلسلة للمطابقة الدقيقة والتعبير العادي لمطابقة النمط.

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

سيستبعد هذا p-1 و p-2 و p-3 و p-4 من التوليد.