إنشاء مكونات تفاعلية
تكون كتل WordPress ثابتة افتراضيًا. يحفظ المحرر HTML في قاعدة البيانات، وتعرضه الواجهة الأمامية، وتنتهي القصة عند هذا الحد. وهذا مناسب تمامًا لكثير من الكتل. لكن بعض المكونات تحتاج إلى الاستجابة لتفاعل المستخدم، مثل تبديل المحتوى والتنقل بين علامات التبويب وفتح مربعات الحوار وتحديث العدادات.
تضيف WordPress وAPI للتفاعلية سلوكًا تفاعليًا من جهة العميل إلى الكتل باستخدام سمات HTML تُسمى التوجيهات. اكتب data-wp-on--click بدلًا من addEventListener، وdata-wp-bind--hidden بدلًا من element.hidden = true. ويتولى API التفاعلية وعزل السياق والتهيئة تلقائيًا.
يتولى Blockstudio توصيل المكونات. عيّن "interactivity": true في block.json، وسينشئ Blockstudio خريطة الاستيراد، ويحمّل API في كل من المحرر والواجهة الأمامية، ويحل عمليات استيراد وحدات ES. لا خطوة بناء ولا أداة تجميع ولا إعداد webpack. راجع مرجع التفاعلية لمعرفة تفاصيل الإعداد.
يشرح هذا الدليل أربعة مكونات كاملة، يقدّم كل منها مفاهيم جديدة. وبحلوله، ستكون لديك أنماط عملية لأكثر عناصر UI التفاعلية شيوعًا.
آلية العمل
التوجيهات
التوجيهات هي سمات data-wp-* تعلن عن السلوك التفاعلي مباشرةً في HTML. ومن أكثرها استخدامًا:
| التوجيه | الغرض | المثال |
|---|---|---|
data-wp-interactive |
تحديد مساحة أسماء المخزن | data-wp-interactive="myBlock" |
data-wp-context |
حالة تفاعلية محلية لكل نسخة | data-wp-context='{ "isOpen": false }' |
data-wp-on--[event] |
معالج حدث | data-wp-on--click="actions.toggle" |
data-wp-bind--[attr] |
ربط سمة HTML | data-wp-bind--hidden="!context.isOpen" |
data-wp-class--[name] |
تبديل فئة CSS | data-wp-class--is-active="context.isActive" |
data-wp-text |
تعيين محتوى النص | data-wp-text="state.count" |
data-wp-style--[prop] |
تعيين نمط مضمن | data-wp-style--opacity="context.opacity" |
data-wp-on-document--[event] |
حدث عام للمستند | data-wp-on-document--keydown="actions.onKeydown" |
data-wp-watch |
تشغيل استدعاء عند تغيّر الحالة | data-wp-watch="callbacks.log" |
data-wp-each |
التكرار عبر مصفوفة | data-wp-each="state.items" |
المخزن
لكل كتلة تفاعلية مخزن يُنشأ باستدعاء store() مع مساحة أسماء وكائن يتضمن actions وcallbacks، واختياريًا state:
import { store, getContext } from '@wordpress/interactivity';
store('myBlock', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
داخل الإجراءات، يعيد getContext() أقرب كائن data-wp-context أعلى شجرة DOM. ويعيد getElement() مرجعًا إلى عنصر DOM الذي أطلق الإجراء، وهو مفيد لقراءة سمات data-*.
السياق مقابل الحالة
السياق (data-wp-context) محلي لكل نسخة من الكتلة. إذا وضعت ثلاثة أقسام قابلة للطي في صفحة، فلكل منها قيمة isOpen خاصة بها. تبديل أحدها لا يؤثر في البقية.
الحالة (wp_interactivity_state()) عامة ومشتركة بين جميع نسخ الكتلة. استخدمها للبيانات القادمة من الخادم، مثل عدد التعليقات، أو للقيم التي ينبغي أن تكون متماثلة في كل مكان.
يعمل السياق في المحرر والواجهة الأمامية معًا. أما الحالة فتعمل في الواجهة الأمامية فقط، لأن WordPress يضمّنها في وسم script غير الموجود في استجابات REST API الخاصة بالمحرر.
القسم القابل للطي
أبسط نمط تفاعلي: انقر زرًا لتبديل ظهور محتوى. لا يحتاج هذا المثال إلا إلى ثلاثة توجيهات وبضعة أسطر من JavaScript.
{
"name": "my-theme/accordion",
"title": "Accordion",
"category": "text",
"icon": "arrow-down-alt2",
"description": "Expandable content section.",
"blockstudio": {
"interactivity": true,
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "Accordion heading" },
{ "id": "body", "type": "textarea", "label": "Body", "default": "Accordion content goes here." }
]
}
}
<div useBlockProps
data-wp-interactive="myTheme/accordion"
data-wp-context='{ "isOpen": false }'>
<button
data-wp-on--click="actions.toggle"
data-wp-bind--aria-expanded="context.isOpen"
aria-controls="accordion-panel"
style="all: unset; cursor: pointer; display: flex; justify-content: space-between; align-items: center; width: 100%; padding: 1rem; font-weight: 600; font-size: 1.125rem;">
<?php echo esc_html( $a['heading'] ); ?>
<span aria-hidden="true" data-wp-text="context.isOpen ? '−' : '+'">+</span>
</button>
<div
id="accordion-panel"
role="region"
data-wp-bind--hidden="!context.isOpen"
style="padding: 0 1rem 1rem;">
<p><?php echo esc_html( $a['body'] ); ?></p>
</div>
</div>
import { store, getContext } from '@wordpress/interactivity';
store('myTheme/accordion', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
آلية العمل:
- ينشئ
data-wp-context='{ "isOpen": false }'قيمة منطقية محلية لهذه النسخة. - يؤدي النقر على الزر إلى استدعاء
actions.toggle، الذي يبدّل قيمةcontext.isOpen. - يخفي
data-wp-bind--hidden="!context.isOpen"اللوحة أو يُظهرها. - يحدّث
data-wp-bind--aria-expandedوdata-wp-textحالة الزر لأغراض إمكانية الوصول والمؤشر المرئي.
بما أن كل نسخة من الكتلة تحصل على سياقها الخاص، تعمل الأقسام القابلة للطي المتعددة في الصفحة مباشرةً، ويتبدل كل منها بشكل مستقل.
علامات التبويب
تقدّم علامات التبويب مفهومين جديدين: data-wp-class--* لتبديل فئات CSS، وgetElement() لقراءة سمات البيانات من العنصر الذي أطلق الإجراء.
يستخدم هذا المثال حقلًا مكررًا، ما يتيح للمحررين إضافة العدد الذي يحتاجونه من علامات التبويب.
{
"name": "my-theme/tabs",
"title": "Tabs",
"category": "text",
"icon": "table-row-after",
"description": "Tabbed content switcher.",
"blockstudio": {
"interactivity": true,
"attributes": [
{
"id": "tabs",
"type": "repeater",
"label": "Tabs",
"min": 1,
"max": 8,
"attributes": [
{ "id": "label", "type": "text", "label": "Tab Label", "default": "Tab" },
{ "id": "content", "type": "textarea", "label": "Content", "default": "Tab content goes here." }
]
}
]
}
}
<div useBlockProps
data-wp-interactive="myTheme/tabs"
data-wp-context='{ "activeTab": 0 }'>
<div role="tablist" style="display: flex; gap: 0; border-bottom: 2px solid #e5e7eb;">
<?php foreach ( $a['tabs'] as $i => $tab ) : ?>
<button
role="tab"
data-index="<?php echo esc_attr( $i ); ?>"
data-wp-on--click="actions.selectTab"
data-wp-class--is-active-tab="callbacks.isActiveTab"
data-wp-bind--aria-selected="callbacks.isActiveTab"
style="padding: 0.75rem 1.5rem; background: none; border: none; cursor: pointer; font-weight: 500; border-bottom: 2px solid transparent; margin-bottom: -2px;">
<?php echo esc_html( $tab['label'] ); ?>
</button>
<?php endforeach; ?>
</div>
<?php foreach ( $a['tabs'] as $i => $tab ) : ?>
<div
role="tabpanel"
data-index="<?php echo esc_attr( $i ); ?>"
data-wp-bind--hidden="!callbacks.isActiveTab"
style="padding: 1.5rem 0;">
<p><?php echo esc_html( $tab['content'] ); ?></p>
</div>
<?php endforeach; ?>
</div>
import { store, getContext, getElement } from '@wordpress/interactivity';
store('myTheme/tabs', {
actions: {
selectTab: () => {
const context = getContext();
const { ref } = getElement();
context.activeTab = parseInt(ref.dataset.index, 10);
},
},
callbacks: {
isActiveTab: () => {
const context = getContext();
const { ref } = getElement();
return context.activeTab === parseInt(ref.dataset.index, 10);
},
},
});
.is-active-tab {
border-bottom-color: currentColor !important;
color: var(--wp--preset--color--primary, #111);
}
ما الجديد هنا:
getElement()يعيد{ ref }حيث يكونrefهو عنصر DOM. نقرأdata-indexلمعرفة علامة التبويب التي نُقر عليها. وهذا يُغنينا عن إنشاء إجراء منفصل لكل علامة تبويب.callbacksقيم مشتقة يُعاد تقييمها عند تغيّر السياق. تستخدم أزرار علامات التبويب ولوحاتهاcallbacks.isActiveTabللتحقق مما إذا كان الفهرس يطابقcontext.activeTab.- يضيف
data-wp-class--is-active-tabفئةis-active-tabأو يزيلها استنادًا إلى القيمة التي يعيدها الاستدعاء.
النافذة المنبثقة
تعرّف النافذة المنبثقة معالجة الأحداث على مستوى المستند باستخدام data-wp-on-document--keydown لإغلاقها عند الضغط على Escape، كما تتيح الإغلاق بالنقر على الخلفية. وتعرض أيضًا سمات إمكانية الوصول المناسبة لمربعات الحوار.
{
"name": "my-theme/modal",
"title": "Modal",
"category": "text",
"icon": "external",
"description": "Button that opens a modal dialog.",
"blockstudio": {
"interactivity": true,
"attributes": [
{ "id": "buttonText", "type": "text", "label": "Button Text", "default": "Open Modal" },
{ "id": "title", "type": "text", "label": "Modal Title", "default": "Modal Title" },
{ "id": "body", "type": "textarea", "label": "Modal Body", "default": "Modal content goes here." }
]
}
}
<div useBlockProps
data-wp-interactive="myTheme/modal"
data-wp-context='{ "isOpen": false }'>
<button
data-wp-on--click="actions.open"
style="padding: 0.75rem 1.5rem; background: #111; color: #fff; border: none; border-radius: 6px; cursor: pointer; font-size: 1rem;">
<?php echo esc_html( $a['buttonText'] ); ?>
</button>
<div
data-wp-bind--hidden="!context.isOpen"
data-wp-on--click="actions.backdropClick"
data-wp-on-document--keydown="actions.onKeydown"
style="position: fixed; inset: 0; z-index: 9999; display: flex; align-items: center; justify-content: center; background: rgba(0,0,0,0.5);">
<div
role="dialog"
aria-modal="true"
data-wp-bind--aria-label="context.isOpen ? '<?php echo esc_attr( $a['title'] ); ?>' : false"
data-wp-on--click="actions.stopPropagation"
style="background: #fff; border-radius: 12px; padding: 2rem; max-width: 32rem; width: 100%; margin: 1rem; position: relative;">
<h2 style="margin: 0 0 1rem; font-size: 1.25rem;"><?php echo esc_html( $a['title'] ); ?></h2>
<p style="margin: 0 0 1.5rem; color: #555;"><?php echo esc_html( $a['body'] ); ?></p>
<button
data-wp-on--click="actions.close"
style="padding: 0.5rem 1rem; background: #f3f4f6; border: none; border-radius: 6px; cursor: pointer;">
Close
</button>
</div>
</div>
</div>
import { store, getContext } from '@wordpress/interactivity';
store('myTheme/modal', {
actions: {
open: () => {
const context = getContext();
context.isOpen = true;
},
close: () => {
const context = getContext();
context.isOpen = false;
},
backdropClick: () => {
const context = getContext();
context.isOpen = false;
},
stopPropagation: (event) => {
event.stopPropagation();
},
onKeydown: (event) => {
if (event.key === 'Escape') {
const context = getContext();
context.isOpen = false;
}
},
},
});
ما الجديد هنا:
data-wp-on-document--keydownيستمع إلىdocumentبدلًا من العنصر نفسه. ويعمل المعالج بصرف النظر عن العنصر الذي عليه التركيز، لذا يعمل Escape من أي مكان.- الإغلاق بالنقر على الخلفية يستخدم طبقتين: يستدعي عنصر التراكب div الإجراء
actions.backdropClick، بينما يستدعي مربع الحوار الداخليactions.stopPropagationلمنع النقرات داخله من إغلاقه. - تخبر
role="dialog"وaria-modal="true"قارئات الشاشة بأن هذا مربع حوار نمطي. ويُربطaria-labelبحيث لا يُطبّق إلا عند ظهور النافذة المنبثقة. - تخفي السمة
hiddenعلى عنصر التراكب النافذة المنبثقة وتمنع أيضًا مستمع keydown للمستند من العمل عند إغلاقها، لأن التوجيهات على العناصر المخفية تكون متوقفة مؤقتًا.
زر الإعجاب بحالة من الخادم
يجمع هذا المثال بين الحالة من جهة الخادم والإجراءات من جهة العميل. يُهيّأ عدد الإعجابات من PHP باستخدام wp_interactivity_state()، ويحدّثه الزر عند النقر عليه.
{
"name": "my-theme/like-button",
"title": "Like Button",
"category": "text",
"icon": "heart",
"description": "A like button with a count.",
"blockstudio": {
"interactivity": true,
"attributes": [
{ "id": "itemId", "type": "text", "label": "Item ID", "default": "post-1" }
]
}
}
<?php
$item_id = $a['itemId'];
$count = (int) get_option( "likes_{$item_id}", 0 );
wp_interactivity_state( 'myTheme/likeButton', array(
'count' => $count,
) );
?>
<div useBlockProps
data-wp-interactive="myTheme/likeButton"
data-wp-context='{ "liked": false }'>
<button
data-wp-on--click="actions.like"
data-wp-class--is-liked="context.liked"
style="display: inline-flex; align-items: center; gap: 0.5rem; padding: 0.5rem 1rem; border: 2px solid #e5e7eb; border-radius: 999px; background: none; cursor: pointer; font-size: 1rem; transition: all 0.2s;">
<span data-wp-text="context.liked ? '❤️' : '🤍'">🤍</span>
<span data-wp-text="state.count"><?php echo esc_html( $count ); ?></span>
</button>
</div>
import { store, getContext } from '@wordpress/interactivity';
const { state } = store('myTheme/likeButton', {
actions: {
like: () => {
const context = getContext();
if (context.liked) {
context.liked = false;
state.count--;
} else {
context.liked = true;
state.count++;
}
},
},
});
.is-liked {
border-color: #ef4444 !important;
background: #fef2f2 !important;
}
ما الجديد هنا:
wp_interactivity_state()يهيّئ العدد من PHP. وتُسلسل القيمة ضمن HTML الصفحة وتكون متاحة بصفتهاstate.countفي التوجيهات وJavaScript.stateمقابلcontext: يوجد العدد فيstate(عام ومشترك)، بينما توجدlikedفيcontext(لكل نسخة). إذا كان لديك عدة أزرار إعجاب للعنصر نفسه، فستشترك في العدد، لكن يمكن لكل زر تتبّع حالة الإعجاب الخاصة به.- تفكيك القيم من
store(): يعيد استدعاءstore()كائنstateتفاعليًا يمكنك الرجوع إليه في إجراءاتك.
تنبيه مهم: حالة الخادم متاحة في الواجهة الأمامية فقط. في المحرر، تُعرض الكتلة عبر REST API، لذا لا يُضمّن wp_interactivity_state(). يظهر النص الاحتياطي الذي يعرضه PHP (<?php echo esc_html( $count ); ?>) بوصفه القيمة الأولية في معاينة المحرر. وللحصول على حالة تفاعلية في المحرر، استخدم data-wp-context بدلًا من ذلك.
نصائح وأنماط
اصطلاحات مساحات الأسماء. استخدم اسم القالب أو الإضافة كبادئة: myTheme/accordion وmyPlugin/tabs. يمنع ذلك تعارض الأسماء عندما تستخدم كتل متعددة في الصفحة نفسها API التفاعلية.
لا حاجة إلى خطوة بناء. يحمّل Blockstudio ملف script.js كوحدة ES أصلية وينشئ importmap لـ@wordpress/interactivity تلقائيًا. اكتب JavaScript قياسيًا مع عبارات import وسيعمل مباشرةً.
كتل التوجيهات فقط. إذا كانت كتلتك تستخدم data-wp-context مع data-wp-bind--hidden أو data-wp-text فقط، فلست بحاجة إلى script.js إطلاقًا. يتولى API التفاعلي معالجة ذلك بطريقة تصريحية. يمكن أن يعمل مثال القسم القابل للطي أعلاه دون JavaScript باستخدام حيلة مربع الاختيار، لكن نهج البرنامج النصي أبسط.
تصحيح الأخطاء باستخدام data-wp-watch. أضف استدعاء مراقبة لتسجيل تغييرات السياق أثناء التطوير:
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<div data-wp-watch="callbacks.debug" ...>
أزله قبل النشر.
أبقِ السياق بسيطًا. لا تضع في data-wp-context إلا القيم التي تتغير فعلًا. اترك البيانات الثابتة مثل التسميات والمحتوى في PHP. تُسلسل JSON السياق في كل نسخة من الكتلة، لذا تزيد الكائنات الكبيرة من حجم الصفحة.
الخطوات التالية
- مرجع Interactivity: خيارات الإعداد، وتفاصيل دعم المحرر، وصيغة الكائن لإعداد
interactivity. - الأصول: كيفية تحميل Blockstudio لـ
script.jsوstyle.cssوأصول الكتل الأخرى. - مستندات Interactivity WordPress API: مرجع API الكامل، بما في ذلك
data-wp-eachوdata-wp-initوdata-wp-runوالتوجيهات الأخرى التي لا يغطيها هذا الدليل.