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

registry.json

registry.json ملف JSON مستضاف على URL. يسرد كل الكتل المتاحة في السجل وبياناتها الوصفية واعتماداتها وبيانات ملفاتها.

المخطط

JSON
{
  "$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 ويكتبها على القرص. ويمكن أن تتضمن المسارات مجلدات فرعية:

JSON
{
  "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 غير المعروفة.