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

نشر سجل كتل على GitHub

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

يقع سجل الكتل بين هذين الخيارين. فهو ملف registry.json ومجموعة من مجلدات الكتل، تُتاح عبر HTTP عادي. ينفذ المستهلكون أمر CLI، فيُنسخ مصدر الكتلة إلى قالبهم، ومنذ ذلك الحين تصبح تلك النسخة ملكهم. يكفي مستودع GitHub لاستضافة السجل، لأن GitHub يتيح كل ملف في المستودع العام عبر عنوان URL خام.

ينشئ هذا الدليل سجلًا باسم acme يضم أربع كتل، وينشره من المستودع acme/acme-blocks، ويثبت الكتل منه في قالب، ثم يثبت إصدارًا باستخدام وسم git.

حزمة blockstudio على npm بالإصدار 0.0.1. وهذا الإصدار تمهيدي: أمرها الوحيد، add، يطبع Adding block: <name> ثم ينتهي من دون جلب أي شيء. تأتي الأوامر والمخرجات في هذا الدليل من سجل CLI في مستودع Blockstudio (packages/registry)، وهو CLI الذي تصفه وثائق السجل.

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

هناك ملفان ينبغي معرفتهما:

  • ينشر مؤلف الكتل الملف registry.json. وهو يسرد الكتل والملفات التي تتكون منها كل كتلة، وbaseUrl لتنزيلها منه.
  • يوجد blocks.json في قالب المستهلك أو إضافته. ويحدد السجلات المراد استخدامها والمجلد الذي تُثبّت فيه الكتل.

عند تثبيت كتلة، يجلب CLI كل سجل في blocks.json، ويعثر على الكتلة، ويحل تبعياتها، وينزّل كل ملف مدرج من {baseUrl}/{block}/{file}، ثم يكتبه في {directory}/{block}/{file}. لا يُجري أي تحويل، لذا تطابق الملفات الموجودة على القرص الملفات الموجودة في المستودع تمامًا.

الخطوة 1: تنظيم المستودع

أنشئ مستودعًا يتضمن registry.json في الجذر ومجلدًا لكل كتلة ضمن blocks/:

الكود
acme-blocks/
  registry.json
  blocks/
    hero/
      block.json
      index.php
    card/
      block.json
      index.php
      style.scss
    tabs/
      block.json
      index.php
      style.scss
    tab-item/
      block.json
      index.php

اسم المجلد هو اسم الكتلة في السجل، وسيصبح اسم المجلد في قالب المستهلك. اجعله مطابقًا للنصف الثاني من اسم الكتلة في block.json (يوجد acme/hero ضمن hero/)، كي يسهل التعرّف على المجلد بعد تثبيته.

الخطوة 2: كتابة الكتل

كل مجلد هو كتلة Blockstudio عادية. تحتوي كتلة القسم الرئيسي على حقل واحد:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/hero",
  "title": "Hero",
  "category": "design",
  "blockstudio": {
    "attributes": [
      {
        "id": "heading",
        "type": "text",
        "label": "Heading",
        "default": "Build faster"
      }
    ]
  }
}
PHP
<section useBlockProps class="acme-hero">
  <h1><?php echo esc_html( $a['heading'] ); ?></h1>
</section>

يتبع card النمط نفسه ويضيف style.scss. يعرض tabs <InnerBlocks allowedBlocks='["acme/tab-item"]' />، ويعرّف tab-item "parent": ["acme/tabs"]، لذا لا يفيد tabs من دون tab-item. يوضّح السجل هذه العلاقة في الخطوة التالية.

لا شيء في هذه الكتل خاص بالسجل. ينسخ CLI المجلدات، لذا يمكن نشر الكتلة بالطريقة نفسها سواء أُنشئت باستخدام @wordpress/create-block أم سُجّلت باستخدام PHP العادي.

الخطوة 3: كتابة registry.json

يسرد registry.json كل كتلة وكل ملف ينبغي أن ينزّله CLI:

JSON
{
  "$schema": "https://blockstudio.dev/schema/registry.json",
  "name": "acme",
  "description": "Acme block library.",
  "baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/main/blocks",
  "blocks": [
    {
      "name": "hero",
      "title": "Hero",
      "description": "Full-width hero section with a heading.",
      "category": "layout",
      "type": "blockstudio",
      "files": ["block.json", "index.php"]
    },
    {
      "name": "card",
      "title": "Card",
      "description": "Content card with a title.",
      "category": "components",
      "type": "blockstudio",
      "files": ["block.json", "index.php", "style.scss"]
    },
    {
      "name": "tabs",
      "title": "Tabs",
      "description": "Tabbed content with keyboard navigation.",
      "category": "layout",
      "type": "blockstudio",
      "dependencies": ["tab-item"],
      "files": ["block.json", "index.php", "style.scss"]
    },
    {
      "name": "tab-item",
      "title": "Tab Item",
      "description": "Single tab panel used inside Tabs.",
      "category": "layout",
      "type": "blockstudio",
      "files": ["block.json", "index.php"]
    }
  ]
}

