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

سياق الكتل والتواصل

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

يوفر WordPress سياق الكتلAPI لهذا الغرض. يكشف العنصر الأصل عن بعض بياناته، وتشترك فيها الكتل الفرعية. وعندما يتغير الأصل، تُحدّث العناصر الفرعية تلقائيًا. يبسّط Blockstudio ذلك كثيرًا: فلا تحتاج إلى إعداد providesContext إطلاقًا. توفر كل كتلة Blockstudio سماتها تلقائيًا ضمن السياق. ولا تحتاج الكتل الفرعية سوى إلى سطر واحد في block.json للاشتراك.

يبني هذا الدليل أربعة أنماط مكونات واقعية تستخدم السياق، ويعرض كل منها حاجة مختلفة للتواصل.

آلية عمل السياق في Blockstudio

في WordPress القياسي، عليك تعيين كل سمة في العنصر الأصل إلى مفتاح سياق صراحةً ضمن providesContext، ثم إدراج تلك المفاتيح في usesContext للعنصر الفرعي. أما Blockstudio فيلغي الخطوة الأولى تمامًا.

الكتلة الأصل: لا يلزم إعداد أي شيء. توفر كل كتلة Blockstudio جميع سماتها تلقائيًا باسم الكتلة.

الكتلة الفرعية: أضف usesContext مع اسم الكتلة الأصلية:

JSON
{
  "usesContext": ["my-theme/parent-block"]
}

قالب الكتلة الفرعية: يمكنك الوصول إلى سمات الكتلة الأصلية عبر $context (أو الصيغة المختصرة $c):

PHP
<?php $parent = $context['my-theme/parent-block']; ?>
<p>Parent says: <?php echo esc_html( $parent['message'] ); ?></p>

هذا كل ما يلزم للإعداد. لا حاجة إلى providesContext في الأصل، ولا تعيين للسمات، ولا شيفرة تسجيل. تتلقى الكتلة الفرعية جميع سمات الأصل بعد تحويلها؛ إذ تُحل حقول الوسائط إلى بيانات المرفقات، وتحترم حقول الاختيار returnFormat، وتُوسّع المكرّرات بالكامل.

نوعا السياق

يوفر Blockstudio متغيري سياق في القوالب، ولكل منهما غرض مختلف:

المتغير المحتوى حالة الاستخدام
$context / $c سمات الكتلة الأصلية (عبر usesContext) التواصل بين المكونات
$block['context'] / $b['context'] بيانات حلقة WordPress (postId، postType) حلقات كتل الاستعلام

الأول مخصص لتواصل الكتل مع كتلها الأصلية. والثاني مخصص للكتل داخل حلقة استعلام التي تحتاج إلى معرفة المقالة التي تعرضها. يركز هذا الدليل على النوع الأول.

دعم المحرر

تتفاعل تحديثات السياق تلقائيًا في المحرر. عندما يغيّر المستخدم قيمة حقل في كتلة أصلية، تعيد جميع الكتل الفرعية المشتركة في سياق تلك الكتلة عرض نفسها تلقائيًا بالقيمة الجديدة. لا حاجة إلى تحديث يدوي.

غلاف القسم

أشيع أنماط السياق هو كتلة غلاف توفر إعدادات السمة للكتل التابعة لها. تحتوي الكتلة الأصلية على حقول للون الخلفية ولون النص والحشو. وتقرأ الكتل الفرعية هذه القيم لتنسيق نفسها بصورة متسقة.

الأصل: القسم

