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

Στοιχεία

Σύνθεση

Τα ενσωματωμένα στοιχεία UI έχουν σχεδιαστεί για συνδυασμό και όχι για μεμονωμένη χρήση. Ένα select ανοίγει μέσα σε ένα παράθυρο διαλόγου, μια φόρμα επικυρώνεται μέσα σε ένα συρόμενο πλαίσιο, ένα μενού εμφανίζεται σε μια γραμμή πίνακα. Αυτή η σελίδα εξηγεί τους μηχανισμούς που κάνουν αυτές τις συνδέσεις να λειτουργούν: πώς δομούνται οι σύνθετες οικογένειες, πώς οι ενεργοποιητές προωθούν τις ιδιότητες κουμπιών, τι κάνει από κάτω το Interactivity API και πώς το μοντέλο επιπέδων διατηρεί τη συνοχή των στοιβαγμένων επιφανειών.

Σύνθετες οικογένειες

Ένα σύνθετο στοιχείο αποτελείται από ένα βασικό block και θυγατρικά block. Το βασικό block διαχειρίζεται την κατάσταση· κάθε θυγατρικό δηλώνει τη θέση του στην οικογένεια μέσω των parent και usesContext στο block.json του:

JSON
{
  "name": "bsui/select-option",
  "parent": ["bsui/select-popup"],
  "usesContext": ["bsui/select"]
}

Οι ρίζες διαθέτουν μια περιοχή InnerBlocks με λίστα allowedBlocks και αρχικό template, ώστε η εισαγωγή ενός παραθύρου διαλόγου στον επεξεργαστή να δημιουργεί τα στοιχεία ενεργοποίησης, το φόντο και το αναδυόμενο παράθυρό του. Έτσι, μια οικογένεια συμπεριφέρεται με τον ίδιο τρόπο είτε συντίθεται στον επεξεργαστή, σε σελίδα βασισμένη σε αρχείο είτε σε ετικέτες:

HTML
<bs:bsui-select name="role" placeholder="Pick a role">
  <bs:bsui-select-trigger />
  <bs:bsui-select-popup>
    <bs:bsui-select-option value="viewer" label="Viewer" />
    <bs:bsui-select-option value="editor" label="Editor" />
  </bs:bsui-select-popup>
</bs:bsui-select>

Τα αναδυόμενα παράθυρα και τα πλαίσια είναι πραγματικές περιοχές InnerBlocks και όχι υποδοχές με ειδική σύνταξη. Ένα bsui/dialog-popup δέχεται ένθετα block όπως ακριβώς ένα block ομάδας, οπότε η τοποθέτηση μιας φόρμας, ενός select ή άλλου παραθύρου διαλόγου μέσα του είναι μια συνηθισμένη πράξη σύνθεσης.

Επίπεδα δεδομένα ή σύνθετα θυγατρικά

Ορισμένες οικογένειες δέχονται το περιεχόμενό τους ως δεδομένα αντί για θυγατρικά στοιχεία. Το select δημιουργεί το δικό του στοιχείο ενεργοποίησης και listbox όταν του δώσετε έναν πίνακα options JSON, κάτι που ταιριάζει σε επιλογές που προέρχονται από το PHP:

PHP
bs_render_block([
  'name' => 'bsui/select',
  'data' => [
    'name' => 'role',
    'placeholder' => 'Pick a role',
    'options' => wp_json_encode([
      ['value' => 'viewer', 'label' => 'Viewer'],
      ['value' => 'editor', 'label' => 'Editor'],
    ]),
  ],
]);

Και οι δύο μορφές παράγουν το ίδιο συμβόλαιο σήμανσης και την ίδια συμπεριφορά κατά την εκτέλεση. Χρησιμοποιήστε θυγατρικά στοιχεία όταν η δομή έχει συνταχθεί εκ των προτέρων και options όταν υπολογίζεται.

Προώθηση στοιχείων ενεργοποίησης

Τα στοιχεία επικάλυψης ανοίγουν με ένα κουμπί και αυτό το κουμπί πρέπει να είναι το κουμπί του συστήματος. Αντί να υλοποιούν ξανά το καθένα το δικό του κουμπί, τα block ενεργοποίησης των bsui/dialog, bsui/alert-dialog, bsui/drawer, bsui/menu, bsui/popover, bsui/collapsible και bsui/tooltip ενσωματώνουν το bsui/button μέσω ενός πεδίου block:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "trigger",
        "type": "block",
        "block": "bsui/button",
        "idStructure": "trigger_{id}"
      }
    ]
  }
}

