
# معالجة الأصول

## التصغير

يمكن لـ Blockstudio تصغير جميع ملفات CSS وJS في الكتلة تلقائيًا.

تُحفظ الملفات المجمعة في مجلد `_dist` الخاص بالكتلة، وتُضاف عند استخدام الكتلة. عند تحديث الملف المصدر، يتحقق Blockstudio من وجود ملف مجمع يحمل الطابع الزمني نفسه، وإن لم يوجد، ينشئه.

تُستخدم مكتبة [minify](https://github.com/matthiasmullie/minify) لهذا الغرض.

يمكن تفعيل التصغير باستخدام إعداد `assets/minify`:

```php title="functions.php"
add_filter('blockstudio/settings/assets/minify/css', function() {
  return true;
});

add_filter('blockstudio/settings/assets/minify/js', function() {
  return true;
});
```

## SCSS

إذا كنت تفضل كتابة الأنماط بـ SCSS، يمكنك تفعيل معالجة SCSS:

```php title="functions.php"
add_filter('blockstudio/settings/assets/process/scss', function() {
  return true;
});
```

سيؤدي هذا إلى تفعيل معالجة SCSS لملفات `.css`.

بدلًا من ذلك، يمكنك استخدام إضافة `.scss`، وستتم معالجة الأنماط تلقائيًا حتى عندما لا يكون الإعداد أعلاه `true`.

### مسارات الاستيراد

عند استخدام SCSS، يمكنك استيراد ملفات SCSS أخرى. تكون مسارات الاستيراد نسبية إلى الملف الذي تستورد منه.

```css title="style.scss"
@import "modules.scss";
```

بالإضافة إلى ذلك، يمكن تحديد مسارات استيراد مخصصة باستخدام المرشح `blockstudio/assets/process/scss/import_paths`، ما يتيح استيراد الملفات من مجلدات أخرى دون تحديد بنية المجلدات.

يمكن حذف امتداد `.scss` من مسارات الاستيراد، كما يمكن حل الملفات الجزئية مثل `_tokens.scss` أو الملف `_index.scss` في المجلد.

```php title="functions.php"
add_filter('blockstudio/assets/process/scss/import_paths', function($paths) {
  $paths[] = get_template_directory() . '/scss';
  return $paths;
});
```

### التمهيد

إذا أردت إتاحة دوال Sass أو متغيراته أو مزائجه أو أدواته المشتركة في كل ملف SCSS، يمكنك إضافة تمهيد عام قبل التجميع.

يفيد هذا مع أطر العمل مثل Bootstrap، إذ قد ترغب في إتاحة مزائج مشتركة مثل نقاط التوقف دون تكرار الاستيرادات في أصول كل كتلة.

```php title="functions.php"
add_filter('blockstudio/assets/process/scss/prelude', function($prelude, $path, $scss) {
  return '@import "functions";' . "\n"
    . '@import "variables";' . "\n"
    . '@import "mixins";';
}, 10, 3);
```

وبالاقتران مع `blockstudio/assets/process/scss/import_paths`، يتيح ذلك محتوى Sass المشار إليه لكل ملف مجمع.

تُعاد ترجمة أصول الكتل عند تغير وقت تعديل أحد التبعيات، بما في ذلك الملفات التي تستوردها ملفات جزئية أخرى. يتتبع Blockstudio تبعيات `@import` و`@use` و`@forward` المحلية، بما فيها تبعيات التمهيد ومسارات الاستيراد المُعدّة. ويُتتبّع كل اعتماد مشترك مرة واحدة، كما تمنع آلية الاكتشاف الدوران في حلقات. وتُدرج هذه الملفات أيضًا في قائمة مراقبة ذاكرة التخزين المؤقت وقت التشغيل.

على سبيل المثال، تؤدي تعديلات `mixins/_wysiwyg.scss` إلى إعادة تجميع `global-styles.scss` عند استيراده `scss/_wysiwyg.scss`، الذي يستورد هذا المزيج بدوره. ولا تتطلب التغييرات تعديل ملف الإدخال. تُستثنى وحدات Sass المضمنة وعمليات الاستيراد البعيدة من رسم التبعيات المحلية.

## وحدات ES

تُحمّل جميع السكربتات (المضمنة والافتراضية) في Blockstudio مع تطبيق `type="module"` عليها افتراضيًا. وهذا يتيح استخدام [صيغة الاستيراد](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) في سكربتات كتلِك دون أي إعداد إضافي.


> **ملاحظة**
>
> للاطلاع على شرح أعمق لوحدات ES، تفضل بزيارة [وثائق MDN للويب](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules).


لنتخيل الكود التالي داخل **script.js**:

```javascript title="script.js"
import { h, render } from "https://esm.sh/preact@10.15.1";
import htm from "https://esm.sh/htm@3.1.1";
import confetti from "https://esm.sh/canvas-confetti@1.6.0";

const html = htm.bind(h);

function App(props) {
  confetti();
  return html`<h1>Hello ${props.name}!</h1>`;
}

render(
  html`<${App} name="Hello from Preact!" />`,
  document.querySelector("#element")
);
```

سينشئ المثال أعلاه مكوّنًا باستخدام [Preact](https://preactjs.com/)، مع استيراد جميع المكونات والدوال اللازمة من CDN المتوافق مع ESM، وهو في هذه الحالة **esm.sh**. لا مشكلة في هذا الأسلوب، لكنه يتطلب طلب الأصول اللازمة من موقع خارجي، ما قد يؤدي إلى تعطل السكربتات إذا توقف CDN عن العمل.

يتضمن Blockstudio طريقة ملائمة لتنزيل وحدات ES إلى الكتلة، ما يلغي الحاجة إلى شبكات CDN خارجية لوحدات ESM في بيئة الإنتاج.

### الإعداد

لتنزيل وحدة إلى مجلد كتلتك، استخدم البادئة `npm:` متبوعة باسم الحزمة وإصدارها:

```javascript title="script.js"
import { h, render } from "npm:preact@10.15.1";
import htm from "npm:htm@3.1.1";
import confetti from "npm:canvas-confetti@1.6.0";
```

تتوافق هذه الصيغة مع اصطلاح [محددات npm في Deno](https://docs.deno.com/runtime/fundamentals/node/#using-npm-packages).


> **ملاحظة**
>
> لا تزال البادئة القديمة `blockstudio/` (e.g و`blockstudio/preact@10.15.1`) مدعومة للتوافق مع الإصدارات السابقة، لكننا نوصي باستخدام البادئة `npm:` للمشاريع الجديدة. راجع [دليل الترحيل](https://blockstudio.dev/ar/docs/dev/migration/v7/) للتفاصيل.


سيتحقق Blockstudio تلقائيًا من ملفات .js المتغيرة بحثًا عن عمليات الاستيراد، وينزلها إلى مجلد الكتلة المحلي. وستوضع الملفات المنزلة في مجلد `modules` داخل مجلد الكتلة.

سيُعاد كتابة ملف السكربت عند الحفظ ليتوافق مع الوحدة المستضافة محليًا:

```javascript title="Generated script.js"
import { h, render } from "./modules/preact/10.15.1.js";
import htm from "./modules/htm/10.15.1.js";
import confetti from "./modules/canvas-confetti/1.6.0.js";
```

أثناء العمل داخل المحرر، سيظل استخدام عنوان URL ‏CDN قائمًا (يستخدم Blockstudio ‏esm.sh) عند معاينة الكتلة والعمل عليها.

### محاذير

#### الإصدار

عادةً، يمكن استخدام الوحدات من شبكات CDN دون رقم إصدار، وفي هذه الحالة يُستخدم أحدث إصدار دائمًا. وبما أن Blockstudio لا يحفظ أي معلومات في قاعدة البيانات، يلزم تحديد رقم الإصدار عند استخدام الوحدات.

#### الوحدات نفسها

تقتصر الوحدات على الكتل التي تستخدمها. حتى عند استخدام الوحدة نفسها بالإصدار نفسه في عدة كتل، سيظل Blockstudio ينزل الوحدة المطلوبة إلى كل كتلة. والسبب الرئيسي هو أن الكتل ينبغي أن تكون وحدات مستقلة يسهل مشاركتها عبر تثبيتات أو مواقع أخرى.

إضافة إلى ذلك، سيُطلب تنزيل الوحدة نفسها مرتين إذا وُجدت الكتلتان في الصفحة. يمكن حل هذه المشكلة باستخدام `script-inline.js` بدلًا من ملف `script.js`. سيعيد Blockstudio كتابة كل استيراد ليشير إلى موقع أول نسخة من الوحدة إذا تطابق الاسم ورقم الإصدار.

## محمّل CSS

يمكن أيضًا استيراد ملفات CSS باستخدام الصيغة نفسها المذكورة أعلاه.

```javascript title="script.js"
import "npm:swiper@11.0.0/swiper.min.css";
```

سيُنزل ملف CSS إلى مجلد `modules`، وستتم إضافته تلقائيًا عند استخدام الكتلة. ما دام الإصدار متطابقًا، لن تُضاف إلا نسخة واحدة من ملف CSS، حتى إذا وُجد في عدة كتل.