JSON
{
  "name": "my-theme/section",
  "title": "Section",
  "category": "design",
  "icon": "align-wide",
  "description": "Section wrapper with theme settings.",
  "blockstudio": {
    "attributes": [
      {
        "id": "theme",
        "type": "select",
        "label": "Theme",
        "default": "light",
        "options": [
          { "value": "light", "label": "Light" },
          { "value": "dark", "label": "Dark" },
          { "value": "accent", "label": "Accent" }
        ]
      },
      {
        "id": "spacing",
        "type": "select",
        "label": "Spacing",
        "default": "md",
        "options": [
          { "value": "sm", "label": "Small" },
          { "value": "md", "label": "Medium" },
          { "value": "lg", "label": "Large" }
        ]
      }
    ]
  }
}
PHP
<?php
$theme_classes = array(
	'light'  => 'bg-white text-gray-900',
	'dark'   => 'bg-gray-900 text-white',
	'accent' => 'bg-indigo-600 text-white',
);
$spacing_classes = array(
	'sm' => 'py-8',
	'md' => 'py-16',
	'lg' => 'py-24',
);
$classes = ( $theme_classes[ $a['theme'] ] ?? '' ) . ' ' . ( $spacing_classes[ $a['spacing'] ] ?? '' );
?>
<div useBlockProps class="<?php echo esc_attr( $classes ); ?>">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/section-heading', 'my-theme/section-text', 'core/columns', 'core/group' ) ) ); ?>'
  />
</div>

الفرع: عنوان القسم

JSON
{
  "name": "my-theme/section-heading",
  "title": "Section Heading",
  "category": "design",
  "icon": "heading",
  "description": "Heading that adapts to section theme.",
  "usesContext": ["my-theme/section"],
  "parent": ["my-theme/section"],
  "blockstudio": {
    "attributes": [
      { "id": "text", "type": "text", "label": "Heading", "default": "Section Title" },
      {
        "id": "size",
        "type": "select",
        "label": "Size",
        "default": "lg",
        "options": [
          { "value": "sm", "label": "Small" },
          { "value": "lg", "label": "Large" },
          { "value": "xl", "label": "Extra Large" }
        ]
      }
    ]
  }
}
PHP
<?php
$section = $context['my-theme/section'] ?? array();
$theme   = $section['theme'] ?? 'light';

$color_class = match ( $theme ) {
	'light'  => 'text-gray-900',
	'dark'   => 'text-white',
	'accent' => 'text-white',
	default  => 'text-gray-900',
};

$size_class = match ( $a['size'] ) {
	'sm' => 'text-2xl',
	'lg' => 'text-4xl',
	'xl' => 'text-6xl',
	default => 'text-4xl',
};
?>
<h2 useBlockProps class="<?php echo esc_attr( "$color_class $size_class font-bold" ); ?>">
  <?php echo esc_html( $a['text'] ); ?>
</h2>

ما يوضحه هذا المثال: لا يحتوي العنوان على حقل لون خاص به. بل يقرأ قيمة theme للقسم من السياق ويتكيف معها. عندما يغيّر المستخدم القسم من «فاتح» إلى «داكن» في المحرر، يتغير لون نص العنوان فورًا.

تقيّد الخاصية parent في block.json مواضع إدراج الكتلة. فهي لا تظهر في أداة الإدراج إلا عندما يكون المستخدم داخل كتلة my-theme/section. هذا الخيار اختياري، لكنه موصى به للكتل التي لا يكون لها معنى إلا داخل كتلة أصلية معينة.

الفرع: نص القسم

JSON
{
  "name": "my-theme/section-text",
  "title": "Section Text",
  "category": "design",
  "icon": "text",
  "description": "Body text that adapts to section theme.",
  "usesContext": ["my-theme/section"],
  "parent": ["my-theme/section"],
  "blockstudio": {
    "attributes": [
      { "id": "text", "type": "textarea", "label": "Text", "default": "Section body text." }
    ]
  }
}
PHP
<?php
$section = $context['my-theme/section'] ?? array();
$theme   = $section['theme'] ?? 'light';

$color_class = match ( $theme ) {
	'dark', 'accent' => 'text-white/80',
	default          => 'text-gray-600',
};
?>
<p useBlockProps class="<?php echo esc_attr( "$color_class text-lg leading-relaxed" ); ?>">
  <?php echo esc_html( $a['text'] ); ?>