Το idStructure επεκτείνει τα πεδία του κουμπιού στο στοιχείο ενεργοποίησης με πρόθεμα trigger_. Όλες οι ιδιότητες του κουμπιού είναι διαθέσιμες: trigger_label, trigger_variant, trigger_size, trigger_icon, trigger_iconPosition, trigger_href, trigger_disabled.

HTML
<bs:bsui-dialog-trigger trigger_label="Invite teammate" trigger_variant="outline" />

Στο πρότυπο του στοιχείου ενεργοποίησης, το $a['trigger'] είναι το πλήρως αποδοσμένο κουμπί, οπότε το φύλλο στυλ του και οι μελλοντικές βελτιώσεις του μεταφέρονται μαζί του. Κατά την εκτέλεση, ένα κοινό βοηθητικό πρόγραμμα προωθεί τις συνδέσεις ARIA του περιτυλίγματος (aria-haspopup, aria-expanded, aria-controls, aria-describedby, aria-labelledby, id) στο εσωτερικό κουμπί και το διατηρεί συγχρονισμένο μέσω ενός MutationObserver, ώστε οι βοηθητικές τεχνολογίες να βλέπουν ένα ενιαίο, συνεκτικό στοιχείο ελέγχου.

Το Interactivity API στο παρασκήνιο

Κάθε διαδραστική οικογένεια είναι ένα WordPress Interactivity API με όνομα που προέρχεται από το βασικό block της: bsui/dialog, bsui/select, bsui/form, bsui/tabs και ούτω καθεξής. Αυτό έχει τρεις συνέπειες.

Η κατάσταση αρχικοποιείται από τον διακομιστή. Το πρότυπο του βασικού block εκτυπώνει την αρχική του κατάσταση ως data-wp-context, απευθείας από τα χαρακτηριστικά του block:

HTML
<div
  data-wp-interactive="bsui/select"
  data-wp-context='{"open":false,"value":"","placeholder":"Pick a role", ...}'
  data-bsui-select-root
>

Η πρώτη εμφάνιση είναι σωστή HTML, χωρίς αναλαμπή κατά την ενυδάτωση στην πλευρά του πελάτη· τα αναδυόμενα παράθυρα ξεκινούν hidden, ενώ η ίδια σήμανση λειτουργεί στον καμβά του επεξεργαστή, επειδή το context δεν εξαρτάται από μια διαδικασία κατάστασης μόνο στο frontend.

Η συμπεριφορά συνδέεται με οδηγίες, όχι με το JavaScript σας. Τα πρότυπα συνδέουν δηλωτικά τη σήμανση με τα store. Το στοιχείο ενεργοποίησης του select, χωρίς το PHP του, αποτελείται μόνο από οδηγίες:

HTML
<button
  data-wp-interactive="bsui/select"
  data-wp-on--click="actions.toggle"
  data-wp-on--keydown="actions.handleTriggerKeyDown"
  data-wp-bind--aria-expanded="state.ariaExpanded"
  data-wp-text="state.displayValue"
  data-bsui-select-trigger
  aria-haspopup="listbox"
>

Το data-wp-on δρομολογεί συμβάντα σε ενέργειες, το data-wp-bind διατηρεί τα χαρακτηριστικά συγχρονισμένα με την παράγωγη κατάσταση, το data-wp-text αποδίδει την κατάσταση ως κείμενο και το data-wp-on-document--click προσφέρει στις ρίζες κλείσιμο με κλικ εκτός στοιχείου. Η σύνθεση στοιχείων δεν απαιτεί ποτέ τη σύνταξη χειριστή συμβάντων· το store διατίθεται μαζί με το block ως ενσωματωμένη λειτουργική μονάδα.

Τα store σας μπορούν να συνδεθούν στα σημεία επέκτασης. Τα στοιχεία ελέγχου φορμών δέχονται εκφράσεις οδηγιών ως χαρακτηριστικά και η σύνταξη namespace του Interactivity API τα κατευθύνει σε οποιοδήποτε store. Το onChange κατευθύνει τη διαχείριση αλλαγών σε μία από τις ενέργειές σας, το checked συνδέει την κατάσταση του στοιχείου ελέγχου με τη δική σας κατάσταση και το bindText αποδίδει μια ετικέτα ως span data-wp-text συνδεδεμένο με οποιαδήποτε διαδρομή κατάστασης:

