Μετάβαση στο περιεχόμενο

Δημοσίευση μητρώου μπλοκ στο 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. Το μπλοκ hero έχει ένα πεδίο:

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 κατεβάζει ακριβώς αυτές τις διαδρομές και τίποτα άλλο. Δεν υπάρχει αντιστοίχιση με μοτίβα, επομένως ένα νέο στοιχείο προστίθεται μόνο όταν το προσθέσετε εδώ. Οι διαδρομές μπορούν να περιέχουν υποκαταλόγους, οι οποίοι δημιουργούνται κατά την εγκατάσταση.
  • Το baseUrl πρέπει να είναι απόλυτο URL. Το CLI το επικυρώνει ως URL και απορρίπτει τις σχετικές τιμές. Τα αρχεία των block ανακτώνται πάντα από το baseUrl και ποτέ από τοποθεσία σχετική με το σημείο από το οποίο φορτώθηκε το registry.json.
  • Τα dependencies δηλώνουν ονόματα block στο ίδιο μητρώο. Η προσθήκη του tabs εγκαθιστά πρώτα το tab-item. Οι ελλείπουσες και κυκλικές εξαρτήσεις διακόπτουν την εγκατάσταση με σφάλμα.
  • Το name είναι υποχρεωτικό, αλλά δεν εμφανίζεται. Οι εντολές και η έξοδος χρησιμοποιούν το κλειδί που δίνει ο καταναλωτής στο μητρώο στο blocks.json, το οποίο δεν χρειάζεται να ταιριάζει.
  • Το type είναι πληροφοριακό. Δέχεται blockstudio, create-block ή wordpress και δεν αλλάζει τη λειτουργία του CLI.

Το CLI επικυρώνει ολόκληρο το αρχείο σε κάθε ανάκτηση και αναφέρει κάθε πεδίο που αποτυγχάνει, ώστε ένα τυπογραφικό λάθος να εντοπίζεται πριν από τη λήψη οποιουδήποτε αρχείου. Η γραμμή $schema παρέχει τους ίδιους ελέγχους στο πρόγραμμα επεξεργασίας σας.

Βήμα 4: Δημοσίευση μέσω ακατέργαστων URL

Κάντε commit και push το αποθετήριο στο GitHub. Κάθε αρχείο σε ένα δημόσιο αποθετήριο είναι τότε διαθέσιμο στη διεύθυνση:

Κώδικας
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>

Το <ref> είναι κλάδος, ετικέτα ή SHA commit. Για αυτό το μητρώο υπάρχουν δύο σημαντικά URL:

  • Το 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: Εγκατάσταση block σε ένα θέμα

Στη ρίζα του θέματος που θα χρησιμοποιήσει τα block, δημιουργήστε το 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 σε ένα τερματικό για να απαντήσετε διαδραστικά στις ίδιες ερωτήσεις (κατάλογος block, ονόματα και 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

Μπορείτε να παραλείψετε τον χώρο ονομάτων όταν μόνο ένα ρυθμισμένο μητρώο περιέχει το block και να περάσετε πολλά block μαζί:

Κέλυφος
npx blockstudio add hero card
Κώδικας
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)

Το Blockstudio εντοπίζει τους νέους φακέλους όπως κάθε άλλο block στο θέμα.

Ενημέρωση εγκατεστημένων block

Τα εγκατεστημένα αρχεία είναι αντίγραφο. Δεν παρακολουθείται ποια έκδοση εγκαταστήσατε και το CLI δεν ενημερώνει ποτέ block από μόνο του. Για να λάβετε νεότερη έκδοση, προσθέστε ξανά το block. Χωρίς τερματικό ή σε 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)

Η αντικατάσταση αντικαθιστά τα αρχεία που αναφέρονται με την έκδοση του μητρώου, επομένως κάντε πρώτα commit τις τοπικές αλλαγές και ελέγξτε το αποτέλεσμα με το 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"

Στη συνέχεια, κάντε commit, προσθέστε ετικέτα και push:

Κέλυφος
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0

Έπειτα, ορίστε ξανά το baseUrl σε main και κάντε commit, ώστε ο κλάδος να συνεχίσει να παρέχει τα τρέχοντα αρχεία. Αν παραλείψετε το πρώτο βήμα, ένας καταναλωτής που έχει καρφιτσώσει την ετικέτα λαμβάνει τη λίστα block της ετικέτας, αλλά κατεβάζει τα αρχεία από το 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, επομένως το καρφιτσωμένο μητρώο προσφέρει μόνο τα δύο αρχικά block:

Κέλυφος
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 commit λειτουργεί επίσης στο URL του μητρώου, αλλά ένα commit δεν μπορεί να περιέχει το δικό του SHA στο baseUrl. Επομένως, η καρφίτσα με SHA σταθεροποιεί τη λίστα block, ενώ τα αρχεία εξακολουθούν να προέρχονται από την αναφορά που ονομάζει το baseUrl του commit. Γι’ αυτό προτιμήστε ετικέτες για τις εκδόσεις.

Σημεία που πρέπει να θυμάστε

  • Κάθε μητρώο ανακτάται πρώτο. Το 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. Οι τιμές κεφαλίδων υποστηρίζουν placeholders ${VAR} που διαβάζονται από το περιβάλλον, και το CLI στέλνει τις κεφαλίδες κατά την ανάκτηση του μητρώου και κάθε αρχείου. Δείτε το GitHub hosting για τη ρύθμιση του token.

Επόμενα βήματα