Δημοσίευση μητρώου μπλοκ στο 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 έχει ένα πεδίο:
{
"$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 κατεβάζει ακριβώς αυτές τις διαδρομές και τίποτα άλλο. Δεν υπάρχει αντιστοίχιση με μοτίβα, επομένως ένα νέο στοιχείο προστίθεται μόνο όταν το προσθέσετε εδώ. Οι διαδρομές μπορούν να περιέχουν υποκαταλόγους, οι οποίοι δημιουργούνται κατά την εγκατάσταση. - Το
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. Προσθέστε το μητρώο κάτω από τον χώρο ονομάτων που θέλετε να πληκτρολογείτε στις εντολές:
{
"$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 σε αυτήν:
"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 του μητρώου τους:
{
"$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.
Επόμενα βήματα
- Επισκόπηση μητρώου: τι είναι το μητρώο και πώς λειτουργεί το CLI
- registry.json: κάθε πεδίο του manifest
- blocks.json: ρυθμίσεις καταναλωτή, έλεγχος ταυτότητας και εντοπισμός ρυθμίσεων
- Προσθήκη: επίλυση χώρου ονομάτων, εξαρτήσεις και συμπεριφορά αντικατάστασης
- GitHub hosting: GitHub Pages και ιδιωτικά αποθετήρια
- Προσαρμοσμένος διακομιστής: παροχή μητρώου από τη δική σας υποδομή