HTML
<bs:bsui-switch label="Notifications" checked="myPlugin::state.notifications" onChange="myPlugin::actions.toggleNotifications" />
<bs:bsui-checkbox label="0 selected" bindText="myPlugin::state.selectionSummary" />

Το bindText είναι διαθέσιμο στα στοιχεία bsui/label, bsui/checkbox, bsui/switch, bsui/toggle και bsui/radio-group. Στα στοιχεία checkbox, switch και radio περνά στο κοινό βασικό στοιχείο ετικέτας, ώστε το κείμενο που βασίζεται στην κατάσταση να διατηρεί ακριβώς την τυπογραφία των ετικετών του συστήματος. Τα select και τα άλλα πεδία εισόδου εκπέμπουν επίσης από τη ρίζα τους ένα συμβάν change που διαδίδεται προς τα πάνω και μεταφέρει τη νέα τιμή στο detail, για πιο συνοπτικές ενσωματώσεις.

Ελεγχόμενες τιμές

Αφήστε το value ή το checked χωρίς τιμή για ένα στοιχείο ελέγχου που διαχειρίζεται τη δική του τιμή. Χρησιμοποιήστε το defaultValue, το defaultChecked ή το defaultPressed του Toggle για την αρχική επιλογή του. Ένα αυτόνομο Toggle χειρίζεται την είσοδο από δείκτη και πληκτρολόγιο χωρίς store καταναλωτή.

Για να ελέγξετε ένα πεδίο από το δικό σας store, παρέχετε τόσο τη σύνδεσή του όσο και μια ενέργεια onChange που ενημερώνει τη δεσμευμένη τιμή. Το value είναι διαδρομή οδηγίας, όχι κυριολεκτική προεπιλεγμένη τιμή. Τα Input, Textarea, Password Input, Number Field, Slider, Radio Group, Color Picker, Rating και Time Picker υποστηρίζουν το value. Τα Checkbox, Switch και Toggle χρησιμοποιούν αντί γι' αυτό το checked.

Προσθέστε στα διαδρομές το namespace που τις περιέχει, για παράδειγμα my/settings::context.quantity ή my/settings::state.quantity. Τα σύνθετα στοιχεία ελέγχου έχουν το δικό τους namespace· μια διαδρομή χωρίς προσδιορισμό αναφέρεται σε εκείνο το στοιχείο ελέγχου και όχι αυτόματα στο γονικό σας store. Οι συνδέσεις σύνθετων τιμών υποστηρίζουν διαδρομές με τελείες προς το context ή το state, συμπεριλαμβανομένων αριθμητικών κλειδιών πίνακα, αλλά όχι εκφράσεις JavaScript ή κλήσεις συναρτήσεων.

Ακολουθεί ένα πλήρες παράδειγμα σύνδεσης Number Field σε προσαρμοσμένο μπλοκ με ενεργοποιημένη την υποστήριξη Interactivity API:

PHP
<div
  data-wp-interactive="my/settings"
  data-wp-context='<?php echo esc_attr(wp_json_encode(['quantity' => 2])); ?>'
>
  <bs:bsui-number-field
    nameAlt="quantity"
    defaultValue="2"
    value="my/settings::context.quantity"
    onChange="my/settings::actions.setQuantity"
  />
  <output data-wp-text="context.quantity"></output>
</div>
JavaScript
import { getContext, store } from '@wordpress/interactivity';

store('my/settings', {
  actions: {
    setQuantity(event) {
      // Compound controls publish their normalized value in a custom change event.
      if (event.detail?.value !== undefined) {
        getContext().quantity = event.detail.value;
      }
    },
  },
});