</p>

أصبح كل من العنوان والنص يستجيب الآن لسمة القسم. يختار المستخدم السمة مرة واحدة في الكتلة الأصلية، ثم تتكيف معها كل كتلة فرعية.

شبكة البطاقات

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

الأصل: شبكة البطاقات

JSON
{
  "name": "my-theme/card-grid",
  "title": "Card Grid",
  "category": "design",
  "icon": "grid-view",
  "description": "Responsive card grid with configurable columns.",
  "blockstudio": {
    "attributes": [
      {
        "id": "columns",
        "type": "range",
        "label": "Columns",
        "default": 3,
        "min": 1,
        "max": 4,
        "step": 1
      },
      {
        "id": "gap",
        "type": "select",
        "label": "Gap",
        "default": "md",
        "options": [
          { "value": "sm", "label": "Small" },
          { "value": "md", "label": "Medium" },
          { "value": "lg", "label": "Large" }
        ]
      },
      {
        "id": "cardStyle",
        "type": "select",
        "label": "Card Style",
        "default": "elevated",
        "options": [
          { "value": "elevated", "label": "Elevated (shadow)" },
          { "value": "outlined", "label": "Outlined (border)" },
          { "value": "flat", "label": "Flat (no decoration)" }
        ]
      }
    ]
  }
}
PHP
<?php
$gap_class = match ( $a['gap'] ) {
	'sm' => 'gap-4',
	'md' => 'gap-6',
	'lg' => 'gap-8',
	default => 'gap-6',
};
?>
<div useBlockProps class="grid grid-cols-<?php echo esc_attr( $a['columns'] ); ?> <?php echo esc_attr( $gap_class ); ?>">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/card' ) ) ); ?>'
    template='<?php echo esc_attr( wp_json_encode( array(
      array( 'my-theme/card', array() ),
      array( 'my-theme/card', array() ),
      array( 'my-theme/card', array() ),
    ) ) ); ?>'
  />
</div>

الفرع: البطاقة

JSON
{
  "name": "my-theme/card",
  "title": "Card",
  "category": "design",
  "icon": "cover-image",
  "description": "Card that inherits style from its grid parent.",
  "usesContext": ["my-theme/card-grid"],
  "parent": ["my-theme/card-grid"],
  "blockstudio": {
    "attributes": [
      { "id": "image", "type": "files", "label": "Image", "multiple": false },
      { "id": "title", "type": "text", "label": "Title", "default": "Card Title" },
      { "id": "description", "type": "textarea", "label": "Description", "default": "Card description goes here." },
      { "id": "url", "type": "link", "label": "Link" }
    ]
  }
}
PHP
<?php
$grid      = $context['my-theme/card-grid'] ?? array();
$card_style = $grid['cardStyle'] ?? 'elevated';

$style_class = match ( $card_style ) {
	'elevated' => 'bg-white rounded-xl shadow-md',
	'outlined' => 'bg-white rounded-xl border border-gray-200',
	'flat'     => 'bg-gray-50 rounded-xl',
	default    => 'bg-white rounded-xl shadow-md',
};
?>
<div useBlockProps class="<?php echo esc_attr( "$style_class overflow-hidden" ); ?>">
  <?php if ( $a['image'] ) : ?>
    <img
      src="<?php echo esc_url( $a['image']['url'] ); ?>"
      alt="<?php echo esc_attr( $a['image']['alt'] ); ?>"
      class="w-full aspect-video object-cover" />
  <?php endif; ?>
  <div class="p-6">
    <h3 class="text-lg font-semibold"><?php echo esc_html( $a['title'] ); ?></h3>
    <p class="mt-2 text-gray-600"><?php echo esc_html( $a['description'] ); ?></p>
    <?php if ( $a['url'] ) : ?>
      <a href="<?php echo esc_url( $a['url']['url'] ); ?>" class="mt-4 inline-block text-indigo-600 font-medium">
        <?php echo esc_html( $a['url']['title'] ?: 'Learn more' ); ?>
      </a>
    <?php endif; ?>
  </div>
