Δημιουργία διαδραστικών στοιχείων
WordPress μπλοκ είναι στατικά από προεπιλογή. Ο επεξεργαστής αποθηκεύει HTML στη βάση δεδομένων, το frontend το εμφανίζει και εκεί τελειώνει η ιστορία. Για πολλά μπλοκ αυτό είναι ακριβώς το ζητούμενο. Ωστόσο, ορισμένα στοιχεία πρέπει να ανταποκρίνονται στις αλληλεπιδράσεις των χρηστών: εναλλαγή περιεχομένου, αλλαγή καρτελών, άνοιγμα παραθύρων διαλόγου, ενημέρωση μετρητών.
Το WordPress Interactivity API προσθέτει αντιδραστική συμπεριφορά στην πλευρά του πελάτη στα μπλοκ, χρησιμοποιώντας χαρακτηριστικά HTML που ονομάζονται οδηγίες. Γράφετε data-wp-on--click αντί για addEventListener, data-wp-bind--hidden αντί για element.hidden = true. Το API αναλαμβάνει αυτόματα την αντιδραστικότητα, την απομόνωση του πλαισίου και την ενυδάτωση.
Το Blockstudio αναλαμβάνει τη σύνδεση. Ορίστε το "interactivity": true στο block.json σας και το Blockstudio δημιουργεί το importmap, φορτώνει το API τόσο στον επεξεργαστή όσο και στο frontend και επιλύει τις εισαγωγές των ES module σας. Χωρίς διαδικασία δημιουργίας, χωρίς bundler, χωρίς ρυθμίσεις webpack. Δείτε την αναφορά Interactivity για λεπτομέρειες διαμόρφωσης.
Αυτός ο οδηγός παρουσιάζει τέσσερα ολοκληρωμένα στοιχεία, καθένα από τα οποία εισάγει νέες έννοιες. Στο τέλος, θα έχετε έτοιμα μοτίβα για τα πιο συνηθισμένα διαδραστικά στοιχεία UI.
Πώς λειτουργεί
Οδηγίες
Οι οδηγίες είναι χαρακτηριστικά data-wp-* που δηλώνουν αντιδραστική συμπεριφορά απευθείας στο HTML σας. Οι πιο συνηθισμένες είναι:
| Οδηγία | Σκοπός | Παράδειγμα |
|---|---|---|
data-wp-interactive |
Ορισμός χώρου ονομάτων αποθήκης | data-wp-interactive="myBlock" |
data-wp-context |
Τοπική αντιδραστική κατάσταση ανά στιγμιότυπο | data-wp-context='{ "isOpen": false }' |
data-wp-on--[event] |
Χειριστής συμβάντος | data-wp-on--click="actions.toggle" |
data-wp-bind--[attr] |
Σύνδεση χαρακτηριστικού HTML | data-wp-bind--hidden="!context.isOpen" |
data-wp-class--[name] |
Εναλλαγή κλάσης CSS | data-wp-class--is-active="context.isActive" |
data-wp-text |
Ορισμός περιεχομένου κειμένου | data-wp-text="state.count" |
data-wp-style--[prop] |
Ορισμός ενσωματωμένου στυλ | data-wp-style--opacity="context.opacity" |
data-wp-on-document--[event] |
Καθολικό συμβάν εγγράφου | data-wp-on-document--keydown="actions.onKeydown" |
data-wp-watch |
Εκτέλεση επανάκλησης όταν αλλάζει η κατάσταση | data-wp-watch="callbacks.log" |
data-wp-each |
Επανάληψη σε έναν πίνακα | data-wp-each="state.items" |
Η αποθήκη
Κάθε διαδραστικό μπλοκ έχει μια αποθήκη, που δημιουργείται καλώντας το store() με έναν χώρο ονομάτων και ένα αντικείμενο που περιέχει actions, callbacks και προαιρετικά state:
import { store, getContext } from '@wordpress/interactivity';
store('myBlock', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
Μέσα στις ενέργειες, το getContext() επιστρέφει το πλησιέστερο αντικείμενο data-wp-context προς τα πάνω στο δέντρο DOM. Το getElement() επιστρέφει αναφορά στο στοιχείο DOM που ενεργοποίησε την ενέργεια, χρήσιμη για την ανάγνωση χαρακτηριστικών data-*.
Πλαίσιο έναντι κατάστασης
Πλαίσιο (data-wp-context) είναι τοπικό σε κάθε στιγμιότυπο μπλοκ. Αν τοποθετήσετε τρία ακορντεόν σε μια σελίδα, καθένα έχει τη δική του τιμή isOpen. Η εναλλαγή του ενός δεν επηρεάζει τα άλλα.
Κατάσταση (wp_interactivity_state()) είναι καθολική και κοινή για όλα τα στιγμιότυπα ενός μπλοκ. Χρησιμοποιήστε τη για δεδομένα που προέρχονται από τον διακομιστή, όπως ο αριθμός σχολίων, ή για τιμές που πρέπει να είναι ίδιες παντού.
Το πλαίσιο λειτουργεί τόσο στον επεξεργαστή όσο και στο frontend. Η κατάσταση λειτουργεί μόνο στο frontend, επειδή το WordPress τη σειριοποιεί σε μια ετικέτα script που δεν περιλαμβάνεται στις απαντήσεις REST API του επεξεργαστή.
Ακορντεόν
Το απλούστερο διαδραστικό μοτίβο: κάντε κλικ σε ένα κουμπί για να εμφανίσετε ή να αποκρύψετε περιεχόμενο. Αυτό το παράδειγμα χρειάζεται μόνο τρεις οδηγίες και λίγες γραμμές JavaScript.
{
"name": "my-theme/accordion",
"title": "Accordion",
"category": "text",
"icon": "arrow-down-alt2",
"description": "Expandable content section.",
"blockstudio": {
"interactivity": true,
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "Accordion heading" },
{ "id": "body", "type": "textarea", "label": "Body", "default": "Accordion content goes here." }
]
}
}
<div useBlockProps
data-wp-interactive="myTheme/accordion"
data-wp-context='{ "isOpen": false }'>
<button
data-wp-on--click="actions.toggle"
data-wp-bind--aria-expanded="context.isOpen"
aria-controls="accordion-panel"
style="all: unset; cursor: pointer; display: flex; justify-content: space-between; align-items: center; width: 100%; padding: 1rem; font-weight: 600; font-size: 1.125rem;">
<?php echo esc_html( $a['heading'] ); ?>
<span aria-hidden="true" data-wp-text="context.isOpen ? '−' : '+'">+</span>
</button>
<div
id="accordion-panel"
role="region"
data-wp-bind--hidden="!context.isOpen"
style="padding: 0 1rem 1rem;">
<p><?php echo esc_html( $a['body'] ); ?></p>
</div>
</div>
import { store, getContext } from '@wordpress/interactivity';
store('myTheme/accordion', {
actions: {
toggle: () => {
const context = getContext();
context.isOpen = !context.isOpen;
},
},
});
Πώς λειτουργεί:
- Το
data-wp-context='{ "isOpen": false }'δημιουργεί μια τοπική λογική τιμή για αυτό το στιγμιότυπο. - Όταν κάνετε κλικ στο κουμπί, καλείται το
actions.toggle, το οποίο αντιστρέφει τοcontext.isOpen. - Το
data-wp-bind--hidden="!context.isOpen"αποκρύπτει ή εμφανίζει το πλαίσιο. - Τα
data-wp-bind--aria-expandedκαιdata-wp-textενημερώνουν την κατάσταση του κουμπιού για λόγους προσβασιμότητας και την οπτική ένδειξη.
Επειδή κάθε στιγμιότυπο μπλοκ έχει το δικό του πλαίσιο, μπορείτε να τοποθετήσετε πολλά ακορντεόν σε μια σελίδα χωρίς πρόσθετες ρυθμίσεις. Ανοιγοκλείνουν ανεξάρτητα.
Καρτέλες
Οι καρτέλες εισάγουν δύο νέες έννοιες: το data-wp-class--* για την εναλλαγή κλάσεων CSS και το getElement() για την ανάγνωση χαρακτηριστικών δεδομένων από το στοιχείο που ενεργοποίησε μια ενέργεια.
Αυτό το παράδειγμα χρησιμοποιεί ένα πεδίο επαναλήπτη, ώστε οι συντάκτες να μπορούν να προσθέτουν όσες καρτέλες χρειάζονται.
{
"name": "my-theme/tabs",
"title": "Tabs",
"category": "text",
"icon": "table-row-after",
"description": "Tabbed content switcher.",
"blockstudio": {
"interactivity": true,
"attributes": [
{
"id": "tabs",
"type": "repeater",
"label": "Tabs",
"min": 1,
"max": 8,
"attributes": [
{ "id": "label", "type": "text", "label": "Tab Label", "default": "Tab" },
{ "id": "content", "type": "textarea", "label": "Content", "default": "Tab content goes here." }
]
}
]
}
}
<div useBlockProps
data-wp-interactive="myTheme/tabs"
data-wp-context='{ "activeTab": 0 }'>
<div role="tablist" style="display: flex; gap: 0; border-bottom: 2px solid #e5e7eb;">
<?php foreach ( $a['tabs'] as $i => $tab ) : ?>
<button
role="tab"
data-index="<?php echo esc_attr( $i ); ?>"
data-wp-on--click="actions.selectTab"
data-wp-class--is-active-tab="callbacks.isActiveTab"
data-wp-bind--aria-selected="callbacks.isActiveTab"
style="padding: 0.75rem 1.5rem; background: none; border: none; cursor: pointer; font-weight: 500; border-bottom: 2px solid transparent; margin-bottom: -2px;">
<?php echo esc_html( $tab['label'] ); ?>
</button>
<?php endforeach; ?>
</div>
<?php foreach ( $a['tabs'] as $i => $tab ) : ?>
<div
role="tabpanel"
data-index="<?php echo esc_attr( $i ); ?>"
data-wp-bind--hidden="!callbacks.isActiveTab"
style="padding: 1.5rem 0;">
<p><?php echo esc_html( $tab['content'] ); ?></p>
</div>
<?php endforeach; ?>
</div>
import { store, getContext, getElement } from '@wordpress/interactivity';
store('myTheme/tabs', {
actions: {
selectTab: () => {
const context = getContext();
const { ref } = getElement();
context.activeTab = parseInt(ref.dataset.index, 10);
},
},
callbacks: {
isActiveTab: () => {
const context = getContext();
const { ref } = getElement();
return context.activeTab === parseInt(ref.dataset.index, 10);
},
},
});
.is-active-tab {
border-bottom-color: currentColor !important;
color: var(--wp--preset--color--primary, #111);
}
Τι νέο υπάρχει εδώ:
getElement()επιστρέφει{ ref }όπου τοrefείναι το στοιχείο DOM. Διαβάζουμε τοdata-indexγια να μάθουμε ποια καρτέλα πατήθηκε. Έτσι αποφεύγουμε να δημιουργούμε ξεχωριστή ενέργεια για κάθε καρτέλα.callbacksείναι παράγωγες τιμές που επανυπολογίζονται όταν αλλάζει το πλαίσιο. Τα κουμπιά καρτελών και τα πάνελ χρησιμοποιούν τοcallbacks.isActiveTabγια να ελέγξουν αν ο δείκτης τους αντιστοιχεί στοcontext.activeTab.- Το
data-wp-class--is-active-tabπροσθέτει ή αφαιρεί την κλάσηis-active-tabανάλογα με την τιμή που επιστρέφει η επανάκληση.
Παράθυρο διαλόγου
Το παράθυρο διαλόγου παρουσιάζει τον χειρισμό συμβάντων σε επίπεδο εγγράφου με το data-wp-on-document--keydown για κλείσιμο με Escape, καθώς και το κλείσιμο με κλικ στο φόντο. Δείχνει επίσης τα κατάλληλα χαρακτηριστικά προσβασιμότητας διαλόγου.
{
"name": "my-theme/modal",
"title": "Modal",
"category": "text",
"icon": "external",
"description": "Button that opens a modal dialog.",
"blockstudio": {
"interactivity": true,
"attributes": [
{ "id": "buttonText", "type": "text", "label": "Button Text", "default": "Open Modal" },
{ "id": "title", "type": "text", "label": "Modal Title", "default": "Modal Title" },
{ "id": "body", "type": "textarea", "label": "Modal Body", "default": "Modal content goes here." }
]
}
}
<div useBlockProps
data-wp-interactive="myTheme/modal"
data-wp-context='{ "isOpen": false }'>
<button
data-wp-on--click="actions.open"
style="padding: 0.75rem 1.5rem; background: #111; color: #fff; border: none; border-radius: 6px; cursor: pointer; font-size: 1rem;">
<?php echo esc_html( $a['buttonText'] ); ?>
</button>
<div
data-wp-bind--hidden="!context.isOpen"
data-wp-on--click="actions.backdropClick"
data-wp-on-document--keydown="actions.onKeydown"
style="position: fixed; inset: 0; z-index: 9999; display: flex; align-items: center; justify-content: center; background: rgba(0,0,0,0.5);">
<div
role="dialog"
aria-modal="true"
data-wp-bind--aria-label="context.isOpen ? '<?php echo esc_attr( $a['title'] ); ?>' : false"
data-wp-on--click="actions.stopPropagation"
style="background: #fff; border-radius: 12px; padding: 2rem; max-width: 32rem; width: 100%; margin: 1rem; position: relative;">
<h2 style="margin: 0 0 1rem; font-size: 1.25rem;"><?php echo esc_html( $a['title'] ); ?></h2>
<p style="margin: 0 0 1.5rem; color: #555;"><?php echo esc_html( $a['body'] ); ?></p>
<button
data-wp-on--click="actions.close"
style="padding: 0.5rem 1rem; background: #f3f4f6; border: none; border-radius: 6px; cursor: pointer;">
Close
</button>
</div>
</div>
</div>
import { store, getContext } from '@wordpress/interactivity';
store('myTheme/modal', {
actions: {
open: () => {
const context = getContext();
context.isOpen = true;
},
close: () => {
const context = getContext();
context.isOpen = false;
},
backdropClick: () => {
const context = getContext();
context.isOpen = false;
},
stopPropagation: (event) => {
event.stopPropagation();
},
onKeydown: (event) => {
if (event.key === 'Escape') {
const context = getContext();
context.isOpen = false;
}
},
},
});
Τι νέο υπάρχει εδώ:
- Το
data-wp-on-document--keydownακούει στοdocumentαντί στο ίδιο το στοιχείο. Ο χειριστής ενεργοποιείται ανεξάρτητα από το στοιχείο που έχει την εστίαση, οπότε το Escape λειτουργεί από παντού. - Κλείσιμο με κλικ στο φόντο χρησιμοποιεί δύο επίπεδα: το div επικάλυψης καλεί το
actions.backdropClick, ενώ το εσωτερικό παράθυρο διαλόγου καλεί τοactions.stopPropagationώστε να μην κλείνει όταν γίνεται κλικ μέσα του. - Τα
role="dialog"καιaria-modal="true"ενημερώνουν τα προγράμματα ανάγνωσης οθόνης ότι πρόκειται για τροπικό παράθυρο διαλόγου. Τοaria-labelσυνδέεται ώστε να εφαρμόζεται μόνο όταν το παράθυρο είναι ορατό. - Το χαρακτηριστικό
hiddenστην επικάλυψη αποκρύπτει το παράθυρο διαλόγου και εμποδίζει την ενεργοποίηση του ακροατή keydown του εγγράφου όταν αυτό είναι κλειστό, επειδή οι οδηγίες σε κρυφά στοιχεία τίθενται σε παύση.
Κουμπί «Μου αρέσει» με κατάσταση διακομιστή
Αυτό το παράδειγμα συνδυάζει κατάσταση στην πλευρά του διακομιστή με ενέργειες στην πλευρά του πελάτη. Ο αριθμός «Μου αρέσει» αρχικοποιείται από το PHP μέσω του wp_interactivity_state() και το κουμπί τον ενημερώνει με κάθε κλικ.
{
"name": "my-theme/like-button",
"title": "Like Button",
"category": "text",
"icon": "heart",
"description": "A like button with a count.",
"blockstudio": {
"interactivity": true,
"attributes": [
{ "id": "itemId", "type": "text", "label": "Item ID", "default": "post-1" }
]
}
}
<?php
$item_id = $a['itemId'];
$count = (int) get_option( "likes_{$item_id}", 0 );
wp_interactivity_state( 'myTheme/likeButton', array(
'count' => $count,
) );
?>
<div useBlockProps
data-wp-interactive="myTheme/likeButton"
data-wp-context='{ "liked": false }'>
<button
data-wp-on--click="actions.like"
data-wp-class--is-liked="context.liked"
style="display: inline-flex; align-items: center; gap: 0.5rem; padding: 0.5rem 1rem; border: 2px solid #e5e7eb; border-radius: 999px; background: none; cursor: pointer; font-size: 1rem; transition: all 0.2s;">
<span data-wp-text="context.liked ? '❤️' : '🤍'">🤍</span>
<span data-wp-text="state.count"><?php echo esc_html( $count ); ?></span>
</button>
</div>
import { store, getContext } from '@wordpress/interactivity';
const { state } = store('myTheme/likeButton', {
actions: {
like: () => {
const context = getContext();
if (context.liked) {
context.liked = false;
state.count--;
} else {
context.liked = true;
state.count++;
}
},
},
});
.is-liked {
border-color: #ef4444 !important;
background: #fef2f2 !important;
}
Τι νέο υπάρχει εδώ:
- Το
wp_interactivity_state()αρχικοποιεί τον αριθμό από το PHP. Η τιμή σειριοποιείται στο HTML της σελίδας και είναι διαθέσιμη ωςstate.countστις οδηγίες και στο JavaScript. stateέναντιcontext: ο αριθμός βρίσκεται στοstate(καθολικός, κοινός), ενώ τοlikedβρίσκεται στοcontext(ανά στιγμιότυπο). Αν υπήρχαν πολλά κουμπιά «Μου αρέσει» για το ίδιο στοιχείο, θα μοιράζονταν τον αριθμό, αλλά το καθένα θα μπορούσε να παρακολουθεί τη δική του κατάσταση επιλογής.- Αποδόμηση από το
store(): η κλήσηstore()επιστρέφει ένα αντιδραστικό αντικείμενοstateστο οποίο μπορείτε να αναφερθείτε στις ενέργειές σας.
Σημαντική επισήμανση: Η κατάσταση διακομιστή λειτουργεί μόνο στο frontend. Στον επεξεργαστή, το μπλοκ αποδίδεται μέσω του REST API, οπότε το wp_interactivity_state() δεν περιλαμβάνεται. Το εφεδρικό κείμενο που αποδίδεται από το PHP (<?php echo esc_html( $count ); ?>) εμφανίζεται ως αρχική τιμή στην προεπισκόπηση του επεξεργαστή. Για κατάσταση με αλληλεπίδραση στον επεξεργαστή, χρησιμοποιήστε το data-wp-context.
Συμβουλές και μοτίβα
Συμβάσεις χώρων ονομάτων. Χρησιμοποιήστε το όνομα του θέματος ή του πρόσθετου ως πρόθεμα: myTheme/accordion, myPlugin/tabs. Έτσι αποφεύγονται συγκρούσεις όταν πολλά μπλοκ στην ίδια σελίδα χρησιμοποιούν το Interactivity API.
Δεν απαιτείται διαδικασία δημιουργίας. Το Blockstudio φορτώνει το script.js ως εγγενές ES module και δημιουργεί αυτόματα το importmap για το @wordpress/interactivity. Γράφετε τυπικό JavaScript με δηλώσεις import και λειτουργεί αμέσως.
Μπλοκ μόνο με οδηγίες. Αν το μπλοκ χρησιμοποιεί μόνο το data-wp-context με data-wp-bind--hidden ή data-wp-text, δεν χρειάζεστε καθόλου script.js. Το Interactivity API τα διαχειρίζεται δηλωτικά. Το παράδειγμα ακορντεόν παραπάνω θα μπορούσε να λειτουργήσει χωρίς JavaScript με ένα τέχνασμα checkbox, αλλά η προσέγγιση με script είναι πιο καθαρή.
Εντοπισμός σφαλμάτων με data-wp-watch. Προσθέστε μια επανάκληση παρακολούθησης για να καταγράφετε τις αλλαγές του πλαισίου κατά την ανάπτυξη:
store('myBlock', {
callbacks: {
debug: () => {
const context = getContext();
console.log('context changed:', { ...context });
},
},
});
<div data-wp-watch="callbacks.debug" ...>
Αφαιρέστε την πριν από την κυκλοφορία.
Διατηρήστε το πλαίσιο λιτό. Βάλτε στο data-wp-context μόνο τιμές που αλλάζουν πραγματικά. Τα στατικά δεδομένα, όπως οι ετικέτες και το περιεχόμενο, πρέπει να παραμένουν στο PHP. Το πλαίσιο JSON σειριοποιείται σε κάθε στιγμιότυπο του μπλοκ, επομένως τα μεγάλα αντικείμενα αυξάνουν το μέγεθος της σελίδας.
Επόμενα βήματα
- Αναφορά Interactivity: επιλογές διαμόρφωσης, λεπτομέρειες υποστήριξης στον επεξεργαστή και η μορφή αντικειμένου της ρύθμισης
interactivity. - Στοιχεία: πώς το Blockstudio φορτώνει το
script.js, τοstyle.cssκαι άλλα στοιχεία μπλοκ. - Τεκμηρίωση Interactivity του WordPressAPI: η πλήρης αναφορά του API, συμπεριλαμβανομένων των
data-wp-each,data-wp-init,data-wp-runκαι άλλων οδηγιών που δεν καλύπτονται σε αυτόν τον οδηγό.