Ορίστε την αντίστοιχη προεπιλεγμένη τιμή για την αρχική τιμή που αποδίδεται στον διακομιστή. Μετά την ενυδάτωση, οι αλλαγές του γονικού στοιχείου ενημερώνουν κάθε συνδεδεμένη παρουσία, συμπεριλαμβανομένων των τιμών μηδέν, false και κενών τιμών. Οι κρυφές είσοδοι φόρμας των Checkbox και Switch ακολουθούν επίσης τη σύνδεσή τους checked. Οι τιμές του Time Picker χρησιμοποιούν το HH:MM σε 24ωρη μορφή ή μια κενή συμβολοσειρά. Για τους χειριστές των εγγενών Input, Textarea και Password Input, διαβάστε το event.target.value· τα στοιχεία ελέγχου σύνθετων τιμών δημοσιεύουν το event.detail.value. Τα όρια του Number Field είναι προαιρετικά: αν παραλειφθούν τα min και max, το πεδίο δεν έχει όρια, ενώ το ρητό μηδέν παραμένει έγκυρο όριο.

Τα Select, Date Input, Phone Input και OTP Input δημοσιεύουν αλλαγές μέσω του onChange, αλλά δεν εκθέτουν αυτήν τη σύνδεση value ελεγχόμενης τιμής. Χρησιμοποιήστε τις τεκμηριωμένες προεπιλεγμένες ιδιότητές τους για αρχικές τιμές.

Σύνθεση από δικά σας block

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

PHP
<div useBlockProps class="settings-panel">
  <bs:bsui-switch label="Public profile" name="public" />
  <bs:bsui-space size="4" />
  <bs:bsui-button label="Save" variant="default" />
</div>

Το ίδιο ισχύει και από το PHP με bs_block(), συμπεριλαμβανομένης της ένθεσης μέσω του κλειδιού content, όπως περιγράφεται στην ενότητα προγραμματισμένη απόδοση. Και στις δύο περιπτώσεις, το φύλλο στυλ και το store του στοιχείου φορτώνονται μαζί του και το block σας παραμένει ένα λεπτό επίπεδο διάταξης πάνω στα μέρη του συστήματος.

Για να τοποθετήσετε στοιχεία δίπλα δίπλα, το bsui/stack είναι η γενική γραμμή ή στήλη flex: direction, gap στην κλίμακα αποστάσεων, align, justify και μια εναλλαγή wrap. Από προεπιλογή, τα θυγατρικά διατηρούν το φυσικό τους μέγεθος· η εναλλαγή grow τα τεντώνει ώστε να μοιράζονται εξίσου το μήκος της στοίβας. Έτσι, ένα υποσέλιδο μπορεί να χωρίσει το πλάτος του στα δύο κουμπιά αντί να τα συγκεντρώσει στη μία άκρη.

Ομάδες πεδίων και κάρτες

Το bsui/field-group αποδίδει ένα fieldset. Η προεπιλεγμένη παραλλαγή ομαδοποιεί σχετικά πεδία χωρίς να προσθέτει επιφάνεια. Χρησιμοποιήστε το variant="card" για ένα εξωτερικό πλαίσιο σε απαλό τόνο και, στη συνέχεια, τοποθετήστε τα πεδία μέσα στο bsui/field-group-content για να εμφανιστεί η εσωτερική επιφάνεια περιεχομένου. Διατηρήστε τον τίτλο και την περιγραφή έξω από αυτό το μπλοκ περιεχομένου:

HTML
<bs:bsui-field-group variant="card">
  <bs:bsui-field-group-title text="Account settings" />
  <bs:bsui-field-group-description text="Manage your account preferences." />
  <bs:bsui-field-group-content>
    <bs:bsui-field>
      <bs:bsui-field-label text="Display name" />
      <bs:bsui-input nameAlt="display_name" placeholder="Enter display name" />
    </bs:bsui-field>
    <bs:bsui-field>
      <bs:bsui-field-label text="Email" />
      <bs:bsui-input nameAlt="email" type="email" placeholder="Enter email" />
    </bs:bsui-field>
  </bs:bsui-field-group-content>
</bs:bsui-field-group>

Το disabled="true" στην ομάδα χρησιμοποιεί την εγγενή συμπεριφορά του fieldset για την απενεργοποίηση των στοιχείων ελέγχου της φόρμας. Η μορφοποίηση της κάρτας δεν αλλάζει την προεπιλεγμένη παραλλαγή.

Διαχωριστικά γραμμής εργαλείων

