مقاطع مخصصة في صفحات مخزنة مؤقتًا
الصفحة التي تُقدَّم من ذاكرة تخزين مؤقت ثابتة تكون متماثلة للجميع. هذا هو الهدف من التخزين المؤقت، وهو أيضًا موضع المشكلة: يريد الترويس أن يقول «مرحبًا يا Ada» لعميل سجل دخوله، ويريد رمز السلة عرض ثلاثة عناصر. إذا تفرع القالب بناءً على المستخدم الحالي، فإما أن تخزّن الذاكرة تحية زائر واحد للجميع، أو أن تضطر إلى استثناء الصفحة بالكامل.
تفصل الجزر الديناميكية في Blockstudio بين هذين الأمرين. يحتوي HTML المخزن مؤقتًا على عنصر نائب آمن للتخزين المؤقت. بعد تحميل الصفحة، تطلب بيئة تشغيل صغيرة WordPress المقطع المخصص ضمن طلب الزائر نفسه، ثم تستبدله به. وهكذا تظل الصفحة قابلة للتخزين المؤقت، بينما يظل المقطع وحده مباشرًا.
ينشئ هذا الدليل جزيرتين: تحية وعدّادًا لعناصر السلة، ويشرح محتوى الصفحة المخزنة مؤقتًا، وشكل طلب المقطع، وكيف تحدد نقطة النهاية هوية الزائر. ويرتبط بدليل تقديم WordPress كـ Static HTML.
آلية عمل الجزيرة الديناميكية
- تعرض الكتلة العنصر النائب داخل عنصر علامة. وتحمل العلامة اسم الكتلة والسمات المسموح بها وتوقيعًا مُنشأ على الخادم.
- بما أن الصفحة المعروضة تحتوي على علامة، يدرج Blockstudio بيئة تشغيل الجزر. أما الصفحات التي لا تحتوي على جزر فلا تتضمن JavaScript للجزر.
- تجمع بيئة التشغيل العلامات الجاهزة وترسل طلب
POSTواحدًا مجمعًا إلى/wp-json/blockstudio/v1/island/render. - تتحقق نقطة النهاية من كل توقيع، وتعرض الكتلة ضمن سياق طلب الزائر، ثم تعيد المقاطع.
- تستبدل بيئة التشغيل كل عنصر نائب وترسل الأحداث.
في محرر الكتل، تُعرض الكتلة بشكلها المعتاد من دون عنصر نائب.
الخطوة 1: كتلة التحية
أنشئ الكتلة بثلاثة ملفات:
blocks/
└── greeting/
├── block.json
├── placeholder.php
└── index.php
{
"apiVersion": 3,
"name": "acme/greeting",
"title": "Greeting",
"category": "widgets",
"icon": "admin-users",
"description": "Account link that greets signed-in visitors.",
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "span",
"attributes": ["guestLabel"],
"cache": {
"ttl": 300,
"per": "user"
}
},
"attributes": [
{ "id": "guestLabel", "type": "text", "label": "Guest label", "default": "Sign in" }
]
}
}
mode: "dynamic" هو ما يجعل هذه الجزيرة ترسل طلب مقطع.
يحدد tag عنصر العلامة، لتتمكن الجزيرة من الظهور ضمن السطر في شريط التنقل.
أما attributes فهي قائمة السماح بسمات الكتلة التي تُرسل مع طلب المقطع؛ فما لم يُدرج فيها لا يُرسل ولا يُوقّع. ويُشرح cache بمزيد من التفصيل لاحقًا.
العنصر النائب هو ما تحتويه الصفحة المخزنة مؤقتًا. يجب أن يكون عرضه آمنًا لجميع الزوار، لذا لا يتضمن بيانات المستخدم. يصلح رابط «الحساب» للجميع:
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">Account</a>
يعرض القالب الرئيسي المقطع الحقيقي:
<?php
$user = wp_get_current_user();
?>
<?php if ( $user->exists() ) : ?>
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">
<?php echo esc_html( sprintf( 'Hi, %s', $user->display_name ) ); ?>
</a>
<?php else : ?>
<a href="<?php echo esc_url( wp_login_url() ); ?>">
<?php echo esc_html( $a['guestLabel'] ); ?>
</a>
<?php endif; ?>
لا بأس من التفرع بناءً على المستخدم الحالي هنا؛ فهذا القالب لا يعمل إلا عند طلب المقطع، وليس عند تقديم الصفحة المخزنة مؤقتًا.
ضعه في الموضع الذي يُعرض فيه الترويس:
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>
تعمل وسوم الكتل أيضًا: <bs:acme-greeting /> أو
<block name="acme/greeting" />.
الخطوة 2: محتوى الصفحة المخزنة مؤقتًا
عند العرض على الخادم، لا تنتج الكتلة إلا العلامة والعنصر النائب:
<span data-bs-island="acme/greeting" data-bs-island-mode="dynamic" data-bs-island-phase="placeholder" data-bs-island-props="{"guestLabel":"Sign in"}" data-bs-island-signature="a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043" data-bs-island-loading="eager"><!--blockstudio/acme/greeting--><a href="https://example.com/account/">Account</a>
</span>
اعرضها مرة كزائر مجهول ومرة كمستخدم سجل دخوله، وستكون السلسلتان متطابقتين بايتًا ببايت. وهذه بالضبط الخاصية التي يحتاج إليها العرض المسبق الثابت مع تفعيل serveLoggedIn: أيًا كان من بدأ العرض، يظل المستند المخزن نفسه، ولا يمكن أن تتسرب إليه أي بيانات شخصية.
الخطوة 3: طلب المقطع
ترسل بيئة التشغيل كل جزيرة جاهزة في طلب واحد:
{
"islands": [
{
"clientId": "a1",
"name": "acme/greeting",
"attributes": {
"guestLabel": "Sign in"
},
"signature": "a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043"
}
]
}
تُفهرس الاستجابة حسب clientId. وبالنسبة إلى زائر سجل دخوله:
{
"a1": "<!--blockstudio/acme/greeting--> <a href=\"https://example.com/account/\">\n Hi, Ada </a>\n"
}
يُعاد العنصر الذي يفشل التحقق عنه برمز خطأ بدلًا من HTML، دون تعطيل بقية الدفعة. في هذا المثال، غيّر العنصر الثاني guestLabel من دون توقيع مطابق، وأشار الثالث إلى كتلة ليست جزيرة ديناميكية:
{
"a1": "<!--blockstudio/acme/greeting--> <a href=\"https://example.com/wp-login.php\">\n Sign in </a>\n",
"a2": {
"error": "blockstudio_island_invalid_signature"
},
"a3": {
"error": "blockstudio_island_not_allowed"
}
}
تتضمن كل استجابة Cache-Control: no-store, no-cache, must-revalidate, max-age=0 وPragma: no-cache وX-Robots-Tag: noindex. توجد نقطة النهاية ضمن /wp-json، الذي يتجاوزه العرض المسبق الثابت دائمًا، لذا لن يخزن المقطع لا ذاكرة التخزين المؤقت للمصدر ولا CDN يحترم ترويسات المصدر.
هوية الزائر
ترسل بيئة التشغيل الطلب باستخدام credentials: 'same-origin'، ولذلك يضمّن المتصفح ملف تعريف ارتباط تسجيل الدخول WordPress. وتتجاهل WordPress REST API عادةً المصادقة عبر ملف تعريف الارتباط من دون nonce، ولا يمكن أن يوجد nonce في صفحة مخزنة مؤقتًا. تتولى نقطة نهاية الجزيرة هذا الأمر بنفسها: ففي طلب المتصفح من المصدر نفسه، تتحقق من ملف تعريف الارتباط logged_in وتستعيد بيانات ذلك المستخدم قبل العرض.
يُحدَّد المصدر نفسه من ترويسة Sec-Fetch-Site، وعند وجودها، بمقارنة ترويسة Origin مع home_url(). يُعرض الطلب القادم من مصدر آخر ويحمل ملف تعريف الارتباط مصادقةً مجهولة، لذا لا يعرض طلب أي موقع آخر المقطع الشخصي للزائر. عمليًا:
| الطلب | يُعرض بصفة |
|---|---|
| طلب fetch من المصدر نفسه مع ملف تعريف ارتباط صالح لتسجيل الدخول | المستخدم الذي سجل دخوله |
| طلب من مصدر آخر يحمل ملف تعريف الارتباط نفسه | مجهول |
| دون ملف تعريف ارتباط | مجهول |
ما هذه الصفحة؟
أضف "context": true إلى blockstudio.island عندما يحتاج الجزء إلى هوية صفحته. عندئذ توقّع العلامة معرّف المقالة ونوعه للصفحة التي جرى الاستعلام عنها، إلى جانب السمات. وفي الجزء، تشير $block['postId'] و$block['postType'] وget_the_ID() وget_queried_object_id() إلى تلك الصفحة. ويظل المقصود داخل حلقة الاستعلام هو الصفحة الخارجية التي جرى الاستعلام عنها، وليس عنصر الحلقة.
سياق الصفحة اختياري، وهو أيضًا جزء من مفتاح ذاكرة التخزين المؤقت للأجزاء. يعيد المسار النهائي التحقق من صلاحية الوصول، حتى للأجزاء المخزنة مؤقتًا، لذا لا تكشف العلامة الموقعة عن صفحة أصبحت خاصة أو محمية بكلمة مرور. راجع سياق الصفحة للاطلاع على تفاصيل الإعداد والأمان. لا يُعاد تشغيل أي URL أو معلمات استعلام عشوائية.
الخطوة 4: عدّاد سلة يُحدّث نفسه
تعرض الجزيرة الثانية نمط العنصر النائب الآخر وخياري بيئة التشغيل.
بدلًا من استخدام ملف عنصر نائب منفصل، يتحقق القالب من $isIslandPlaceholder:
{
"apiVersion": 3,
"name": "acme/cart-count",
"title": "Cart Count",
"category": "widgets",
"icon": "cart",
"description": "Number of items in the visitor's cart.",
"blockstudio": {
"island": {
"mode": "dynamic",
"loading": "visible",
"event": "acme:cart-updated"
},
"attributes": []
}
}
<?php
$count = (int) apply_filters( 'acme/cart_count', 0 );
?>
<?php if ( $isIslandPlaceholder ) : ?>
<a href="/cart/" class="cart-count">Cart</a>
<?php else : ?>
<a href="/cart/" class="cart-count">
Cart <span class="cart-count__badge"><?php echo esc_html( (string) $count ); ?></span>
</a>
<?php endif; ?>
تتوفر العلامات نفسها في كل لغات القوالب: isIsland وisIslandPlaceholder وisIslandFragment وislandPhase ("normal" أو "hydrate" أو "placeholder" أو "fragment"). يأتي العدد هنا من مرشح acme/cart_count تملؤه شيفرة التجارة الإلكترونية لديك؛ وعندما يُرجع 3، تعيد نقطة النهاية:
{"c1":"<!--blockstudio/acme/cart-count--> <a href=\"/cart/\" class=\"cart-count\">\n Cart <span class=\"cart-count__badge\">3</span>\n </a>\n"}
يؤجل loading: "visible" الطلب حتى تدخل العلامة إطار العرض، باستخدام IntersectionObserver. ومع ذلك، تُجمع الجزر الظاهرة التي تظهر معًا في طلب واحد. يحدد event حدثًا على window يعيد جلب الجزيرة، لذا لا يحتاج البرنامج النصي بعد استدعاء الإضافة إلى السلة إلا إلى إطلاقه:
window.dispatchEvent(new Event('acme:cart-updated'));
التفاعل في كود الواجهة الأمامية
تنتقل الأحداث صعودًا من العلامة، لذا يغطي مستمع واحد على document كل الجزر. ويحتوي event.detail.name على اسم الكتلة:
document.addEventListener('blockstudio:island:rendered', (event) => {
if (event.detail.name !== 'acme/cart-count') return;
event.target.querySelector('.cart-count__badge')?.classList.add('is-fresh');
});
document.addEventListener('blockstudio:island:error', (event) => {
console.warn('Island failed', event.detail.name, event.detail.error);
});
بعد الاستبدال، ترسل بيئة التشغيل blockstudio:island:rendered ثم blockstudio:island:hydrate. وعند الإخفاق، يبقى العنصر النائب في مكانه ويُطلق blockstudio:island:error. تتخطى الجزر المُهيأة ("island": "hydrate") الطلب بالكامل: فـHTML الكامل موجود في الصفحة، ولا تتلقى إلا حدث hydrate، ما يجعلها مناسبة للكتل التفاعلية الآمنة للتخزين المؤقت، مثل علامات التبويب.
تخزين المقاطع مؤقتًا
تُعرض المقاطع في كل طلب افتراضيًا. وتختار التحية أعلاه تخزينًا مؤقتًا قصير المدة:
{
"cache": {
"ttl": 300,
"per": "user"
}
}
يغيّر per: "user" المقطع المخزن مؤقتًا بحسب معرّف مستخدم WordPress، ولا تُخزّن الطلبات المجهولة مؤقتًا بهذا الخيار، لذا لا يمكن لزائرين مجهولين مشاركة مدخل مخصص لمستخدم. يشارك per: "global" مقطعًا واحدًا للكتلة والسمات نفسيهما، وهو مناسب للمحتوى المباشر غير الشخصي، مثل مستوى المخزون. تكون قيمة ttl الافتراضية 60 ثانية، وcache: true ذاكرة تخزين مؤقت عامة مدتها 60 ثانية.
نموذج الأمان
نقطة النهاية عامة، لكنها ليست أداة عرض عامة للكتل. ولا تعرض عنصرًا إلا عند تحقق جميع الشروط التالية:
- أن تكون الكتلة مسجلة وديناميكية، وأن تكون
island.modeمضبوطة علىdynamic - أن يطابق التوقيع اسم الكتلة والسمات التي اجتازت المرشح: المفاتيح الموجودة في كل من مخطط الكتلة وقائمة السماح للجزيرة فقط
التوقيع هو HMAC-SHA256 على اسم الكتلة وسماتها بعد تطبيعها، ومفتاحه ملح auth للموقع الذي يقدمها. تُنشأ التوقيعات وقت العرض على ذلك الموقع، ولا تُضمَّن مطلقًا في سمة. ويترتب على ذلك أمران: يحمل المستند المعروض في بيئة التجهيز توقيعات تلك البيئة، لذا اعرض المستندات على الموقع الذي سيقدمها. كما أن تدوير أملاح WordPress يبطل كل توقيع في المستندات المخزنة، لذا امسح العرض المسبق الثابت بعد تدوير الملح.
يقبل الطلب الواحد حتى 50 جزيرة؛ وما زاد على ذلك يعيد HTTP 413. غيّر الحد باستخدام blockstudio/islands/max_per_request. وتتوفر خطافات التوقيع (blockstudio/islands/signature_payload وblockstudio/islands/signature وblockstudio/islands/verify_signature) للمضيفين الذين يحتاجون إلى آلية مختلفة.
متى لا تستخدم الجزيرة
لا تظهر المقاطع ضمن HTML الأولي، لذا لا تراها برامج الزحف. أبقِ المحتوى المرتبط بـSEO ضمن العرض المعتاد. استخدم الجزر الديناميكية للمحتوى الذي يمكن أن يصل بعد هيكل الصفحة، مثل روابط الحساب وحالة السلة والتوصيات وعناصر التحكم المقيّدة بالأذونات. وعندما تكون الصفحة بأكملها شخصية، مثل لوحة معلومات الحساب، أدرج مسارها في dynamicPaths بدلًا من ذلك واعرضها مباشرةً.
الخطوات التالية
- مرجع الجزر: كل الخيارات، وترتيب البحث عن العناصر النائبة، وPHP API، والخطافات.
- تقديم WordPress بوصفها HTML: ذاكرة التخزين المؤقت التي صُممت هذه الجزر للاستفادة منها.
- مرجع العرض المسبق الثابت:
serveLoggedIn، والمسارات الديناميكية، والتقديم المبكر. - المكونات التفاعلية: سلوك العميل للكتل التي تحتاج إلى أكثر من حدث تركيب.