</div>

ما يوضحه هذا المثال: لا تحتوي البطاقة على حقل تنسيق خاص بها. بل تقرأ cardStyle من الكتلة الأصلية للشبكة. عندما يغيّر المستخدم نمط الشبكة من «بارز» إلى «محدد بإطار»، تتحدث كل بطاقة فيها دفعة واحدة. وهذا يحافظ على اتساق مظهر البطاقات دون أن يضطر المستخدم إلى تحديث كل واحدة على حدة.

تملأ السمة template في <InnerBlocks> الشبكة مسبقًا بثلاث بطاقات، لتمنح المستخدم نقطة بداية.

جدول الأسعار

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

الأصل: جدول الأسعار

JSON
{
  "name": "my-theme/pricing-table",
  "title": "Pricing Table",
  "category": "text",
  "icon": "money-alt",
  "description": "Pricing comparison with shared currency and billing settings.",
  "blockstudio": {
    "attributes": [
      {
        "id": "currency",
        "type": "select",
        "label": "Currency",
        "default": "usd",
        "options": [
          { "value": "usd", "label": "USD ($)" },
          { "value": "eur", "label": "EUR (\u20ac)" },
          { "value": "gbp", "label": "GBP (\u00a3)" }
        ]
      },
      {
        "id": "period",
        "type": "select",
        "label": "Billing Period",
        "default": "month",
        "options": [
          { "value": "month", "label": "Monthly" },
          { "value": "year", "label": "Yearly" }
        ]
      }
    ]
  }
}
PHP
<div useBlockProps class="grid grid-cols-3 gap-6 items-start">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/pricing-tier' ) ) ); ?>'
    template='<?php echo esc_attr( wp_json_encode( array(
      array( 'my-theme/pricing-tier', array( 'name' => 'Starter', 'price' => 9 ) ),
      array( 'my-theme/pricing-tier', array( 'name' => 'Pro', 'price' => 29, 'highlighted' => true ) ),
      array( 'my-theme/pricing-tier', array( 'name' => 'Enterprise', 'price' => 99 ) ),
    ) ) ); ?>'
  />
</div>

الفرع: فئة السعر

JSON
{
  "name": "my-theme/pricing-tier",
  "title": "Pricing Tier",
  "category": "text",
  "icon": "tag",
  "description": "Single pricing tier that reads currency from parent.",
  "usesContext": ["my-theme/pricing-table"],
  "parent": ["my-theme/pricing-table"],
  "blockstudio": {
    "attributes": [
      { "id": "name", "type": "text", "label": "Tier Name", "default": "Plan" },
      { "id": "price", "type": "number", "label": "Price", "default": 0 },
      { "id": "highlighted", "type": "toggle", "label": "Highlighted", "default": false },
      {
        "id": "features",
        "type": "repeater",
        "label": "Features",
        "attributes": [
          { "id": "text", "type": "text", "label": "Feature" }
        ]
      }
    ]
  }
}
PHP
<?php
$table    = $context['my-theme/pricing-table'] ?? array();
$currency = $table['currency'] ?? 'usd';
$period   = $table['period'] ?? 'month';

$symbols = array(
	'usd' => '$',
	'eur' => "\u{20AC}",
	'gbp' => "\u{00A3}",
);
$symbol = $symbols[ $currency ] ?? '$';

$period_label = $period === 'year' ? '/year' : '/month';