Τοποθετήστε το bsui/toolbar-separator ανάμεσα στα στοιχεία της γραμμής εργαλείων. Ακολουθεί το orientation της γονικής γραμμής εργαλείων: η οριζόντια γραμμή εργαλείων έχει ένα κατακόρυφο διαχωριστικό πλήρους ύψους, ενώ η κατακόρυφη γραμμή εργαλείων έχει ένα οριζόντιο διαχωριστικό πλήρους πλάτους. Τα διαχωριστικά εκτείνονται έως τις εσωτερικές πλευρές του περιγράμματος της γραμμής εργαλείων χωρίς να αλλάζουν το ύψος των στοιχείων ελέγχου. Η οριζόντια γραμμή εργαλείων κάνει κύλιση όταν το περιεχόμενό της υπερβαίνει το διαθέσιμο πλάτος.

Το μοντέλο επιπέδων

Οι στοιβαγμένες επιφάνειες είναι το σημείο όπου συνήθως αποτυγχάνουν οι βιβλιοθήκες στοιχείων. Τα ενσωματωμένα στοιχεία ακολουθούν ένα μικρό σύνολο κανόνων, σχεδιασμένων για όσους κατασκευάζουν πραγματικά UI.

Τα modal μεταφέρονται στο body

Όταν ανοίγει ένα παράθυρο διαλόγου, ένα παράθυρο ειδοποίησης ή ένα συρόμενο πλαίσιο, το αναδυόμενο παράθυρο και το φόντο του μεταφέρονται στο document.body, ενώ ένα σχόλιο-σύμβολο κράτησης θέσης σημειώνει πού θα επιστρέψουν όταν κλείσουν. Η μεταφορά εκτός DOM απαλλάσσει το modal από το overflow, τον μετασχηματισμό ή το περιβάλλον στοίβαξης οποιουδήποτε προγόνου. Το άνοιγμα κλειδώνει επίσης την κύλιση της σελίδας: το κλείδωμα διατηρεί μετρητή αναφορών για όλα τα στοιχεία επικάλυψης και αντισταθμίζει το πλάτος της γραμμής κύλισης ώστε η σελίδα να μη μετατοπίζεται. Το φόντο βρίσκεται στο z-index: 50, το αναδυόμενο παράθυρο στο 51, η εστίαση μεταφέρεται στο αναδυόμενο παράθυρο, το Tab παραμένει παγιδευμένο μέσα του και κατά το κλείσιμο η εστίαση επιστρέφει στο στοιχείο ενεργοποίησης.

Τα modal στοιβάζονται. Το άνοιγμα ενός διαλόγου μέσα από έναν άλλο προσθέτει τον νέο διάλογο σε μια κοινόχρηστη στοίβα: μόνο ο εξωτερικός διάλογος εμφανίζει το φόντο σκίασης, ενώ οι διάλογοι πίσω από τον επάνω μικραίνουν και προβάλλουν πίσω του. Η στοίβα ορίζει μια προσαρμοσμένη ιδιότητα --bs-ui-nested-dialogs σε κάθε popup του φόντου, ώστε η μετατόπιση και η κλίμακα της προβολής να αυξάνονται με κάθε επίπεδο, ενώ το γονικό στοιχείο προσαρμόζει το ύψος του στο θυγατρικό, ώστε τα επίπεδα να προβάλλουν ομοιόμορφα. Κατά το κλείσιμο, όλα επανέρχονται με την αντίστροφη σειρά, ένα επίπεδο κάθε φορά.

Όταν κλείνει ένα modal, η εστίαση επιστρέφει στο στοιχείο που το ενεργοποίησε, και επιστρέφει στο σωστό στοιχείο. Ένα κοινόχρηστο βοηθητικό getAnchor εντοπίζει το κουμπί του συστήματος μέσα στο περίβλημα του στοιχείου ενεργοποίησης, ώστε η εστίαση να επιστρέψει στο ορατό στοιχείο ελέγχου και όχι σε ένα αόρατο περίβλημα.

Το επάνω modal δεν μετασχηματίζεται ποτέ

