نشر سجل كتل على 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 عادية. تحتوي كتلة القسم الرئيسي على حقل واحد:
{
"$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"
}
]
}
}
<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:
{
"$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 فارغًا. أضف السجل ضمن مساحة الاسم التي تريد كتابتها في الأوامر:
{
"$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 عليه:
"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 الخاص بالسجل:
{
"$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 لإعداد الرمز.
الخطوات التالية
- نظرة عامة على السجل: ماهية السجل وكيف يعمل CLI
- registry.json: جميع حقول البيان
- blocks.json: إعدادات المستهلك والمصادقة واكتشاف الإعدادات
- إضافة: حل مساحة الأسماء والتبعيات وسلوك الاستبدال
- استضافة GitHub: GitHub Pages والمستودعات الخاصة
- خادم مخصص: تقديم سجل من بنيتك التحتية الخاصة