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

تسجيل الأصول

سيضيف Blockstudio تلقائيًا جميع الملفات المنتهية بـ .css و.scss و.js عند استخدام كتلتك في صفحة. ويمكن تحديد طريقة إضافة الأصول باستخدام أحد أسماء الملفات التالية. ويُعد * حرفًا بدلًا يمكن استبداله بأي سلسلة تختارها.

داخل ملفات CSS وSCSS الخاصة بالكتلة، يتمدد %selector% ليشير إلى فئة الغلاف الخاصة بالكتلة. يتيح لك ذلك استهداف العنصر نفسه الذي يتلقى bs_get_scoped_class()، حتى عندما لا يكون الملف أصلًا محدد النطاق.

النمط السلوك
*.(s)css يُضاف كوسم <link> في المحرر والواجهة الأمامية
*.inline.(s)css يُضاف المحتوى ضمن وسم <style> مضمن في المحرر والواجهة الأمامية
*.editor.(s)css يُضاف كوسم <link> في المحرر فقط
*.scoped.(s)css يُضاف المحتوى المحدد النطاق ضمن وسم <style> مضمن في المحرر والواجهة الأمامية
*.js يُضاف كوسم <script> في المحرر والواجهة الأمامية
*.inline.js يُضاف المحتوى ضمن وسم <script> مضمن في المحرر والواجهة الأمامية
*.editor.js يُضاف كوسم <script> في المحرر فقط
*.view.js يُضاف كوسم <script> في الواجهة الأمامية فقط

ملاحظة

لا تزال صيغة الشرطة (*-inline.css و*-editor.css وما إلى ذلك) مدعومة للتوافق مع الإصدارات السابقة، لكنها مهملة. استخدم صيغة النقطة للكتل الجديدة.

مضمنة

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

  • تُضمّن ملفات .js في نهاية المتن
  • تُضمّن ملفات .(s)css في نهاية الرأس
  • لا يُضمّن كل ملف إلا مرة واحدة

أوراق الأنماط الصغيرة المضمّنة

يُربط ملف *.(s)css افتراضيًا، ما يضيف طلبًا واحدًا لكل ملف. وبدلًا من ذلك، يطبع الإعداد assets.inlineLimit أوراق الأنماط الصغيرة مضمنة، وفقًا للقاعدة التي يطبّقها WordPress على أنماطه: تُؤخذ أوراق أنماط الكتل الخارجية للصفحة من الأصغر إلى الأكبر وتُطبع بصيغة <style> ما دام مجموع أحجامها التراكمي ضمن الحد. ويظل لكل ملف آخر وسم <link> الخاص به.

JSON
{
  "assets": {
    "inlineLimit": 40000
  }
}

الحد بوحدة البايت، وتُعطّل القيمة 0، وهي الافتراضية، هذا السلوك. ويقيس الحد حجم الملف المجمّع الذي سيحمّله <link>، بعد تصغيره إذا كان assets.minify.css مفعّلًا. يعتمد الاختيار بين <link> و<style> فقط على الحجم. يبقى كل وسم في الموضع الذي كان سيشغله <link>، لذلك لا يتغير ترتيب التحميل ولا التتالي. ويحتفظ العنصر بـ id الخاص به.

لا ينطبق الإعداد على ملفات *.inline.(s)css و*.scoped.(s)css، التي تكون مضمنة دائمًا، ولا على أصول المحرر والإدارة، ولا على أوراق الأنماط المستخرجة من وحدات JavaScript المستوردة. تُحتسب أوراق الأنماط العامة مثل أوراق أنماط الكتل. ويظل الملف مرتبطًا كلما كان تضمينه سيغيّره:

  • يحتوي على URL نسبي في url() أو @import، يُحلّ مساره نسبةً إلى ورقة الأنماط عند ربطه، ونسبةً إلى الصفحة عند تضمينه. المسارات المطلقة وعناوين URL الكاملة ومعرّفات الموارد المنتظمة data: وأجزاء # صالحة.
  • يستخدم image-set() أو يحتوي على تسلسل إغلاق </style.
  • يحتوي على تسلسلات هروب CSS أو بداية تعليق HTML أو تصريح @charset. تُترك هذه الملفات مرتبطة كإجراء احترازي لتجنب تغيير URL أو تحليل المستند.

استخدم عامل تصفية الإعداد لتغيير الحد من PHP:

PHP
add_filter('blockstudio/settings/assets/inline_limit', fn() => 40000);

يصبح CSS المضمّن جزءًا من HTML الصفحة. يجب إفراغ ذاكرة التخزين المؤقت للصفحة بعد تغيير ورقة أنماط، ولا يمكن للمتصفح تخزين تلك البايتات مؤقتًا بين الصفحات؛ لذلك يُحدد الحد كمجموع لكل صفحة.

محددة النطاق

تُضمّن الأنماط محددة النطاق أيضًا، لكن تسبقها قيمة معرّف فريدة لكل كتلة. استخدم الدالة bs_get_scoped_class لإضافة الفئة إلى قالبك.

PHP
<section class="hero <?php echo bs_get_scoped_class($b['name']); ?>">
  <h1 class="hero__title">Scope me!</h1>
</section>
CSS
%selector% {
  --hero-gap: var(--wp--preset--spacing--space-10);
}

%selector%.hero {
  border-bottom: 1px solid currentColor;
}

.hero__title {
  color: red;
}

سينتج عن ذلك النمط المحدد النطاق التالي:

HTML
<style>
  .bs-62df71e6cc9a {
    --hero-gap: var(--wp--preset--spacing--space-10);
  }

  .bs-62df71e6cc9a.hero {
    border-bottom: 1px solid currentColor;
  }

  .bs-62df71e6cc9a .hero__title {
    color: red;
  }