تحدد بعض القواعد صلاحية هذا الملف:

  • files قائمة صريحة. ينزّل CLI هذه المسارات تحديدًا ولا شيء سواها. لا تُستخدم أنماط glob، لذا لا يُضمّن أي أصل جديد إلا بعد إضافته هنا. ويمكن أن تتضمن المسارات مجلدات فرعية تُنشأ عند التثبيت.
  • يجب أن يكون baseUrl عنوان URL مطلقًا. يتحقق CLI من كونه URL ويرفض القيم النسبية. تُجلب ملفات الكتل دائمًا من baseUrl، ولا تُجلب مطلقًا من موقع نسبي إلى المكان الذي حُمّل منه registry.json.
  • تسمّي dependencies الكتل في السجل نفسه. يؤدي إضافة tabs إلى تثبيت tab-item أولًا. ويؤدي اكتشاف تبعيات مفقودة أو دائرية إلى إيقاف التثبيت مع ظهور خطأ.
  • name مطلوب لكنه لا يُعرض. تستخدم الأوامر والمخرجات المفتاح الذي يخصصه المستهلك للسجل في blocks.json، ولا يلزم أن يطابق الاسم.
  • type للمعلومات فقط. يقبل blockstudio أو create-block أو wordpress، ولا يغير سلوك CLI.

يتحقق CLI من الملف كاملًا عند كل جلب ويبلّغ عن كل حقل غير صالح، لذا يظهر الخطأ الإملائي قبل تنزيل أي ملف. ويوفر سطر $schema الفحوص نفسها في المحرر.

الخطوة 4: النشر عبر الروابط الخام

أودع المستودع وادفعه إلى GitHub. وبعد ذلك يصبح كل ملف في المستودع العام متاحًا على:

الكود
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>

يمكن أن يكون <ref> فرعًا أو وسمًا أو معرّف SHA لالتزام. وفي هذا السجل، هناك عنوانان مهمان:

  • عنوان URL الذي يضبطه المستهلكون: https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
  • baseUrl في registry.json: https://raw.githubusercontent.com/acme/acme-blocks/main/blocks

باستخدام baseUrl هذا، يُجلب index.php الخاص بـ hero من https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php. يعيد المضيف الخام محتوى الملف بدلًا من صفحة GitHub HTML، وهي ما يحتاج إليه CLI. ويظهر خطأ المالك أو المستودع أو المرجع عند الأمر الأول على هيئة 404:

الكود
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json

الخطوة 5: تثبيت الكتل في قالب

أنشئ blocks.json في جذر القالب المستهلك:

سطر الأوامر
npx blockstudio init --yes
الكود
Created .../acme-theme/blocks.json

ينشئ init --yes كائن registries فارغًا. أضف السجل ضمن مساحة الاسم التي تريد كتابتها في الأوامر:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
  }
}

شغّل init من دون --yes في الطرفية للإجابة عن الأسئلة نفسها تفاعليًا (مجلد الكتل وأسماء السجلات وعناوين URL) بدلًا من ذلك.

تحقق من حل السجل:

سطر الأوامر
npx blockstudio list
الكود
acme (4 blocks)

  Name      Title     Category      Type
  hero      Hero      layout        blockstudio
  card      Card      components    blockstudio
  tabs      Tabs      layout        blockstudio
  tab-item  Tab Item  layout        blockstudio

يطابق search جزءًا من النص، مع تجاهل حالة الأحرف، ضمن الأسماء والعناوين والأوصاف:

سطر الأوامر
npx blockstudio search tab
الكود
Results for "tab"

  acme/tabs - Tabs
    Tabbed content with keyboard navigation.
  acme/tab-item - Tab Item
    Single tab panel used inside Tabs.

عاين التثبيت باستخدام --dry-run. تظهر التبعية أولًا لأنها تُثبّت أولًا:

سطر الأوامر
npx blockstudio add acme/tabs --dry-run
الكود
Would install:
  tab-item (2 files)
  tabs (3 files)

ثم نفّذ التثبيت فعليًا:

سطر الأوامر
npx blockstudio add acme/tabs
الكود
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)

يوجد المجلدان الآن في مجلد blockstudio ضمن القالب، تمامًا كما هما في المستودع:

الكود
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss

