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

المكونات

يتضمن Blockstudio 59 UI مكوّنات مع كل عملية بناء. تُسجّل تلقائيًا، وتُنسّق باستخدام رموز التصميم، وتُكتب بصياغة الوسوم نفسها المستخدمة لأي كتلة أخرى.

يتضمن Blockstudio 7.3 مجموعة مضمّنة من كتل UI بلا واجهة مرئية، تعمل بواسطة WordPress Interactivity API. وهي مسجلة ضمن مساحة الاسم bsui/*، ويمكن تركيبها في القوالب والصفحات القائمة على الملفات والأنماط ومحتوى المنشورات.

ملاحظة

لا تزال مكونات UI في المرحلة التجريبية بينما نجمع الملاحظات حول مجموعة المكونات، وتسمياتها وسلوكها وأنماط استخدامها في المشاريع. وهي جاهزة للتجربة في 7.3، لكن قد يطرأ تحسين على واجهة API قبل اعتمادها مستقرة.

تفعيل مكونات UI

مكونات UI المضمّنة اختيارية. فعّلها في blockstudio.json الخاصة بسمتك:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "ui": {
    "enabled": true
  }
}

أو فعّلها باستخدام مرشح:

PHP
add_filter('blockstudio/settings/ui/enabled', '__return_true');

عند التفعيل، يسجل Blockstudio مكتبة المكونات المضمّنة من includes/ui/blocks.

الجرد العام والأمثلة

تظل كتل التنفيذ المضمّنة تسجيلات bsui/* عادية، لكن ينبغي للمستخدمين الاستعانة بجرد العائلات العامة عند إنشاء معرض للمكونات:

PHP
use Blockstudio\Ui;

$families = Ui::inventory();
$examples = Ui::examples();

يجمع Ui::inventory() كل مكون مركب تحت جذره العام، ويسرد تسجيلات التنفيذ المطلوبة لهذه العائلة. ويضيف Ui::examples() تعريفًا موحدًا وحتميًا يتضمن القيم الافتراضية وبيانات توضيحية. ويحافظ على العلاقات المطلوبة بين الجذر والعناصر الفرعية، لذا يمكن تمرير الناتج مباشرة إلى Blockstudio\Render::document().

يعرض الجرد العام للوحة Canvas هذه الأمثلة ضمن نوع ui، ويستبعد تسجيلات التنفيذ المضمّنة من النوع العادي blocks. وينتج عن ذلك مثال كامل واحد لكل عائلة مكونات عامة بدلًا من معرض لأجزاء الجذر والمشغل والنافذة المنبثقة والطبقة الداخلية.

عند تجميع مستند معروض مسبقًا، يعيد Ui::global_assets($block_names, $html) النمط العام والبرنامج النصي المضمّنين نفسيهما فقط عندما يستخدم الناتج المحدد مكون UI فعليًا.

العرض

استخدم صيغة وسوم الكتل المعتادة:

HTML
<block name="bsui/button" label="Save" variant="default"></block>

وتعمل أيضًا الصيغة الأقصر <bs:>:

HTML
<bs:bsui-button label="Save" variant="default" />

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

JSON
{
  "ui": {
    "enabled": true
  },
  "blockTags": {
    "enabled": true,
    "allow": ["bsui/*", "app/*"]
  }
}

المكونات الأساسية

تُعرض المكونات البسيطة ككتلة واحدة:

HTML
<block name="bsui/button" label="Continue" variant="default"></block>
<block name="bsui/badge" label="Beta"></block>
<block
  name="bsui/input"
  nameAlt="email"
  type="email"
  placeholder="Email"
></block>
<block name="bsui/textarea" name="message" placeholder="Message"></block>
<block name="bsui/spinner"></block>

تتطابق السمات مباشرةً مع سمات block.json الخاصة بكل مكون. على سبيل المثال، يدعم bsui/button label وicon وiconPosition وhref وvariant وsize وdisabled.

PHP
bs_render_block([
  'name' => 'bsui/button',
  'data' => [
    'label' => 'Continue',
    'icon' => [
      'set' => 'heroicons',
      'subSet' => 'outline',
      'icon' => 'arrow-right',
    ],
    'iconPosition' => 'right',
  ],
]);

المكونات المركبة

العديد من مكونات UI عبارة عن كتل مركبة. تتحكم الكتلة الجذرية في الحالة، وتحدد الكتل الفرعية العنصر الأب لها.

علامات التبويب

HTML
<block name="bsui/tabs" defaultValue="tab1">
  <block name="bsui/tabs-list">
    <block name="bsui/tabs-trigger" value="tab1" title="Features"></block>
    <block name="bsui/tabs-trigger" value="tab2" title="Pricing"></block>
    <block name="bsui/tabs-trigger" value="tab3" title="FAQ"></block>
  </block>
  <block name="bsui/tabs-panel" value="tab1">
    <p>Features content.</p>
  </block>
  <block name="bsui/tabs-panel" value="tab2">
    <p>Pricing content.</p>
  </block>
  <block name="bsui/tabs-panel" value="tab3">
    <p>FAQ content.</p>
  </block>
</block>

مربع الحوار

HTML
<block name="bsui/dialog">
  <block name="bsui/dialog-trigger" label="Open Dialog"></block>
  <block name="bsui/dialog-backdrop"></block>
  <block name="bsui/dialog-popup">
    <p>Dialog content.</p>
    <block name="bsui/dialog-close" label="Close"></block>
  </block>
</block>

قائمة الاختيار

HTML
<block name="bsui/select" placeholder="Choose a fruit" nameAlt="fruit">
  <block name="bsui/select-trigger"></block>
  <block name="bsui/select-popup">
    <block name="bsui/select-option" value="apple" label="Apple"></block>
    <block name="bsui/select-option" value="banana" label="Banana"></block>
    <block name="bsui/select-option" value="cherry" label="Cherry"></block>
  </block>
</block>

حقول النموذج

HTML
<block name="bsui/form" block="contact/form" successMessage="Thank you!">
  <block name="bsui/field">
    <block name="bsui/field-label" text="Email"></block>
    <block name="bsui/input" nameAlt="email" type="email"></block>
    <block name="bsui/field-error"></block>
  </block>
</block>

الكتل المتاحة

تتضمن مكتبة UI المضمّنة ما يلي:

المجال الكتل
التخطيط bsui/aspect-ratio، bsui/card، bsui/separator، bsui/stack، bsui/table
الإجراءات bsui/button، bsui/button-group، bsui/toggle، bsui/toggle-group، bsui/toolbar
المدخلات bsui/checkbox، bsui/color-picker، bsui/date-input، bsui/file-upload، bsui/input، bsui/number-field، bsui/otp-input، bsui/password-input، bsui/phone-input، bsui/radio-group، bsui/rating، bsui/select، bsui/slider، bsui/switch، bsui/textarea، bsui/time-picker
الطبقات المنبثقة bsui/alert-dialog، bsui/dialog، bsui/drawer، bsui/menu، bsui/menubar، bsui/popover، bsui/preview-card، bsui/tooltip
التنقل bsui/accordion، bsui/breadcrumb، bsui/carousel، bsui/collapsible، bsui/context-menu، bsui/navigation-menu، bsui/pagination، bsui/tabs
الملاحظات bsui/badge، bsui/kbd، bsui/meter، bsui/progress، bsui/skeleton، bsui/spinner، bsui/text، bsui/toast
النماذج bsui/field، bsui/field-group، bsui/form

تكشف المكونات المركبة أيضًا عن كتل فرعية مثل bsui/dialog-trigger وbsui/dialog-popup وbsui/tabs-list وbsui/tabs-trigger وbsui/tabs-panel وbsui/select-trigger وbsui/select-popup وbsui/select-option.

التنسيق

تأتي مكونات UI بخصائص مخصصة خاصة بها من CSS، وتستخدم السابقة --bs-ui-*. يمكنك تجاوز قيمها من ملف CSS الخاص بسمتك:

CSS
:root {
  --bs-ui-radius: 0.5rem;
  --bs-ui-primary: oklch(0.45 0.18 260);
  --bs-ui-primary-foreground: white;
}

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

تُصدر CSS المكونات المضمّنة في طبقة التتالي المسماة bsui. ويمكن لقواعد CSS غير الموجودة في طبقة ضمن السمة تجاوز قواعد المكونات دون !important:

CSS
.button-brand {
  background: var(--brand-primary);
}

لإضافة متغير bsui/button مخصص، ألحِق خيار قائمة الاختيار باستخدام مرشح السمات الموجود، ووفّر CSS الخاص بالمتغير مع blockstudio/ui/button/variants-style:

PHP
add_filter('blockstudio/blocks/attributes', function($attribute, $block) {
  if (($block['name'] ?? '') === 'bsui/button' && ($attribute['id'] ?? '') === 'variant') {
    $attribute['options'][] = [
      'label' => 'Brand',
      'value' => 'brand',
    ];
  }

  return $attribute;
}, 10, 2);

add_filter('blockstudio/ui/button/variants-style', function($css) {
  return $css . '
[data-bsui-button][data-variant="brand"] {
  background: var(--brand-primary);
  color: white;
}';
});

جميع المكونات

قائمة الأكورديون أقسام متراصة يتوسّع منها قسم واحد في كل مرة. مربع حوار التنبيه نافذة مشروطة توقف سير العمل وتتطلب إجابة قبل إغلاقها. نسبة العرض إلى الارتفاع يثبّت المحتوى على نسبة محددة بين العرض والارتفاع. الصورة الرمزية صورة مستخدم تعرض الأحرف الأولى عند تعذّر تحميلها. شارة شارة صغيرة للحالة والأعداد والفئات. مسار التنقل تُظهر موضع الصفحة الحالية ضمن التسلسل الهرمي. زر ينفّذ إجراءً، مع أشكال مختلفة لكل مستوى من مستويات التأكيد. مجموعة الأزرار يجمع الأزرار المرتبطة في عنصر تحكم واحد مقسّم. تقويم شبكة تواريخ لاختيار يوم واحد. بطاقة مساحة تجمع رأسًا ومتنًا وتذييلًا. عرض دوّار مسار شرائح قابل للسحب مع دعم لوحة المفاتيح. مربع اختيار خيار ثنائي يدعم أيضًا حالة غير محددة. قابل للطي يخفي منطقة محتوى واحدة ويعرضها. أداة اختيار اللون يختار لونًا ويرسله مع النموذج المحيط به. مربع الخيارات حقل نصي يصفّي قائمة الخيارات أثناء الكتابة. قائمة السياق إجراءات تظهر عند النقر بزر الفأرة الأيمن، ومثبتة عند موضع المؤشر. حقل إدخال التاريخ حقل مقنّع لإدخال التواريخ دون أداة اختيار. مربع الحوار طبقة نافذة مشروطة للمهام المركّزة والتأكيدات. اللوحة الجانبية لوحة تنزلق من أي حافة للشاشة. الحقل يجمع عنصر تحكم واحدًا مع تسميته ووصفه ورسالة الخطأ. مجموعة الحقول يجمع الحقول المرتبطة تحت عنوان مشترك. تحميل ملف منطقة إسقاط لاختيار الملفات، مع دعم ملفات متعددة. نموذج يرسل حقوله ويعرض النجاح دون إعادة تحميل الصفحة. الإدخال حقل نصي من سطر واحد لجميع أنواع الإدخال الشائعة. اختصار لوحة المفاتيح يعرض اختصار لوحة مفاتيح داخل مفتاح مستقل. تسمية تسمية توضيحية لعنصر تحكم، مشتركة بين جميع المكونات ذات التسميات. القائمة قائمة منسدلة بالإجراءات مثبتة إلى عنصر تشغيل. شريط القوائم شريط أفقي من القوائم، مثل تطبيقات سطح المكتب. مقياس يعرض قياسًا ضمن نطاق معروف. قائمة التنقل تنقل الموقع بروابط متداخلة ولوحات تظهر عند التمرير. حقل الرقم إدخال رقمي بأزرار زيادة ونقصان ونطاق محدود. حقل إدخال رمز OTP خانات منفصلة لإدخال رمز مرور لمرة واحدة. ترقيم الصفحات روابط صفحات تتضمن السابق والتالي والاختصار. حقل إدخال كلمة المرور حقل كلمة مرور مع زر لإظهارها. حقل إدخال رقم الهاتف حقل هاتف مع اختيار البلد والتنسيق. نافذة منبثقة محتوى منسق مثبت إلى عنصر تشغيل، ويُغلق عند النقر خارجه. بطاقة المعاينة بطاقة تظهر عند التمرير لمعاينة وجهة الرابط. التقدم تُظهر مدى التقدم في المهمة. مجموعة أزرار الاختيار الدائرية مجموعة خيارات يمكن اختيار خيار واحد منها فقط. التقييم عنصر تحكم بالنجوم لتسجيل التقييم. منطقة التمرير حاوية تمرير بأشرطة تمرير متراكبة ومنسقة. اختر قائمة منسدلة للاختيار من قائمة خيارات. فاصل خط يفصل المحتوى أو مجموعات عناصر التحكم. هيكل تحميل شكل نائب يظهر إلى حين تحميل المحتوى. شريط تمرير يختار قيمة أو نطاقًا بالسحب على مسار. مسافة خطوة ثابتة للإيقاع الرأسي من مقياس التباعد. مؤشر دوار يشير إلى عمل جارٍ دون مدة معروفة. تكديس يرتب العناصر التابعة في صف أو عمود مع تباعد ثابت. مفتاح تبديل يبدّل إعدادًا يُطبّق فورًا. جدول بيانات جدولية مع إمكانية الفرز والتظليل الاختياري للصفوف. علامات تبويب يتنقل بين لوحات تشغل المساحة نفسها. Text يعرض نصًا بحجم ووسم دلالي محددين. منطقة نص حقل نصي متعدد الأسطر يزداد ارتفاعه مع عدد صفوفه. منتقي الوقت يختار وقتًا من اليوم بخطوة محددة. موفّر الإشعارات المنبثقة يستضيف إشعارات مؤقتة في أحد أركان الشاشة. تبديل زر يبقى مضغوطًا لتمثيل حالة التشغيل. مجموعة التبديل مجموعة مفاتيح تبديل تعمل للاختيار المفرد أو المتعدد. شريط الأدوات صف من عناصر التحكم ينتقل التركيز بينها. تلميح تلميح قصير يظهر عند التمرير أو التركيز.