الجزر
تتيح جزر الكتل للكتلة مواصلة استخدام مسار العرض المعتاد Blockstudio، مع إخراج المحتوى المرتبط بالطلب من استجابة HTML الأولية.
يفيد ذلك عندما ينبغي تخزين صفحة مؤقتًا بفعالية، بينما تظل إحدى كتلها معتمدة على الزائر الحالي أو الجلسة أو عربة التسوق أو الأذونات أو سياق طلب مباشر آخر.
تظل كتل Blockstudio ديناميكية من نوع WordPress. ولا تحوّلها الجزر إلى HTML ثابتة مُترجمة مسبقًا. بل يغيّر Blockstudio ما يُعرض في الطلب الأول:
- تعرض الجزر المُرطّبة HTML المعتاد والآمن للتخزين المؤقت، وتتلقى حدث تركيب
- تعرض الجزر الديناميكية عنصرًا نائبًا آمنًا للتخزين المؤقت أولًا، ثم تجلب الجزء الفعلي من متصفح الزائر
الأوضاع
الجزر المُرطّبة
استخدم جزيرة مُرطّبة عندما يكون ناتج الخادم آمنًا للتخزين المؤقت، ولا تحتاج الكتلة إلا إلى إشارة تركيب على الواجهة الأمامية.
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
تكون HTML الكتلة كاملةً موجودة في الاستجابة الأولية. ولا يجري وقت تشغيل الجزيرة طلب REST لها، بل يرسل blockstudio:island:hydrate على العلامة كي تتمكن شيفرة الواجهة الأمامية من إرفاق السلوك.
الجزر الديناميكية
استخدم جزيرة ديناميكية عندما يجب عرض ناتج الكتلة الفعلي ضمن سياق طلب الزائر.
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
لا تتضمن الاستجابة الأولية سوى عنصر نائب. ويجمع المتصفح كل الجزر الديناميكية الجاهزة في طلب واحد إلى:
POST /wp-json/blockstudio/v1/island/render
لا تعرض نقطة النهاية سوى كتل Blockstudio المسجّلة التي تكون ديناميكية وتكون blockstudio.island.mode مضبوطة على dynamic.
الإعداد
يمكن أن تكون قيمة island اختصارًا أو كائنًا.
{
"blockstudio": {
"island": true
}
}
تعني كل من true و"hydrate" الوضع المُرطّب. أما "dynamic" فتعني الوضع الديناميكي.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "section",
"attributes": ["productId", "variant"],
"placeholder": "cart-placeholder.php",
"loading": "visible",
"event": "cart:updated",
"cache": {
"ttl": 60,
"per": "user"
}
}
}
}
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
mode |
"hydrate" أو "dynamic" |
"hydrate" |
وضع الجزيرة. |
tag |
string |
"div" |
وسم غلاف العلامة. |
attributes |
string[] |
جميع سمات المكوّن | قائمة السماح بالسمات المرسلة إلى طلبات الأجزاء الديناميكية. |
placeholder |
string |
يُكتشف تلقائيًا | مسار قالب العنصر النائب النسبي. |
loading |
"eager" أو "visible" |
"eager" |
توقيت جلب الجزيرة الديناميكية من قِبل بيئة التشغيل. |
event |
string |
غير محدد | اسم حدث النافذة الذي يحدّث الجزيرة الديناميكية. |
context |
boolean |
false |
توقيع معرّف المقالة ونوعها للصفحة المطلوبة واستعادتهما للأجزاء الديناميكية. |
cache |
boolean أو object |
false |
سياسة اختيارية لذاكرة تخزين الأجزاء المؤقتة. |
سياق الصفحة
تُعرض الأجزاء الديناميكية عادةً باستقلال عن هيكل الصفحة. فعّل هوية الصفحة عندما يقرأ المكوّن إعدادات خاصة بالصفحة أو محتوى مرتبطًا بها:
{
"blockstudio": {
"island": {
"mode": "dynamic",
"context": true,
"cache": { "ttl": 60, "per": "global" }
}
}
}
تتضمن العلامة postId وpostType للصفحة المطلوبة ضمن data-bs-island-context. وتُوقّع القيمتان مع اسم المكوّن والسمات المسموح بها باستخدام السر الخاص بموقع الخدمة. ولا يمكن تغييرهما أو إضافتهما إلى طلب دون إبطال التوقيع. وترسلهما بيئة التشغيل مع طلب الأجزاء المجمّع الحالي، بما في ذلك التحديثات عند الظهور والتحديثات التي تطلقها الأحداث. ويعمل هذا أيضًا مع bs_render_block() وbs_block() ووسوم المكوّنات.
أثناء عرض الأجزاء، تشير $block['postId'] و$block['postType'] وget_the_ID() وget_queried_object_id() إلى تلك الصفحة. وتُستعاد بعد ذلك متغيرات الاستعلام والمقالة العامة في WordPress، حتى بعد استثناء أثناء العرض. هذه هي الصفحة المطلوبة، وليست عنصرًا داخل حلقة استعلام. ولا تُعاد معالجة معلمات URL عشوائية أو استعادة URL الطلب الأصلي. استخدم get_permalink($block['postId']) عند الحاجة إلى HTML الخاص بالصفحة الأساسية URL. لا ترسل الأرشيفات وعمليات العرض التي لا تتضمن مقالة مطلوبة هوية صفحة.
يتحقق المسار من استمرار وجود الصفحة، ومن مطابقة نوع المقالة الموقّع، ومن إمكانية قراءتها بواسطة الزائر الحالي، وذلك قبل الرجوع إلى ذاكرة تخزين الأجزاء المؤقتة. لا يتجاوز التوقيع الصالح حماية المقالات الخاصة أو المحمية بكلمة مرور، أو أهلية الجزيرة، أو قوائم السماح بالسمات، أو عمليات التحقق من الأذونات الخاصة بمكوّنك. تكون هوية الصفحة دائمًا جزءًا من مفتاح ذاكرة تخزين الأجزاء المؤقتة عند وجودها، لذا لا تشترك الصفحة نفسها في جزء مع صفحة أخرى حتى عند تطابق المكوّن والسمات. استخدم per: "user" أو عطّل ذاكرة تخزين الأجزاء المؤقتة عندما يعتمد الناتج أيضًا على الزائر.
عند حذف context أو تعيينه إلى false، تظل العلامات الحالية والسلوك المستقل عن السياق دون تغيير. لا تضع بيانات سرية في العلامة العامة.
العناصر النائبة الديناميكية
ينبغي أن تعرض الجزر الديناميكية عنصرًا نائبًا آمنًا في ذاكرة تخزين مشتركة للصفحة كاملة. لا تُضمّن بيانات خاصة بالزائر في فرع العنصر النائب.
يبحث Blockstudio عن العناصر النائبة بالترتيب التالي:
- المسار الصريح
island.placeholder placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- القالب العادي مع أعلام العناصر النائبة
<div class="cart-count-placeholder">
Loading cart...
</div>
إذا لم يوجد ملف للعنصر النائب، فاستخدم أعلام القالب في القالب العادي:
<?php if ( $isIslandPlaceholder ) : ?>
<div class="cart-count-placeholder">Loading cart...</div>
<?php else : ?>
<div class="cart-count">
<?php echo esc_html( acme_cart_count() ); ?>
</div>
<?php endif; ?>
تتوفر القيم نفسها في PHP وقوالب Twig وBlade:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
islandPhase هو "normal" أو "hydrate" أو "placeholder" أو "fragment".
سلوك وقت التشغيل
لا يحمّل Blockstudio بيئة تشغيل الجزر إلا عندما تحتوي الصفحة المعروضة على علامة جزيرة. لا تحمّل الصفحات الخالية من الجزر أي JavaScript إضافي للجزر.
بالنسبة إلى الجزر الديناميكية، تقوم بيئة التشغيل بما يلي:
- تجمع كل العلامات الجاهزة
- تزيل تكرار أزواج اسم الكتلة والسمات والتوقيع المتطابقة
- ترسل طلب REST مجمعًا واحدًا
- تستبدل كل عنصر نائب بالجزء المعاد
- تطلق
blockstudio:island:rendered - تطلق
blockstudio:island:hydrate
تُعرض جزر loading: "eager" فور بدء بيئة التشغيل. تنتظر جزر loading: "visible" حتى IntersectionObserver. إذا دخلت عدة جزر ظاهرة إلى إطار العرض معًا، تُجمع في طلب واحد.
ينعش event الجزيرة عند إطلاق حدث النافذة المحدد:
window.dispatchEvent(new Event('cart:updated'));
تُبقي حالات الإخفاق العنصر النائب في مكانه وتطلق blockstudio:island:error.
نقطة نهاية الأجزاء
نقطة نهاية الجزيرة عامة، لكنها ليست API عامًا لعرض الكتل.
تحمل كل علامة ما يلي:
- اسم الكتلة
- السمات المدرجة في قائمة السماح
- توقيعًا ينشئه الخادم
لا تعرض نقطة النهاية الكتلة إلا عندما:
- تكون الكتلة مسجلة
- تكون الكتلة كتلة WordPress ديناميكية
- تكون الكتلة معلّمة كجزيرة Blockstudio ديناميكية
- تجتاز السمات الواردة مخطط الكتلة وقائمة السماح الخاصة بالجزيرة
- يطابق التوقيع اسم الكتلة وسماتها بعد التطبيع
تُنشأ التوقيعات وقت العرض على موقع WordPress الذي يقدّم المحتوى، باستخدام أملاح ذلك الموقع وبيانات الجزيرة. ولا تُصدّر أو تُضمّن مسبقًا في القالب.
تُعلّم استجابات نقطة النهاية بأنها غير قابلة للتخزين المؤقت. إذا أردت تخزين الأجزاء مؤقتًا، فاستخدم island.cache.
تخزين الأجزاء مؤقتًا
لا تُخزّن الأجزاء الديناميكية مؤقتًا افتراضيًا.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
يستخدم true ذاكرة تخزين مؤقت عامة قصيرة الأجل. استخدم الصيغة الكائنية للتحكم الصريح:
{
"cache": {
"ttl": 120,
"per": "user"
}
}
per: "global" يشارك جزءًا مخزّنًا مؤقتًا واحدًا للكتلة نفسها والسمات وسياق الصفحة الذي تم تفعيله اختياريًا.
per: "user" يغيّر ذاكرة التخزين المؤقت بحسب معرّف المستخدم الحالي WordPress.
العرض برمجيًا
تعمل الجزر أينما عُرضت كتل Blockstudio:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
echo bs_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
كما تعمل باستخدام وسوم الكتل:
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />
يبقى الناتج الأولي علامة الجزيرة والعنصر النائب، وتُحمّل بيئة التشغيل عندما تحتوي الاستجابة المعروضة على تلك العلامة.
PHP API
Blockstudio\Islands::is_island('acme/cart-count');
Blockstudio\Islands::mode('acme/cart-count');
Blockstudio\Islands::registered();
Blockstudio\Islands::marker('acme/cart-count', $attributes, $html);
يتحقق marker() من البيانات الوصفية للكتلة. ولا تُنشأ العلامات الديناميكية إلا للكتل Blockstudio الديناميكية المسجلة التي تكون قيمة island.mode فيها dynamic.
الخطافات
الاكتشاف والترميز:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
نقطة النهاية والعرض:
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment
يغيّر blockstudio/islands/max_per_request الحد الأقصى لعدد الجزر الديناميكية المقبولة في طلب مجمّع واحد إلى نقطة النهاية. القيمة الافتراضية هي 50.
إعدادات بيئة التشغيل:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
التوقيعات:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
إجراءات دورة الحياة:
blockstudio/islands/registered
blockstudio/islands/rendered
متى لا تستخدم الجزر
لا تستخدم جزيرة ديناميكية للمحتوى المهم لـSEO. فأجزاء الجزر الديناميكية غير موجودة في HTML الأولي، وليس الغرض منها أن تُفهرس.
استخدم العرض العادي أو جزيرة مهيأة عندما يكون المحتوى آمنًا للتخزين المؤقت وينبغي أن تراه برامج الزحف. استخدم الجزيرة الديناميكية فقط للمحتوى الذي يمكن أن يصل بعد هيكل الصفحة، مثل UI الحساب وحالة سلة التسوق والتوصيات المخصصة أو عناصر التحكم المقيدة بالأذونات.