$border_class = $a['highlighted'] ? 'border-2 border-indigo-600' : 'border border-gray-200';
?>
<div useBlockProps class="<?php echo esc_attr( "rounded-xl p-8 $border_class" ); ?>">
  <h3 class="text-lg font-semibold"><?php echo esc_html( $a['name'] ); ?></h3>
  <div class="mt-4">
    <span class="text-4xl font-bold"><?php echo esc_html( $symbol . $a['price'] ); ?></span>
    <span class="text-gray-500"><?php echo esc_html( $period_label ); ?></span>
  </div>
  <?php if ( ! empty( $a['features'] ) ) : ?>
    <ul class="mt-6 space-y-3">
      <?php foreach ( $a['features'] as $feature ) : ?>
        <li class="flex items-center gap-2">
          <span class="text-indigo-600">&#10003;</span>
          <?php echo esc_html( $feature['text'] ); ?>
        </li>
      <?php endforeach; ?>
    </ul>
  <?php endif; ?>
</div>

ما يوضحه هذا المثال: يُحدَّد رمز العملة وفترة الفوترة مرة واحدة في جدول الأسعار، وترثهما كل فئة. عندما يغيّر المستخدم العملة من USD إلى EUR، تتحدث رموز العملة في الفئات الثلاث كلها في الوقت نفسه. ومن دون السياق، ستحتاج إلى تكرار حقل العملة في كل فئة وإبقائها متزامنة يدويًا.

سياق حلقة الاستعلام

هناك نوع منفصل من السياق يوفره WordPress داخل حلقات كتل الاستعلام. عندما تُعرض كتلة داخل حلقة، يحتوي $block['context'] (أو $b['context']) على بيانات المقالة الخاصة بالتكرار الحالي:

PHP
<?php
$loop_post_id   = $block['context']['postId'];
$loop_post_type = $block['context']['postType'];
?>
<article useBlockProps>
  <h2><?php echo esc_html( get_the_title( $loop_post_id ) ); ?></h2>
  <p><?php echo esc_html( get_the_excerpt( $loop_post_id ) ); ?></p>
  <a href="<?php echo esc_url( get_permalink( $loop_post_id ) ); ?>">Read more</a>
</article>

يختلف هذا عن سياق الكتلة الأصلية ($context / $c). يوفر نواة WordPress سياق الحلقة، ولا يحتوي إلا على postId وpostType. لا تحتاج إلى usesContext في block.json لهذا الغرض. يشترك Blockstudio تلقائيًا في postId وpostType لكل كتلة.

مواضع الاستفادة من سياق الحلقة: بطاقات المقالات المخصصة داخل كتل الاستعلام، والكتل التي تعرض بيانات المقالة الوصفية، وأي كتلة تحتاج إلى عرض مختلف لكل مقالة في الحلقة.

يمكنك أيضًا الوصول إلى بيانات مقالة الصفحة الخارجية، بصرف النظر عن سياق الحلقة:

PHP
$outer_post_id   = $block['postId'];   // always the current page
$loop_post_id    = $block['context']['postId'];  // current loop iteration

السياق المتداخل

ينتقل السياق عبر شجرة الكتل بأكملها، وليس إلى مستوى واحد فقط. إذا احتوت الكتلة A على الكتلة B التي تحتوي بدورها على الكتلة C، فيمكن لـ C الاشتراك في سياق A. وينجح ذلك لأن WordPress ينقل السياق عبر كل مستويات InnerBlocks.

الكود
my-theme/section (theme: "dark")
└── core/columns
    └── core/column
        └── my-theme/section-heading (reads section context)

ليس من الضروري أن يكون العنوان ابنًا مباشرًا للقسم. يمكن أن يكون متداخلًا داخل كتل أساسية (مثل الأعمدة والمجموعات وغيرها) مع استمراره في تلقي سياق القسم. يعمل اشتراك usesContext على أي مستوى من التداخل.

عدة كتل أصلية

يمكن للكتلة الفرعية الاشتراك في سياق عدة كتل أصلية:

JSON
{
  "usesContext": ["my-theme/section", "my-theme/card-grid"]
}
PHP
<?php
$section = $context['my-theme/section'] ?? array();
$grid    = $context['my-theme/card-grid'] ?? array();

