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

Δημιουργία διαδραστικών στοιχείων

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:

JavaScript
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.

JSON
{
  "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." }
    ]
  }
}
PHP
<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>
JavaScript
import { store, getContext } from '@wordpress/interactivity';

store('myTheme/accordion', {
  actions: {
    toggle: () => {
      const context = getContext();
      context.isOpen = !context.isOpen;
    },
  },
});

Πώς λειτουργεί:

  1. Το data-wp-context='{ "isOpen": false }' δημιουργεί μια τοπική λογική τιμή για αυτό το στιγμιότυπο.
  2. Όταν κάνετε κλικ στο κουμπί, καλείται το actions.toggle, το οποίο αντιστρέφει το context.isOpen.
  3. Το data-wp-bind--hidden="!context.isOpen" αποκρύπτει ή εμφανίζει το πλαίσιο.
  4. Τα data-wp-bind--aria-expanded και data-wp-text ενημερώνουν την κατάσταση του κουμπιού για λόγους προσβασιμότητας και την οπτική ένδειξη.

Επειδή κάθε στιγμιότυπο μπλοκ έχει το δικό του πλαίσιο, μπορείτε να τοποθετήσετε πολλά ακορντεόν σε μια σελίδα χωρίς πρόσθετες ρυθμίσεις. Ανοιγοκλείνουν ανεξάρτητα.

Καρτέλες

Οι καρτέλες εισάγουν δύο νέες έννοιες: το data-wp-class--* για την εναλλαγή κλάσεων CSS και το getElement() για την ανάγνωση χαρακτηριστικών δεδομένων από το στοιχείο που ενεργοποίησε μια ενέργεια.

Αυτό το παράδειγμα χρησιμοποιεί ένα πεδίο επαναλήπτη, ώστε οι συντάκτες να μπορούν να προσθέτουν όσες καρτέλες χρειάζονται.

JSON
{
  "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." }
        ]
      }
    ]
  }
}
PHP
<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>
JavaScript
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);
    },
  },
});
CSS
.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, καθώς και το κλείσιμο με κλικ στο φόντο. Δείχνει επίσης τα κατάλληλα χαρακτηριστικά προσβασιμότητας διαλόγου.

JSON
{
  "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." }
    ]
  }
}
PHP
<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>
JavaScript
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() και το κουμπί τον ενημερώνει με κάθε κλικ.

JSON
{
  "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
<?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>
JavaScript
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++;
      }
    },
  },
});
CSS
.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. Προσθέστε μια επανάκληση παρακολούθησης για να καταγράφετε τις αλλαγές του πλαισίου κατά την ανάπτυξη:

JavaScript
store('myBlock', {
  callbacks: {
    debug: () => {
      const context = getContext();
      console.log('context changed:', { ...context });
    },
  },
});
HTML
<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 και άλλων οδηγιών που δεν καλύπτονται σε αυτόν τον οδηγό.