registry.json
registry.json ملف JSON مستضاف على URL. يسرد كل الكتل المتاحة في السجل وبياناتها الوصفية واعتماداتها وبيانات ملفاتها.
المخطط
{
"$schema": "https://blockstudio.dev/schema/registry.json",
"name": "ui",
"description": "Core UI blocks for Blockstudio projects.",
"baseUrl": "https://raw.githubusercontent.com/acme/blocks/main/blocks",
"blocks": [
{
"name": "tabs",
"title": "Tabs",
"description": "Tabbed content with accessible keyboard navigation.",
"category": "layout",
"type": "blockstudio",
"dependencies": ["tab-item"],
"files": [
"block.json",
"index.php",
"style.scss"
]
}
]
}
الحقول العليا
name
مطلوب. معرّف السجل. يتحقق CLI من صحته لكنه لا يعرضه؛ إذ تستخدم الأوامر والمخرجات المفتاح الذي اختاره المستهلك للسجل في blocks.json.
description
اختياري. وصف موجز لمحتويات هذا السجل.
baseUrl
مطلوب. عنوان URL الأساسي لتنزيل ملفات الكتل. يجب أن يكون URL صالحًا.
تُجلب الملفات بضم عنوان URL الأساسي إلى اسم الكتلة ومسار الملف: {baseUrl}/{block.name}/{file}.
على سبيل المثال، إذا كانت قيمة baseUrl هي
https://raw.githubusercontent.com/acme/blocks/main/blocks، وكانت هناك كتلة اسمها tabs بملف index.php، فإن CLI يجلب:
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php
حقول الكتلة
name
مطلوب. اسم مجلد الكتلة. هذا هو المعرّف المستخدم في أوامر CLI، ويصبح اسم المجلد على القرص.
title
اختياري. اسم مقروء للبشر يظهر في list ومخرجات search.
description
اختياري. وصف من سطر واحد يظهر في نتائج search.
category
اختياري. تسمية للتجميع في مخرجات list.
type
اختياري. إحدى القيم blockstudio أو create-block أو wordpress.
هذا الحقل للمعلومات فقط. لا يغيّر CLI سلوكه بناءً على نوع الكتلة. بل ينزّل دائمًا الملفات المذكورة في files وينسخها.
dependencies
اختياري. مصفوفة بأسماء كتل أخرى في السجل نفسه، يجب تثبيتها مع هذه الكتلة.
عندما يضيف المستخدم كتلة لها اعتمادات، يحل CLI شجرة الاعتمادات كاملة ويثبّت جميع العناصر بالترتيب الصحيح. ويُكتشف الاعتماد الدائري ويُرفض.
يجب أن تكون الاعتمادات موجودة في السجل نفسه. الاعتمادات بين السجلات غير مدعومة.
files
مطلوب. مصفوفة بمسارات الملفات النسبية إلى مجلد الكتلة. يلزم ملف واحد على الأقل.
هذه هي الملفات المحددة التي ينزّلها CLI ويكتبها على القرص. ويمكن أن تتضمن المسارات مجلدات فرعية:
{
"files": [
"block.json",
"index.php",
"style.scss",
"src/components/tabs.tsx",
"src/styles/tabs.css"
]
}
تحديد مسارات الملفات
ينشئ CLI عنوان تنزيل URL لكل ملف في بيان ملفات الكتلة:
{baseUrl}/{block.name}/{file}
ويكتبه في:
{directory}/{block.name}/{file}
يُحافَظ على بنية المجلدات داخل مجلد الكتلة. وإذا احتوى مسار الملف على مجلدات فرعية، تُنشأ تلقائيًا.
تُجلب الملفات دائمًا من baseUrl داخل registry.json، وليس من موقع نسبي إلى URL السجل في blocks.json.
التحقق من الصحة
يتحقق CLI من صحة registry.json باستخدام مخطط Zod عند كل عملية جلب.
وتنتج عن السجلات غير الصالحة رسائل خطأ واضحة تحدد الحقول التي أخفقت في التحقق.
يُكتشف قبل تنزيل أي ملفات كل من الحقول المطلوبة المفقودة، والمصفوفات الفارغة blocks أو files، وعناوين URL غير الصالحة، وقيم type غير المعروفة.