</style>

<section class="hero bs-62df71e6cc9a">
  <h1 class="hero__title">Scope me!</h1>
</section>

تظل المحددات العادية داخل ملف محدد النطاق تستهدف العناصر المتفرعة من الغلاف المحدد النطاق. استخدم %selector% عندما تريد تنسيق الغلاف نفسه.

عامة

إلى جانب الأصول الخاصة بالكتل، يمكنك أيضًا إضافة أصول عامة لتكون متاحة في جميع الصفحات، سواء وُجدت فيها كتلة أم لا. لإضافة أصل عام، أضف البادئة global- إلى اسم الملف. ويمكن استخدام أي من اللواحق (e.g و-inline) معها.

التركيبات الممكنة هي:

  • global-styles.(s)css
  • global-styles.inline.(s)css
  • global-styles.editor.(s)css
  • global-styles.scoped.(s)css
  • global-scripts.js
  • global-scripts.inline.js
  • global-scripts.editor.js
  • global-scripts.view.js

الإدارة

تُضاف أصول الإدارة في منطقة إدارة WordPress فقط. وتُستخدم البادئة admin- لتعريف أصول الإدارة.

  • admin-styles.(s)css
  • admin-scripts.js

محرر الكتل

تُضاف أصول محرر الكتل في محرر الكتل فقط. وتُستخدم البادئة block-editor- لتعريف أصول محرر الكتل.

  • block-editor-styles.(s)css
  • block-editor-scripts.js

ملاحظة

إذا عطّل WordPress إطار المحرر لأن كتلة من جهة العميل مسجلة بإصدار apiVersion أقل من 3، فإن لوحة المحرر وواجهة إدارة WordPress تشتركان في المستند نفسه. ينبغي للسكربتات العامة أو سكربتات المحرر التي ترتبط بـ window أو document أو body أو أحداث عجلة الفأرة أو تمرير المستند أن تتحقق من body.block-editor-page أو تستثني مناطق المحرر WordPress مثل .interface-complementary-area و.interface-navigable-region.

ترتيب التحميل

في الواجهة الأمامية، عند تفعيل الإضافة التلقائية للأصول وتخزين المخرجات مؤقتًا، يضيف Blockstudio وسوم الكتلة CSS و<link> و<style> إلى الصفحة المخزنة مؤقتًا مباشرةً قبل وسم الإغلاق </head> بدلًا من تسجيلها باستخدام wp_enqueue_style(). لذلك يأتي CSS الخاص بالكتلة بعد أوراق الأنماط التي طبعها WordPress مسبقًا في الرأس، بما فيها أنماط القوالب والإضافات المضافة باستخدام wp_enqueue_style()، بصرف النظر عن أولوية الإضافة أو التبعيات. أما أصول الإدارة وblock-editor- فتستخدم نظام الإضافة الخاص بـ WordPress.

عندما تتساوى القواعد في الأهمية وطبقة التتالي ودرجة التحديد، تتغلب ورقة أنماط الكتلة على ورقة أنماط القالب. لتغيير ذلك، ارفع درجة تحديد قاعدة القالب أو ألحِق ورقة أنماط القالب بالرأس الذي ينشئه Blockstudio باستخدام مرشح blockstudio/render/head. يوضع المحتوى الذي يضيفه المرشح بعد أصول الكتلة. أزل ورقة الأنماط أيضًا من WordPress حتى لا تُحمّل مرتين.

PHP
add_action('wp_enqueue_scripts', function() {
  wp_dequeue_style('theme-overrides');
}, 100);

add_filter('blockstudio/render/head', function($head) {
  return $head . '<link rel="stylesheet" href="' . esc_url(get_theme_file_uri('overrides.css')) . '">';
});

لا يعمل عامل التصفية head إلا عندما يخزّن Blockstudio الصفحة مؤقتًا. يكون التخزين المؤقت معطّلًا في معاينة أداة التخصيص وعندما تُعيد blockstudio/buffer/enabled القيمة false. يوضّح bs_is_buffering() الحالة التي أنت فيها، كي يتمكن القالب من إضافة ورقة أنماطه عبر عامل التصفية عندما تكون الصفحة مخزّنة مؤقتًا، وإضافتها إلى قائمة التحميل باستخدام WordPress في غير ذلك. تصبح الإجابة متاحة ابتداءً من wp_enqueue_scripts، وتكون false قبل template_redirect.

PHP
add_action('wp_enqueue_scripts', function() {
  $url = get_theme_file_uri('overrides.css');

  if (bs_is_buffering()) {
    add_filter('blockstudio/render/head', function($head) use ($url) {
      return $head . '<link rel="stylesheet" href="' . esc_url($url) . '">';
    });
    return;
  }

  wp_enqueue_style('theme-overrides', $url);
});

استخدم blockstudio/buffer/output إذا احتجت إلى إعادة ترتيب المستند النهائي بطريقة أخرى.

تعطيل الإضافة

يمكن تعطيل الإضافة التلقائية للأصول باستخدام إعداد assets/enqueue. يفيد ذلك إذا أردت تولي إضافة جميع الأصول بنفسك.

PHP
add_filter('blockstudio/settings', function($settings) {
  $settings['assets']['enqueue'] = false;
  return $settings;
});

لكل كتلة

عندما لا يُرجع قالب الكتلة شيئًا، لن يضيف Blockstudio أي أصول لتلك الكتلة. وتفيد هذه الطريقة لتعطيل الإضافة عند تحقق شرط معين.

PHP

PHP
<?php
  if ( !$a['slides'] ) {
    // or return '';
    return false;
  }
?>

<div>my slider</div>

Twig

Twig
{% if not a.slides %}
  <div>my slider</div>
{% endif %}