يمكنك حذف مساحة الاسم عندما يحتوي سجل واحد مضبوط فقط على الكتلة، وتمرير عدة كتل دفعة واحدة:

سطر الأوامر
npx blockstudio add hero card
الكود
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)

Blockstudio يكتشف المجلدات الجديدة مثل أي كتلة أخرى في القالب.

تحديث الكتل المثبتة

الملفات المثبتة عبارة عن نسخة. لا يتم تتبّع الإصدار الذي ثبّته، ولا يحدّث CLI أي كتلة تلقائيًا. لجلب إصدار أحدث، أضف الكتلة مجددًا. من دون طرفية، أو في CI، يؤدي وجود مجلد حالي إلى إيقاف الأمر:

سطر الأوامر
npx blockstudio add tab-item
الكود
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.

في الطرفية، يسأل CLI قبل الاستبدال بدلًا من ذلك. يعرض --dry-run المجلدات التي سيستبدلها، ويستبدلها --yes:

سطر الأوامر
npx blockstudio add acme/tab-item --dry-run
الكود
Would overwrite tab-item
Would install:
  tab-item (2 files)

يستبدل الاستبدال الملفات المدرجة بإصدار السجل، لذا أرسل التغييرات المحلية إلى المستودع أولًا وراجع النتيجة باستخدام git diff.

لإلغاء التثبيت، أزل المجلد باسمه:

سطر الأوامر
npx blockstudio remove tabs --yes
الكود
Removed tabs

يأخذ remove اسم المجلد، لا namespace/block. ولا يزيل التبعيات، لذا يظل tab-item مثبتًا بعد إزالة tabs.

إدارة الإصدارات باستخدام مراجع git

لا يحتوي CLI على حقل إصدار أو خيار إصدار. ما يجلبه تحدده عناوين URL بالكامل، وفي GitHub يكون المرجع في URL هو الإصدار. يحصل المستهلك الذي يشير إلى main على ما يحتويه main وقت التثبيت.

لنشر إصدار ثابت، يجب أن ينزّل registry.json عند الوسم من الوسم نفسه أيضًا. قبل إنشاء الوسم، اضبط baseUrl عليه:

JSON
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"

ثم أرسل التغييرات، وأنشئ الوسم، وادفعه:

سطر الأوامر
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0

بعد ذلك، أعد baseUrl إلى main وأرسل التغيير، كي يستمر الفرع في تقديم الملفات الحالية. إذا تخطيت الخطوة الأولى، فسيحصل المستهلك المثبّت على الوسم على قائمة الكتل الموسومة، لكنه سينزّل الملفات من main.

يثبّت المستهلكون الإصدار باستخدام الوسم في URL الخاص بالسجل:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
  }
}

في هذا المثال، وُسِم v1.0.0 قبل وجود tabs وtab-item، لذا لا يعرض السجل المثبّت سوى الكتلتين الأصليتين:

سطر الأوامر
npx blockstudio list
الكود
acme (2 blocks)

  Name  Title  Category      Type
  hero  Hero   layout        blockstudio
  card  Card   components    blockstudio
سطر الأوامر
npx blockstudio add acme/tabs
الكود
Block "tabs" not found in registry "acme".

تعمل قيمة SHA للالتزام في URL الخاص بالسجل أيضًا، لكن لا يمكن للالتزام أن يتضمن قيمة SHA الخاصة به في baseUrl. لذا فإن التثبيت باستخدام SHA يثبّت قائمة الكتل، بينما تظل الملفات آتية من المرجع الذي يسميه baseUrl الخاص بذلك الالتزام؛ لذلك يُفضّل استخدام الوسوم للإصدارات.

أمور ينبغي مراعاتها

  • يُجلب كل سجل أولًا. يحمّل add جميع السجلات في blocks.json قبل حل أي شيء، لذا يؤدي تعذّر الوصول إلى سجل واحد إلى فشل الأمر حتى عند استخدام acme/hero. أزل السجلات التي لم تعد تستخدمها.
  • الأسماء الملتبسة تحتاج إلى مساحة أسماء. إذا احتوى سجلان على hero، فستسألك جلسة الطرفية أيهما تستخدم، ويختار --yes الأول حسب ترتيب blocks.json، بينما ينتهي التشغيل غير التفاعلي بالرمز Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero.
  • المستودعات الخاصة تحتاج إلى ترويسات. استخدم الصيغة الكائنية لإدخال السجل مع url وheaders. تدعم قيم الترويسات عناصر نائبة ${VAR} تُقرأ من البيئة، ويرسل CLI الترويسات مع جلب السجل وكل تنزيل للملفات. راجع استضافة GitHub لإعداد الرمز.

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