# كتل مخصصة في 3 ملفات

لا JavaScript، ولا خطوة بناء، ولا تعليمات تمهيدية.

## عرّف الحقول في JSON

أضف مفتاح `blockstudio` إلى block.json. عرّف السمات بأنواع مثل `text` و `toggle` و `color`. ينشئ Blockstudio محرر UI تلقائيًا، مع أنواع الحقول 27 التي تتراوح بين حقول إدخال النصوص والمكررات ومحررات الأكواد، إضافةً إلى أنواع الحقول التي تسجلها بنفسك.

يوفر دعم JSON Schema الكامل الإكمال التلقائي والتحقق في VS Code وPhpStorm وكل محرر متوافق.

يمكن لكل حقل تعيين `default` للكتل الجديدة و `fallback` يتلقاه القالب عندما يكون الحقل فارغًا.

[مرجع أنواع الحقول](https://blockstudio.dev/ar/docs/blocks/attributes/field-types/)

block.json

```
{
  "name": "starter/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading" },
      { "id": "showCta", "type": "toggle", "label": "Show CTA" },
      { "id": "background", "type": "color", "label": "Background" }
    ]
  }
}
```

## سير عمل من ثلاثة ملفات

block.json للحقول، وقالب للترميز، وورقة أنماط اختيارية.

## React في PHP

تعمل RichText وInnerBlocks وuseBlockProps مباشرةً في PHP أو Twig أو Blade.

## SCSS وTailwind

استخدم CSS أو SCSS أو Tailwind. يدعم SCSS مسارات الاستيراد ومقدمة مشتركة، وتؤدي إعادة ترجمة جزء متداخل إلى إعادة ترجمة كل ملف يستورده.

## 27 نوعًا من الحقول

النص واللون والصورة والمكرر والقائمة المنسدلة ومحرر الأكواد والمزيد، كلها تُهيأ في JSON.

## JSON Schema

إكمال تلقائي وتحقق في VS Code وPhpStorm والمحررات المتوافقة.

## ثلاث لغات للقوالب

تشترك PHP وTwig وBlade في المتغيرات والمكونات نفسها.

## استيرادات npm

استورد الحزم في script.js؛ تكون محلية في الإنتاج ومدعومة بـ CDN في المحرر.

## Interactivity API

فعّل WordPress Interactivity API بعلامة واحدة.

## مكونات React في قوالب PHP

استخدم `<RichText />` للتحرير المباشر وHTML للواجهة الأمامية الثابتة، و `<InnerBlocks />` للكتل الفرعية، و `useBlockProps` للحاوية، وكل ذلك في قالب واحد.

تتحول هذه العناصر في المحرر إلى مكونات React فعلية. وفي الواجهة الأمامية، تُعرض كـ HTML من جهة الخادم، دون إرسال JavaScript إلى الزوار.

[استكشف المكونات](https://blockstudio.dev/ar/docs/blocks/react-components/)

index.php

```
<div useBlockProps class="container">
  <RichText
    class="text-xl font-semibold"
    tag="h1"
    attribute="headline"
    placeholder="Enter headline"
  />

  <?php if ($a['showCta']): ?>
    <a href="<?= esc_url($a['ctaUrl']) ?>">
      <?= esc_html($a['ctaLabel']) ?>
    </a>
  <?php endif; ?>

  <InnerBlocks class="mt-4 p-4 border" />
</div>
```

## اكتب باستخدام PHP أو Twig أو Blade

استخدم لغة القوالب التي تعرفها. يعمل PHP مباشرة، ويعمل Twig بعد تثبيت Timber، ويعمل Blade على `illuminate/view` من 8 إلى 12 عبر `Blockstudio\Blade_Renderer`. وتظل المتغيرات والمكونات والسلوك كما هي.

تتوفر `$a` (السمات) و `$b` (الكتلة) و `$c` (السياق) و `$innerBlocks` في كل لغة.

تتلقى القوالب أيضًا السياق الكامل Twig Timber. يعرض Blade الصفحات والأنماط وقوالب محرر الموقع أيضًا. يتعطل الغلاف الأقدم `jenssegers/blade` مع `illuminate/view` 10 والإصدارات الأحدث، لذا استخدم `Blade_Renderer` بدلًا منه.

[لغات القوالب](https://blockstudio.dev/ar/docs/blocks/templating/blade/)

index.twig

```
<div useBlockProps class="card">
  <RichText tag="h2" attribute="title" placeholder="Card title" />
  {% if a.image %}
    <img src="{{ a.image.url|esc_url }}"
      alt="{{ a.image.alt|esc_attr }}" />
  {% endif %}
  <div class="card__body">{{ a.description|esc_html }}</div>
  <InnerBlocks allowedBlocks='["core/button"]' />
</div>
```

## المنطق الشرطي والخيارات الديناميكية

أظهر الحقول وأخفها باستخدام عوامل مثل `==` و `!=` و `includes` و `empty` والمقارنات. ادمج الشروط بمنطق OR.

قد تعتمد الخيارات على حقل آخر. أدرج `{attributes.post_type.value}` في وسيطات populate، وستُعاد تحميل القائمة عند تغيّر ذلك الحقل. أضف `fetch: true` للبحث في المنشورات أثناء كتابة المحرر.

شارك قائمة خيارات واحدة بين الكتل باستخدام `type: custom` والمرشح `blockstudio/blocks/attributes/populate`، وسجّل شروطك العامة الخاصة، مثل التحقق من الشراء، عبر `blockstudio/blocks/conditions`.

[المنطق الشرطي](https://blockstudio.dev/ar/docs/blocks/attributes/conditional-logic/)

block.json

```
{
  "name": "starter/posts",
  "title": "Posts",
  "blockstudio": {
    "attributes": [
      {
        "id": "post_type",
        "type": "select",
        "label": "Post type",
        "options": [
          { "value": "page", "label": "Pages" },
          { "value": "post", "label": "Posts" }
        ]
      },
      {
        "id": "selected_post",
        "type": "select",
        "label": "Post",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": { "post_type": "{attributes.post_type.value}" }
        }
      },
      {
        "id": "style",
        "type": "select",
        "label": "Style",
        "populate": { "type": "custom", "custom": "cardStyles" },
        "conditions": [[
          { "type": "purchasedProduct", "operator": "==", "value": "yes" }
        ]]
      }
    ]
  }
}
```

## حقول التكرار التي يسهل إدارتها

عيّن `min` و `max`، وابدأ الكتل الجديدة بصفوف `default`، واطوِ الصفوف الحالية باستخدام `minimized`. يعرض `textMinimized` للحقل المطوي تسميةً مأخوذة من أحد حقوله، مثل الاسم.

تقبل الصفوف جميع أنواع الحقول باستثناء علامات التبويب، بما فيها حقول التكرار المتداخلة. يتحقق الشرط داخل الصف من حقل خارجه باستخدام `"context": "main"`، ويتيح `<RichText />` و `<MediaPlaceholder />` تعديل صف واحد عندما يشير `attribute` الخاص بهما إلى `repeaterId[index].fieldId`.

[أنماط حقول التكرار](https://blockstudio.dev/ar/guides/field-patterns/#repeater-patterns)

block.json

```
{
  "name": "starter/team",
  "title": "Team",
  "blockstudio": {
    "attributes": [
      {
        "id": "members",
        "type": "repeater",
        "label": "Team members",
        "min": 1,
        "max": 12,
        "minimized": true,
        "textMinimized": { "id": "name", "fallback": "Team member" },
        "attributes": [
          { "id": "name", "type": "text", "label": "Name" },
          { "id": "bio", "type": "richtext", "label": "Bio" }
        ]
      }
    ]
  }
}
```

## مجموعات حقول قابلة لإعادة الاستخدام

عرّف مجموعة من الحقول مرة واحدة في `field.json`، واستخدمها في أي كتلة عبر `"type": "custom/cta"`. تُضمّن الحقول مباشرة، لذا تقرؤها القوالب مثل أي سمة أخرى.

استخدم المجموعة نفسها مرتين مع `idStructure` مثل `hero_{id}`، وغيّر التسميات أو القيم الافتراضية أو الشروط لكل كتلة باستخدام `overrides`. يؤدي نوع الحقل `block` الوظيفة نفسها مع كتلة كاملة: يوسّع حقول تلك الكتلة مباشرةً ويعيد HTML المعروض لها.

[حقول مخصصة](https://blockstudio.dev/ar/docs/blocks/attributes/custom-fields/)

fields/cta/field.json

```
{
  "name": "cta",
  "title": "Call to action",
  "attributes": [
    { "id": "label", "type": "text", "label": "Button label", "default": "Learn more" },
    { "id": "url", "type": "link", "label": "Button URL" }
  ]
}
```

## وحدات ES دون خطوة بناء

أضف `script.js` وسيتم تحميله كوحدة ES. استورد حزم npm باستخدام البادئة `npm:`، وسينزّلها Blockstudio محليًا للإنتاج.

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

تُستورد أوراق الأنماط بالطريقة نفسها. ينزّل `import "npm:swiper@11.0.0/swiper.min.css"` الملف ويضيفه إلى قائمة الانتظار مرة واحدة لكل إصدار، حتى عند استخدام عدة كتل له.

[معالجة الأصول](https://blockstudio.dev/ar/docs/blocks/assets/)

script.js

```
import Swiper from "npm:swiper@11.0.0";
import "npm:swiper@11.0.0/swiper.min.css";

for (const el of document.querySelectorAll(".swiper")) {
  new Swiper(el, {
    slidesPerView: 3,
    spaceBetween: 20,
    loop: true,
  });
}
```

## وسوم الكتل خارج نطاق القوالب

اربط بادئة قصيرة بمساحة أسماء في `blockstudio.json`، أو اربط وسمًا واحدًا بكتلة واحدة باستخدام مرشح alias، وسيعرض `<acme-card>` `acme/card`. فعّل `blockTags.enabled` لعرض الوسوم في محتوى المنشورات وعناصر الودجات، مع تقييدها بأنماط `allow` و `deny`.

تصل سمات `data-*` إلى العنصر الجذر للكتلة، وتصل سمات `html-*` إليه من دون البادئة. أضف أدوات إنشاء الوسوم الخاصة بك باستخدام `blockstudio/block_tags/builders`، وحوّل الصيغ المختصرة إلى الصيغة المحمولة `<bs:acme-card>` باستخدام الأمر `migrate-block-tags`.

[اقرأ الدليل](https://blockstudio.dev/ar/guides/block-tags/)

blockstudio.json

```
{
  "blockTags": {
    "enabled": true,
    "prefixes": {
      "acme": ["acme"],
      "ui": ["acme-ui"]
    },
    "deny": ["acme-ui/admin-*"]
  }
}
```

## أنواع حقول مخصصة

سجّل عنصر التحكم الخاص بحقل وأنشئه، ثم استخدمه كحقل مدمج.

## كتل الجزر

خزّن الصفحة بأكملها مؤقتًا واعرض كتلة واحدة ضمن طلب الزائر.

## التسجيل المشروط

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

## بيانات المنشور الوصفية والخيارات

خزّن القيم في البيانات الوصفية للمنشور أو الخيارات إلى جانب سمات الكتلة.

## المنطق الشرطي

اعرض الحقول بناءً على القيم باستخدام المساواة والتضمين والفراغ والمقارنات.

## مصادر ديناميكية

املأ الخيارات من المنشورات أو المستخدمين أو المصطلحات أو الدوال أو واجهات APIs.

## التجاوزات

عيّن override: true مع اسم كتلة مشتركة لدمج السمات حسب المعرّف، واستبدال الأصول ذات أسماء الملفات المتطابقة، وتبديل القالب. يمكن لقوالب Twig تجاوز كتل مفردة باستخدام extends.

## التنويعات

صرّح بالتنويعات في block.json لتعيين قيم الحقول مسبقًا، وأخفِ الحقل الذي يتحكم فيها باستخدام hidden.

## المكونات

عيّن component: true لكتلة لا تُعرض إلا من PHP أو وسوم الكتل. يحتفظ ذلك بالحقول والقوالب والأصول وTailwind، لكنه لا يظهر أبدًا في أداة الإدراج.

## قواعد InnerBlocks

اسمح بالكتل باستخدام رموز namespace/* وcategory: و@theme، وبدّل القالب الداخلي من خيار select، وأزل الغلاف في الواجهة الأمامية باستخدام مرشح.

## أصول حقل التعليمات البرمجية

يحوّل حقل التعليمات البرمجية الذي يضبط asset: true مدخلات المحرر إلى CSS أو SCSS أو JavaScript لتلك الكتلة، ويقتصر على مثيلها عبر %selector%.

## الأصول بحسب اسم الملف

*.view.js يُحمّل في الواجهة الأمامية فقط، بينما تحمّل البادئات global- وadmin- وblock-editor- ملفًا في كل صفحة أو في wp-admin أو في محرر الكتل.

## الأيقونات ومجلدات الكتل

امنح كتلة أيقونة SVG مخصصة أو أيقونة HTML، وغيّر موضع اكتشافها باستخدام المرشح blockstudio/path، وأضف مجلدات باستخدام Blockstudio\Build::init().

## قيم ACF وMeta Box

تتلقى القوالب $post_id، لذا يقرأ get_field() و rwmb_get_value() المنشور الذي يجري تحريره، ويعيد refreshOn تحميل المعاينة بعد الحفظ.

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

داخل حلقة الاستعلام، يتبع $block [‘context’][‘postId’] العنصر الحالي، بينما يظل $block [‘postId’] هو معرّف المنشور المعروض.

## WPML

ينشئ wp bs wpml config ملف wpml-config.xml الذي يحدد حقول النصوص القابلة للترجمة، وتُضاف الصور المخزنة في الحقول إلى مهام الترجمة WPML مع نصوصها البديلة وتعليقاتها.

Plus

## حزمة الإضافات الرسمية

قوالب مواقع مميزة، وتعليمات نظام للذكاء الاصطناعي، ومجتمع Discord خاص. شراء لمرة واحدة وتحديثات مدى الحياة.

- أكثر من 500+ قالب موقع
- تعليمات نظام الذكاء الاصطناعي
- تحديثات مدى الحياة
- مجتمع Discord خاص

[احصل على Plus](https://blockstudio.dev/ar/plus/)
