Νησίδες
Οι νησίδες block επιτρέπουν σε ένα block να διατηρεί την κανονική του διαδικασία απόδοσης Blockstudio, ενώ μεταφέρουν την έξοδο που εξαρτάται από το αίτημα έξω από την αρχική απόκριση HTML.
Αυτό είναι χρήσιμο όταν μια σελίδα πρέπει να αποθηκεύεται επιθετικά στην προσωρινή μνήμη, αλλά ένα block εξακολουθεί να εξαρτάται από τον τρέχοντα επισκέπτη, τη συνεδρία, το καλάθι, τα δικαιώματα ή κάποιο άλλο ζωντανό πλαίσιο αιτήματος.
Τα blocks Blockstudio παραμένουν δυναμικά blocks WordPress. Οι νησίδες δεν τα μετατρέπουν σε προμεταγλωττισμένα στατικά HTML. Αντίθετα, το Blockstudio αλλάζει αυτό που αποδίδεται στο πρώτο αίτημα:
- οι ενυδατωμένες νησίδες αποδίδουν το κανονικό τους HTML που είναι ασφαλές για προσωρινή αποθήκευση και λαμβάνουν ένα συμβάν προσάρτησης
- οι δυναμικές νησίδες αποδίδουν πρώτα ένα placeholder ασφαλές για προσωρινή αποθήκευση και μετά ανακτούν το πραγματικό τμήμα από το πρόγραμμα περιήγησης του επισκέπτη
Λειτουργίες
Ενυδατωμένες νησίδες
Χρησιμοποιήστε μια ενυδατωμένη νησίδα όταν η έξοδος του διακομιστή είναι ασφαλής για προσωρινή αποθήκευση και το block χρειάζεται μόνο ένα σήμα προσάρτησης στο frontend.
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
Ολόκληρο το block HTML περιλαμβάνεται στην αρχική απόκριση. Ο χρόνος εκτέλεσης της νησίδας δεν υποβάλλει αίτημα REST για αυτό. Εκπέμπει το blockstudio:island:hydrate στον δείκτη, ώστε ο κώδικας του frontend να μπορεί να προσθέσει συμπεριφορά.
Δυναμικές νησίδες
Χρησιμοποιήστε μια δυναμική νησίδα όταν η πραγματική έξοδος του block πρέπει να αποδοθεί στο πλαίσιο αιτήματος του επισκέπτη.
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
Η αρχική απόκριση περιέχει μόνο ένα placeholder. Το πρόγραμμα περιήγησης ομαδοποιεί όλες τις έτοιμες δυναμικές νησίδες σε ένα αίτημα προς:
POST /wp-json/blockstudio/v1/island/render
Το endpoint αποδίδει μόνο εγγεγραμμένα blocks Blockstudio που είναι δυναμικά και έχουν το blockstudio.island.mode ορισμένο σε dynamic.
Διαμόρφωση
Η τιμή island μπορεί να είναι σύντομη μορφή ή αντικείμενο.
{
"blockstudio": {
"island": true
}
}
Τα true και "hydrate" σημαίνουν και τα δύο «ενυδατωμένο». Το "dynamic" σημαίνει «δυναμικό».
{
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "section",
"attributes": ["productId", "variant"],
"placeholder": "cart-placeholder.php",
"loading": "visible",
"event": "cart:updated",
"cache": {
"ttl": 60,
"per": "user"
}
}
}
}
| Ιδιότητα | Τύπος | Προεπιλογή | Περιγραφή |
|---|---|---|---|
mode |
"hydrate" ή "dynamic" |
"hydrate" |
Λειτουργία island. |
tag |
string |
"div" |
Ετικέτα περιτυλίγματος δείκτη. |
attributes |
string[] |
όλα τα χαρακτηριστικά του μπλοκ | Λίστα επιτρεπόμενων χαρακτηριστικών που αποστέλλεται σε αιτήματα δυναμικών αποσπασμάτων. |
placeholder |
string |
εντοπίζεται αυτόματα | Σχετική διαδρομή προτύπου placeholder. |
loading |
"eager" ή "visible" |
"eager" |
Πότε πρέπει το runtime να ανακτά ένα δυναμικό island. |
event |
string |
δεν έχει οριστεί | Όνομα συμβάντος παραθύρου που ανανεώνει ένα δυναμικό island. |
context |
boolean |
false |
Υπογραφή και επαναφορά του αναγνωριστικού δημοσίευσης και του τύπου δημοσίευσης της σελίδας που ζητήθηκε για δυναμικά αποσπάσματα. |
cache |
boolean ή object |
false |
Προαιρετική πολιτική cache αποσπάσματος. |
Πλαίσιο σελίδας
Τα δυναμικά αποσπάσματα αποδίδονται συνήθως ανεξάρτητα από το κέλυφος της σελίδας. Ενεργοποιήστε την ταυτότητα της σελίδας όταν το μπλοκ σας διαβάζει ρυθμίσεις ειδικές για τη σελίδα ή σχετικό περιεχόμενο:
{
"blockstudio": {
"island": {
"mode": "dynamic",
"context": true,
"cache": { "ttl": 60, "per": "global" }
}
}
}
Ο δείκτης περιλαμβάνει τα postId και postType της σελίδας που ζητήθηκε στο data-bs-island-context. Και οι δύο τιμές υπογράφονται με το όνομα του μπλοκ και τα επιτρεπόμενα χαρακτηριστικά, χρησιμοποιώντας το μυστικό του ιστότοπου που εξυπηρετεί το αίτημα. Δεν μπορούν να τροποποιηθούν ή να προστεθούν σε αίτημα χωρίς να ακυρωθεί η υπογραφή. Το runtime τα στέλνει μαζί με το υπάρχον ομαδοποιημένο αίτημα αποσπασμάτων, ακόμη και κατά τις ανανεώσεις που προκαλούνται από την εμφάνιση ή από συμβάντα. Αυτό λειτουργεί επίσης με τα bs_render_block(), bs_block() και τις ετικέτες μπλοκ.
Κατά την απόδοση αποσπασμάτων, τα $block['postId'], $block['postType'], get_the_ID() και get_queried_object_id() αναφέρονται σε εκείνη τη σελίδα. Το WordPress επαναφέρονται μετά, μαζί με τα καθολικά ερωτήματος και δημοσίευσης, ακόμη και μετά από εξαίρεση κατά την απόδοση. Πρόκειται για τη σελίδα που ζητήθηκε, όχι για ένα στοιχείο μέσα σε έναν βρόχο Query Loop. Δεν αναπαράγει αυθαίρετες παραμέτρους URL ούτε επαναφέρει το αρχικό αίτημα URL. Χρησιμοποιήστε το get_permalink($block['postId']) όταν χρειάζεστε το κανονικό URL της σελίδας HTML. Τα αρχεία και οι αποδόσεις χωρίς ζητούμενη δημοσίευση δεν στέλνουν ταυτότητα σελίδας.
Το endpoint ελέγχει ότι η σελίδα εξακολουθεί να υπάρχει, έχει τον υπογεγραμμένο τύπο δημοσίευσης και είναι αναγνώσιμη από τον τρέχοντα επισκέπτη, πριν ελέγξει την cache αποσπασμάτων. Μια έγκυρη υπογραφή δεν παρακάμπτει την προστασία ιδιωτικών δημοσιεύσεων ή με κωδικό πρόσβασης, την επιλεξιμότητα island, τις λίστες επιτρεπόμενων χαρακτηριστικών ή τους ελέγχους δικαιωμάτων του μπλοκ σας. Όταν υπάρχει, η ταυτότητα σελίδας αποτελεί πάντα μέρος του κλειδιού cache αποσπάσματος, επομένως το ίδιο μπλοκ με τα ίδια χαρακτηριστικά σε διαφορετικές σελίδες δεν μοιράζεται ποτέ απόσπασμα. Χρησιμοποιήστε το per: "user" ή μην χρησιμοποιήσετε cache αποσπασμάτων όταν η έξοδος εξαρτάται επίσης από τον επισκέπτη.
Αν παραλειφθεί το context ή οριστεί ως false, οι υπάρχοντες δείκτες και η συμπεριφορά χωρίς πλαίσιο παραμένουν αμετάβλητα. Μην τοποθετείτε εμπιστευτικά δεδομένα στον δημόσιο δείκτη.
Δυναμικά placeholders
Οι δυναμικές νησίδες πρέπει να αποδίδουν ένα placeholder ασφαλές για κοινόχρηστη προσωρινή αποθήκευση ολόκληρης σελίδας. Μην συμπεριλαμβάνετε δεδομένα συγκεκριμένου επισκέπτη στον κλάδο του placeholder.
Το Blockstudio αναζητά placeholders με την εξής σειρά:
- η ρητή διαδρομή
island.placeholder placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- το κανονικό πρότυπο με σημαίες placeholder
<div class="cart-count-placeholder">
Loading cart...
</div>
Αν δεν υπάρχει αρχείο placeholder, χρησιμοποιήστε τις σημαίες προτύπου στο κανονικό σας πρότυπο:
<?php if ( $isIslandPlaceholder ) : ?>
<div class="cart-count-placeholder">Loading cart...</div>
<?php else : ?>
<div class="cart-count">
<?php echo esc_html( acme_cart_count() ); ?>
</div>
<?php endif; ?>
Οι ίδιες τιμές είναι διαθέσιμες στα πρότυπα PHP, Twig και Blade:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
Το islandPhase είναι "normal", "hydrate", "placeholder" ή "fragment".
Συμπεριφορά χρόνου εκτέλεσης
Το Blockstudio εισάγει τον χρόνο εκτέλεσης νησίδων μόνο όταν η σελίδα που αποδίδεται περιέχει δείκτη νησίδας. Οι σελίδες χωρίς νησίδες δεν περιλαμβάνουν επιπλέον JavaScript νησίδας.
Για τις δυναμικές νησίδες, ο χρόνος εκτέλεσης:
- συλλέγει όλους τους έτοιμους δείκτες
- αφαιρεί τα διπλότυπα ζεύγη ίδιου ονόματος block, χαρακτηριστικών και υπογραφής
- στέλνει ένα ομαδοποιημένο αίτημα REST
- αντικαθιστά κάθε placeholder με το τμήμα που επιστρέφεται
- εκπέμπει το
blockstudio:island:rendered - εκπέμπει το
blockstudio:island:hydrate
Οι νησίδες loading: "eager" αποδίδονται μόλις ξεκινήσει ο χρόνος εκτέλεσης. Οι νησίδες loading: "visible" περιμένουν το IntersectionObserver. Αν πολλές ορατές νησίδες εισέλθουν ταυτόχρονα στο ορατό πεδίο, ομαδοποιούνται σε ένα αίτημα.
Το event ανανεώνει μια νησίδα όταν ενεργοποιείται το καθορισμένο συμβάν παραθύρου:
window.dispatchEvent(new Event('cart:updated'));
Σε περίπτωση αποτυχίας, το placeholder παραμένει στη θέση του και εκπέμπεται το
blockstudio:island:error.
Endpoint τμημάτων
Το endpoint νησίδων είναι δημόσιο, αλλά δεν αποτελεί γενικό API απόδοσης block.
Κάθε δείκτης περιλαμβάνει:
- το όνομα του block
- τα χαρακτηριστικά που περιλαμβάνονται στη λίστα επιτρεπόμενων
- μια υπογραφή που δημιουργείται από τον διακομιστή
Το endpoint αποδίδει μόνο όταν:
- το block είναι εγγεγραμμένο
- το block είναι δυναμικό block WordPress
- το block έχει επισημανθεί ως δυναμική νησίδα Blockstudio
- τα εισερχόμενα χαρακτηριστικά περνούν το σχήμα του block και τη λίστα επιτρεπόμενων για τις νησίδες
- η υπογραφή αντιστοιχεί στο κανονικοποιημένο όνομα του block και στα χαρακτηριστικά
Οι υπογραφές δημιουργούνται κατά την απόδοση στον ιστότοπο εξυπηρέτησης WordPress από τα salt του ιστότοπου και το φορτίο της νησίδας. Δεν εξάγονται ούτε ενσωματώνονται σε ένα θέμα.
Οι αποκρίσεις του endpoint επισημαίνονται ως μη αποθηκεύσιμες στην προσωρινή μνήμη. Αν θέλετε προσωρινή αποθήκευση τμημάτων, χρησιμοποιήστε το island.cache.
Προσωρινή αποθήκευση τμημάτων
Τα δυναμικά τμήματα δεν αποθηκεύονται στην προσωρινή μνήμη από προεπιλογή.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
Το true χρησιμοποιεί μια σύντομη καθολική προσωρινή μνήμη. Χρησιμοποιήστε τη μορφή αντικειμένου για ρητό έλεγχο:
{
"cache": {
"ttl": 120,
"per": "user"
}
}
per: "global" μοιράζεται ένα αποθηκευμένο τμήμα για το ίδιο block, τα ίδια attributes και το ίδιο προαιρετικό πλαίσιο σελίδας.
Το per: "user" διαφοροποιεί την cache με βάση το τρέχον ID χρήστη WordPress.
Προγραμματιστική απόδοση
Οι νησίδες λειτουργούν όπου αποδίδονται blocks Blockstudio:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
echo bs_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
Λειτουργούν επίσης μέσω ετικετών block:
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />
Η αρχική έξοδος παραμένει ο δείκτης και το placeholder της νησίδας, ενώ ο χρόνος εκτέλεσης εισάγεται όταν η απόκριση που αποδίδεται περιέχει αυτόν τον δείκτη.
PHP API
Blockstudio\Islands::is_island('acme/cart-count');
Blockstudio\Islands::mode('acme/cart-count');
Blockstudio\Islands::registered();
Blockstudio\Islands::marker('acme/cart-count', $attributes, $html);
Το marker() επικυρώνει τα μεταδεδομένα του block. Οι δυναμικοί δείκτες δημιουργούνται μόνο για εγγεγραμμένα δυναμικά blocks Blockstudio με το island.mode ορισμένο σε dynamic.
Άγκιστρα
Εντοπισμός και σήμανση:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
Endpoint και απόδοση:
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment
Το blockstudio/islands/max_per_request αλλάζει τον μέγιστο αριθμό δυναμικών νησίδων που γίνονται δεκτές σε ένα ομαδοποιημένο αίτημα endpoint. Η προεπιλογή είναι 50.
Ρύθμιση χρόνου εκτέλεσης:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
Υπογραφές:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
Ενέργειες κύκλου ζωής:
blockstudio/islands/registered
blockstudio/islands/rendered
Πότε να μην χρησιμοποιείτε νησίδες
Μην χρησιμοποιείτε δυναμική νησίδα για περιεχόμενο κρίσιμο για το SEO. Τα τμήματα δυναμικών νησίδων δεν υπάρχουν στο αρχικό HTML και δεν προορίζονται για ευρετηρίαση.
Χρησιμοποιήστε κανονική απόδοση ή ενυδατωμένη νησίδα όταν το περιεχόμενο είναι ασφαλές για προσωρινή αποθήκευση και πρέπει να είναι ορατό στους ανιχνευτές. Χρησιμοποιήστε δυναμική νησίδα μόνο για περιεχόμενο που μπορεί να φτάσει μετά το περίβλημα της σελίδας, όπως UI λογαριασμού, κατάσταση καλαθιού, εξατομικευμένες προτάσεις ή στοιχεία ελέγχου με περιορισμένη πρόσβαση.