انتقل إلى المحتوى

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

التصغير

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

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

تُستخدم مكتبة minify لهذا الغرض.

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

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
add_filter('blockstudio/settings/assets/process/scss', function() {
  return true;
});

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

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

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

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

CSS
@import "modules.scss";

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

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

PHP
add_filter('blockstudio/assets/process/scss/import_paths', function($paths) {
  $paths[] = get_template_directory() . '/scss';
  return $paths;
});

التمهيد

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

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

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" عليها افتراضيًا. وهذا يتيح استخدام صيغة الاستيراد في سكربتات كتلِك دون أي إعداد إضافي.

ملاحظة

للاطلاع على شرح أعمق لوحدات ES، تفضل بزيارة وثائق MDN للويب.

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

JavaScript
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، مع استيراد جميع المكونات والدوال اللازمة من CDN المتوافق مع ESM، وهو في هذه الحالة esm.sh. لا مشكلة في هذا الأسلوب، لكنه يتطلب طلب الأصول اللازمة من موقع خارجي، ما قد يؤدي إلى تعطل السكربتات إذا توقف CDN عن العمل.

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

الإعداد

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

JavaScript
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.

ملاحظة

لا تزال البادئة القديمة blockstudio/ (e.g وblockstudio/preact@10.15.1) مدعومة للتوافق مع الإصدارات السابقة، لكننا نوصي باستخدام البادئة npm: للمشاريع الجديدة. راجع دليل الترحيل للتفاصيل.

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

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

JavaScript
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
import "npm:swiper@11.0.0/swiper.min.css";

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