Αυτό το εφέ προβολής μετασχηματίζει μόνο τους διαλόγους του φόντου. Το επάνω modal παραμένει σκόπιμα χωρίς μετασχηματισμό, επειδή ένα μετασχηματισμένο στοιχείο γίνεται το μπλοκ περιέκτη για τους απογόνους position: fixed, κάτι που θα διέλυε κάθε αιωρούμενο popup που ανοίγει μέσα του.

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

  • Το μενού και το σύνθετο πλαίσιο υπολογίζουν τη θέση τους σε σχέση με το στοιχείο ενεργοποίησης, χρησιμοποιώντας τη στρατηγική fixed του Floating UI. Εμφανίζονται από κάτω και μετακινούνται ή αλλάζουν πλευρά όταν δεν υπάρχει αρκετός χώρος στο παράθυρο προβολής.
  • Το πεδίο επιλογής κάνει το ίδιο όταν δεν έχει επιλεγεί τίποτα. Αν υπάρχει ήδη επιλογή, ευθυγραμμίζει το popup έτσι ώστε η επιλεγμένη επιλογή να εμφανίζεται ακριβώς πάνω από το στοιχείο ενεργοποίησης, εντός των ορίων του παραθύρου προβολής, όπως συμβαίνει στα εγγενή πεδία επιλογής στο macOS.
  • Το μενού περιβάλλοντος ανοίγει στις συντεταγμένες clientX/clientY του δείκτη.

Καθώς το επάνω modal παραμένει χωρίς μετασχηματισμό, όλα αυτά αγκυρώνονται σωστά στα στοιχεία ενεργοποίησής τους μέσα σε διάλογο, διάλογο ειδοποίησης ή συρτάρι, ανεξάρτητα από το βάθος της εμφώλευσης. Τα popup δεν γνωρίζουν ότι βρίσκονται μέσα σε modal, ούτε χρειάζεται να το γνωρίζουν.

Το Escape κλείνει πρώτα το βαθύτερο επίπεδο

Ένα πάτημα του Escape κλείνει ακριβώς ένα επίπεδο, από μέσα προς τα έξω:

  1. Ένα ανοιχτό αιωρούμενο επίπεδο (μια λίστα επιλογών, ένα μενού, ένα popover, ένα popup ημερομηνίας ή τηλεφώνου) κλείνει πρώτο και η εστίαση επιστρέφει στο στοιχείο ενεργοποίησής του. Το πεδίο επιλογής διακόπτει τη διάδοση του συμβάντος, ενώ οι χειριστές του modal επίσης δεν ενεργοποιούνται όταν είναι ανοιχτό οποιοδήποτε αιωρούμενο επίπεδο, ώστε ο διάλογος από κάτω να μη λαμβάνει ποτέ αυτό το πάτημα.
  2. Στη συνέχεια κλείνει το επάνω modal.
  3. Όταν υπάρχουν στοιβαγμένα modal, κάθε επιπλέον πάτημα του Escape αφαιρεί ένα ακόμη από τη στοίβα.

Η συμπεριφορά κλεισίματος είναι πολιτική, όχι τυχαίο αποτέλεσμα. Ένας διάλογος που αποδίδεται με dismissable="false" αγνοεί τόσο το Escape όσο και τα κλικ στο φόντο σκίασης. Και το bsui/alert-dialog ανταποκρίνεται στο Escape όπως κάθε modal, αλλά αγνοεί σκόπιμα τα κλικ στο φόντο σκίασης: σκοπός αυτού του μοτίβου είναι η επιλογή να γίνεται συνειδητά και να μην κλείνει κάτι κατά λάθος. Τα κλικ στο φόντο σκίασης κλείνουν έναν κανονικό διάλογο, καθώς το dismissable έχει προεπιλεγμένη τιμή true.

Μια φόρμα σε διάλογο

Το μοτίβο που εφαρμόζει ταυτόχρονα όλους τους παραπάνω κανόνες: ένα στοιχείο ενεργοποίησης ανοίγει ένα modal, το modal περιέχει μια φόρμα με επικύρωση και η φόρμα περιέχει ένα αιωρούμενο πεδίο επιλογής.