$theme     = $section['theme'] ?? 'light';
$cardStyle = $grid['cardStyle'] ?? 'elevated';
?>

إذا لم يُعثر على كتلة أصلية في شجرة الأسلاف، فسيكون مفتاحها غائبًا عن $context. استخدم دائمًا معامل الدمج مع null ‏(??) أو تحقق من isset() عند قراءة قيم السياق، تحسبًا لاستخدام الكتلة خارج الكتلة الأصلية المتوقعة.

كتابة كود دفاعي

ينبغي للكتل التي تستخدم السياق أن تتعامل دائمًا مع احتمال غياب الكتلة الأصلية. فقد يدرج المستخدم الكتلة خارج موضعها المقصود، أو قد لا تكون هناك قيمة معينة لحقل في الكتلة الأصلية.

PHP
<?php
// Always provide defaults
$section = $context['my-theme/section'] ?? array();
$theme   = $section['theme'] ?? 'light';
$spacing = $section['spacing'] ?? 'md';
?>

إذا أردت فرض ظهور الكتلة الفرعية داخل كتلتها الأصلية فقط، فأضف الخاصية parent:

JSON
{
  "parent": ["my-theme/section"]
}

يؤدي ذلك إلى إزالة الكتلة من أداة الإدراج عندما لا يكون المستخدم داخل كتلة my-theme/section. ومن دون parent، تظهر الكتلة في كل مكان، ويصبح على القالب التعامل بسلاسة مع غياب السياق.

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

نصائح

السياق للقراءة فقط. لا تستطيع الكتل الفرعية تعديل سمات الكتلة الأصلية عبر السياق. تتدفق البيانات إلى الأسفل ولا تعود إلى الأعلى. إذا احتاجت كتلة فرعية إلى التواصل مع كتلتها الأصلية، فستحتاج إلى نهج آخر، مثل حالة مشتركة على الخادم عبر Interactivity API أو بيانات المقالة الوصفية.

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

القيم المحوّلة. تمر قيم السياق عبر مسار تحويل السمات في Blockstudio. تحتوي حقول الملفات على بيانات المرفق كاملة (url وalt وwidth وheight)، وتحترم حقول الاختيار returnFormat، وتُوسّع الحقول المتكررة تكراريًا. وستحصل على بنية البيانات نفسها التي يوفرها $a في قالب الكتلة الأصلية.

تفاعلية المحرر. عندما يغيّر المستخدم حقلًا في الكتلة الأصلية داخل المحرر، تعيد الكتل الفرعية عرض نفسها تلقائيًا. ويستخدم ذلك نشر السياق المدمج في WordPress مع React useEffect يرصد تغييرات السياق ويؤدي إلى إعادة عرض الكتلة الفرعية على الخادم.

اجعل السياق مقتصدًا. مع أن Blockstudio يوفر كل سمات الكتلة الأصلية تلقائيًا، ينبغي للكتل الفرعية قراءة القيم التي تحتاج إليها فقط. لا يتعلق الأمر بالأداء، فالبيانات موجودة بالفعل، بل بوضوح الكود. وثّق حقول الكتلة الأصلية التي تعتمد عليها الكتلة الفرعية، ليفهم المطورون مستقبلًا العلاقة بينها.

الخطوات التالية

  • مرجع السياق: متغيرات القوالب، وسياق الحلقة، وبنية البيانات $block.
  • InnerBlocks: المكوّن <InnerBlocks />، وallowedBlocks، والقوالب، ومرشح غلاف الواجهة الأمامية.
  • دليل Interactivity: للتفاعلية من جهة العميل بين الكتل (يتولى Interactivity API ما لا يستطيع السياق التعامل معه: التواصل من الكتلة الفرعية إلى الأصلية، والحالة المشتركة بين الكتل، والتحديثات التي يبدأها المستخدم).