HTML
<bs:bsui-dialog>
  <bs:bsui-dialog-trigger trigger_label="Invite teammate" trigger_variant="outline" />
  <bs:bsui-dialog-backdrop />
  <bs:bsui-dialog-popup>
    <bs:bsui-dialog-header>
      <bs:bsui-dialog-title content="Invite a teammate" />
      <bs:bsui-dialog-description content="They receive an email with a join link." />
    </bs:bsui-dialog-header>
    <bs:bsui-dialog-content>
      <bs:bsui-form block="team/invite" successMessage="Invitation sent.">
        <bs:bsui-field name="email">
          <bs:bsui-field-label text="Email" />
          <bs:bsui-input name="email" type="email" placeholder="colleague@example.com" required="true" />
          <bs:bsui-field-error />
        </bs:bsui-field>
        <bs:bsui-field name="role">
          <bs:bsui-field-label text="Role" />
          <bs:bsui-select name="role" defaultValue="editor" placeholder="Pick a role">
            <bs:bsui-select-trigger />
            <bs:bsui-select-popup>
              <bs:bsui-select-option value="viewer" label="Viewer" />
              <bs:bsui-select-option value="editor" label="Editor" />
              <bs:bsui-select-option value="admin" label="Admin" />
            </bs:bsui-select-popup>
          </bs:bsui-select>
        </bs:bsui-field>
        <bs:bsui-space size="2" />
        <bs:bsui-button label="Send invite" />
      </bs:bsui-form>
    </bs:bsui-dialog-content>
    <bs:bsui-dialog-footer>
      <bs:bsui-dialog-close label="Cancel" />
    </bs:bsui-dialog-footer>
  </bs:bsui-dialog-popup>
</bs:bsui-dialog>

Κάθε ετικέτα και χαρακτηριστικό παραπάνω είναι απαραίτητα: το στοιχείο ενεργοποίησης παραπέμπει στο κουμπί του συστήματος, ο τίτλος και η περιγραφή λαμβάνουν το content, τα πεδία έχουν τα ονόματα που σειριοποιεί η φόρμα και το required="true" μετατρέπεται σε πραγματική δυαδική τιμή από τον αναλυτή ετικετών.

Τι κάνει κάθε store κατά την εκτέλεση

bsui/dialog εισάγει το {"open":false,"dismissable":true} στο context από την πλευρά του διακομιστή. Το κλικ στο στοιχείο ενεργοποίησης εκτελεί το actions.open: το popup και το φόντο σκίασης μεταφέρονται μέσω portal στο body, η κύλιση κλειδώνει με αντιστάθμιση της γραμμής κύλισης, το popup εμφανίζεται με κίνηση σε 150ms, η εστίαση μεταφέρεται στο πρώτο στοιχείο που μπορεί να λάβει εστίαση και το Tab κινείται κυκλικά μέσα σε αυτό. Οι περιοχές κεφαλίδας, περιεχομένου και υποσέλιδου τοποθετούνται με βάση τα tokens κενού του modal.

bsui/select περιμένει μέσα στη φόρμα με τη λίστα επιλογών του hidden. Με κλικ στο στοιχείο ενεργοποίησης, το context.open αλλάζει κατάσταση και η λίστα τοποθετείται με σταθερές συντεταγμένες ως προς το παράθυρο προβολής. Επειδή το defaultValue="editor" είναι ήδη επιλεγμένο, το popup ευθυγραμμίζεται έτσι ώστε το Editor να εμφανίζεται ακριβώς πάνω από το στοιχείο ενεργοποίησης. Τα πλήκτρα βέλους, Home, End και η πληκτρολόγηση για γρήγορη αναζήτηση μετακινούν την ενεργή επιλογή· το Enter ή ένα κλικ επιλέγει· τα Tab και τα κλικ εκτός λίστας κλείνουν το popup χωρίς επιλογή. Το ορατό κείμενο του στοιχείου ενεργοποίησης ενημερώνεται μέσω του data-wp-text="state.displayValue", ενώ το κρυφό <input name="role"> παρακολουθεί την τιμή μέσω του data-wp-bind--value="state.selectedValue", την οποία αργότερα σειριοποιεί η φόρμα. Όλα αυτά αγκυρώνονται σωστά μέσα στον διάλογο, επειδή το επάνω modal παραμένει χωρίς μετασχηματισμό.

Το bsui/form παρεμβάλλεται κατά την υποβολή. Το bsui/button στο τέλος της φόρμας αποδίδει ένα απλό στοιχείο button χωρίς γνώρισμα type, οπότε είναι το στοιχείο υποβολής της φόρμας από προεπιλογή στο HTML· το κουμπί Ακύρωση βρίσκεται στο υποσέλιδο, έξω από το στοιχείο form, και δεν μπορεί να υποβάλει τίποτα. Κατά την υποβολή, το store σειριοποιεί τα FormData της φόρμας και τα στέλνει μέσω του data API του μπλοκ που ορίζεται στο block, δημιουργώντας εδώ μια εγγραφή στο σχήμα βάσης δεδομένων σχήμα βάσης δεδομένων του μπλοκ team/invite. Τα σφάλματα επικύρωσης επιστρέφονται ανά πεδίο: κάθε bsui/field λαμβάνει το name του, επισημαίνεται ως μη έγκυρο, αλλάζει το χρώμα του δακτυλίου εστίασης σε χρώμα καταστροφικής ενέργειας και εμφανίζει το μήνυμα στην ειδοποίηση bsui/field-error του. Σε περίπτωση επιτυχίας, το σώμα της φόρμας αποκρύπτεται και εμφανίζεται το successMessage, και τα δύο μέσω του data-wp-bind--hidden.

Τα επίπεδα κλείνουν με τη σειρά. Όταν η λίστα επιλογών είναι ανοιχτή, το Escape την κλείνει και επαναφέρει την εστίαση στο στοιχείο ενεργοποίησης του πεδίου επιλογής· το επόμενο Escape κλείνει τον διάλογο και επαναφέρει την εστίαση στο Invite teammate. Ένα κλικ στο φόντο σκίασης κλείνει τον διάλογο, επειδή το dismissable διατηρήθηκε στην προεπιλεγμένη τιμή του. Το κλείσιμο ξεκλειδώνει την κύλιση και επαναφέρει το popup στη θέση του στο έγγραφο.

Η ίδια σήμανση όταν επικολληθεί σε σελίδα βασισμένη σε αρχεία συγχρονίζεται ως εγγενή blocks, ενώ η ίδια σύνθεση όταν δημιουργηθεί στον επεξεργαστή εμφανίζεται διαδραστικά στον καμβά, επειδή κάθε παραπάνω συμπεριφορά υλοποιείται σε οδηγίες και stores που φορτώνονται και στα δύο περιβάλλοντα.

Τι διατηρεί λειτουργικές αυτές τις συνδέσεις

Οι παραπάνω συνδέσεις δεν είναι συμβάσεις, αλλά αναλλοίωτοι κανόνες που διατηρεί η βιβλιοθήκη σε κάθε απόδοση: κάθε ετικέτα αντιστοιχεί στην ίδια τυπογραφία, κάθε popup modal μοιράζεται την ίδια επιφάνεια και σκουραίνει τη σελίδα πίσω του, τα αιωρούμενα popup παραμένουν αγκυρωμένα στο στοιχείο ενεργοποίησης ενώ γίνεται κύλιση στη σελίδα και το Escape κλείνει ακριβώς ένα επίπεδο κάθε φορά, από μέσα προς τα έξω. Οι εγγυήσεις ισχύουν τόσο στο frontend όσο και στον καμβά του επεξεργαστή, με τα προεπιλεγμένα tokens ή με εκείνα του θέματός σας, ώστε μια σύνθεση που λειτουργεί σε ένα περιβάλλον να λειτουργεί με τον ίδιο τρόπο και στα υπόλοιπα.

Ζωντανά παραδείγματα

Οι συνθέσεις σε αυτήν τη σελίδα αποτελούν τη γραμματική· το /ui/examples είναι το εγχειρίδιο φράσεων. Συγκεντρώνει συνθέσεις που αποδίδονται ζωντανά σε τρία επίπεδα: ζεύγη που αναδεικνύουν τη σύνδεση ανάμεσα σε δύο ή τρία στοιχεία, αναγνωρίσιμα μοτίβα προϊόντων φτιαγμένα από λίγα στοιχεία και ολοκληρωμένες μικρές εφαρμογές συναρμολογημένες όπως διατίθενται τα στοιχεία μέσα σε πραγματικά προϊόντα. Η σελίδα κάθε στοιχείου στο /ui προσθέτει δικά της ολοκληρωμένα παραδείγματα, από ένα πεδίο με ετικέτα έως ένα ημερολόγιο πίσω από popover.

Διαδραστικότητα

Το μοντέλο οδηγίας και store πάνω στο οποίο βασίζονται τα στοιχεία UI, καθώς και ο τρόπος χρήσης του στα δικά σας blocks.