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

Απόδοση χαρακτηριστικών

Μέσα στα αρχεία προτύπων, μπορείτε να αποκτήσετε πρόσβαση σε όλα τα χαρακτηριστικά χρησιμοποιώντας τις μεταβλητές $attributes ή $a και το αντίστοιχο αναγνωριστικό του πεδίου.

PHP

PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>

Twig

Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>

Εγγραφή χαρακτηριστικών μέσω προγραμματισμού

Ο επεξεργαστής τοποθετεί τις αποθηκευμένες τιμές κάτω από το blockstudio.attributes. Οτιδήποτε εγγράφει ένα block εκτός του επεξεργαστή, όπως το REST API, το WP-CLI, μια μετεγκατάσταση περιεχομένου ή ένας διακομιστής MCP, ανιχνεύει το block από τα χαρακτηριστικά που καταχωρίζει το Blockstudio στο WP_Block_Type και τα εγγράφει στο ανώτερο επίπεδο. Και οι δύο μορφές αποδίδονται:

PHP
// Top level, as a programmatic writer produces it.
echo do_blocks( '<!-- wp:acme/hero {"visual_type":"media"} /-->' );

// Nested, as the editor saves it.
echo do_blocks( '<!-- wp:acme/hero {"blockstudio":{"attributes":{"visual_type":"media"}}} /-->' );

Αναγνωρίζονται μόνο τα αναγνωριστικά που δηλώνει το block στο ανώτερο επίπεδο, επομένως τα ίδια τα χαρακτηριστικά του WordPress, όπως τα anchor, className, lock, metadata και style, δεν υιοθετούνται ποτέ ως τιμές πεδίων. Αν το ίδιο αναγνωριστικό εμφανίζεται και στις δύο θέσεις, υπερισχύει η ένθετη τιμή.

Ανάγνωση χαρακτηριστικών μέσω προγραμματισμού

Ο κώδικας που εκτελείται εκτός του προτύπου, όπως τα δομημένα δεδομένα στο save_post, οι εξαγωγές, η ευρετηρίαση αναζήτησης ή ένα φίλτρο render_block, συχνά χρειάζεται τις τιμές ενός αποθηκευμένου μπλοκ όπως τις βλέπει το πρότυπο. Το bs_block_values() τις επιστρέφει χωρίς να αποδώσει το μπλοκ. Καλέστε το μετά την καταχώριση του μπλοκ (init ή αργότερα), με τον πλήρη πίνακα attrs από το parse_blocks():

PHP
foreach (parse_blocks($post->post_content) as $block) {
  if ($block['blockName'] === null) {
    continue;
  }

  $a = bs_block_values($block['blockName'], $block['attrs']);

  if ($a === null) {
    // Not a Blockstudio block, and no extension applies.
    continue;
  }

  echo esc_html($a['title'] ?? '');
}

Το αποτέλεσμα είναι ο πίνακας $a του προτύπου, με κλειδί το αναγνωριστικό κάθε πεδίου:

  • Εφαρμόζονται οι προεπιλεγμένες τιμές πεδίων, ενώ ένας επαναλήπτης με min περιλαμβάνει τις αρχικές γραμμές του.
  • Οι τιμές ανώτατου επιπέδου συγχωνεύονται με το blockstudio.attributes, και υπερισχύει η ένθετη τιμή. Διαβάζονται μόνο τα δηλωμένα αναγνωριστικά από το ανώτατο επίπεδο, ενώ το WordPress απορρίπτει μια τιμή ανώτατου επιπέδου που δεν ταιριάζει με τον καταχωρισμένο τύπο του πεδίου, για παράδειγμα μια συμβολοσειρά επιλογής, όπως ακριβώς και κατά την απόδοση.
  • Περιλαμβάνονται τα πεδία των αντίστοιχων επεκτάσεων, μαζί με τις προεπιλεγμένες τιμές τους. Μια επέκταση ενός βασικού μπλοκ ή μπλοκ τρίτου μέρους διαβάζει μόνο το blockstudio.attributes, όπως και κατά την απόδοση.
  • Εφαρμόζονται οι μορφές επιστροφής: έτσι, μια λίστα επιλογών με returnFormat ίσο με label επιστρέφει την ετικέτα, ενώ ένα πεδίο αρχείων επιστρέφει τα δεδομένα του συνημμένου.
  • Τα απενεργοποιημένα και κενά πεδία είναι false, όπως και στο πρότυπο.

Το null σημαίνει ότι ούτε το μπλοκ ούτε κάποια επέκταση διαχειρίζεται από το Blockstudio. Ένα μπλοκ Blockstudio χωρίς πεδία επιστρέφει [].

Η συνάρτηση εκτελεί τον ίδιο μετασχηματισμό με την απόδοση, επομένως έχει τις ίδιες παρενέργειες: τα πεδία αρχείων αναζητούν τα συνημμένα, ένα πεδίο μπλοκ που δεν επιστρέφει το data αποδίδει το μπλοκ στο οποίο αναφέρεται και το φίλτρο blockstudio/blocks/attributes/render εκτελείται για κάθε τιμή. Δεν αποδίδει το πρότυπο του ίδιου του μπλοκ και δεν επιλύει τα innerBlocks· πρέπει να τα διασχίσετε εσείς. Ένα πεδίο κώδικα διατηρεί ένα αυτόματα δημιουργημένο αναγνωριστικό %selector%, το οποίο διαφέρει σε κάθε κλήση.

Η επίλυση χρησιμοποιεί το τρέχον περιβάλλον WordPress. Δεν δημιουργούνται μεταδεδομένα που αφορούν μόνο την απόδοση, όπως οι μετρητές μπλοκ και το innerBlocks· τα φίλτρα απόδοσης χαρακτηριστικών λαμβάνουν το όνομα του μπλοκ και όχι τα μεταδεδομένα ενός πλήρως αποδοσμένου μπλοκ.

Δεν υπάρχει επιλογή για ανάγνωση των αποθηκευμένων τιμών χωρίς τον μετασχηματισμό. Για αυτές, διαβάστε απευθείας τον πίνακα attrs ή χρησιμοποιήστε το bs_validate_block() για να τις ελέγξετε.

Κενές τιμές

Οι τιμές χαρακτηριστικών επιστρέφουν false αν το πεδίο είναι κενό ή δεν έχει επιλεγεί κάποια επιλογή.

PHP

PHP
<?php if ($a['message']) : ?>
  <h1><?php echo $a['message']; ?></h1>
<?php endif; ?>

Twig

Twig
{% if a.message %}
  <h1>{{ a.message }}</h1>
{% endif %}

Σύνθετοι τύποι

Αρχεία

Από προεπιλογή (χωρίς returnFormat ή με "returnFormat": "object"), το πεδίο αρχείων επιστρέφει έναν πίνακα με τα δεδομένα του συνημμένου. Με το "multiple": true επιστρέφει μια λίστα τέτοιων πινάκων. Ένα αρχείο του οποίου το συνημμένο δεν υπάρχει πλέον παραλείπεται false.

Κλειδί Περιγραφή
ID Το αναγνωριστικό του συνημμένου.
title Ο τίτλος του συνημμένου.
alt Το εναλλακτικό κείμενο. Αν είναι κενό, χρησιμοποιείται ο τίτλος του συνημμένου.
caption Η λεζάντα.
description Η περιγραφή.
href Ο μόνιμος σύνδεσμος της σελίδας του συνημμένου.
url Το URL του αρχείου. Με το αναπτυσσόμενο μενού μεγέθους ("size": true), το URL του επιλεγμένου μεγέθους.
sizes Το URL και οι διαστάσεις κάθε καταχωρισμένου μεγέθους εικόνας· δείτε παρακάτω.

PHP

PHP
<?php if ($a['image']) :
  $image = $a['image'];
  $sizes = $image['sizes'] ?? [];
?>
  <img
    src="<?php echo esc_url($sizes['large'] ?? $image['url']); ?>"
    alt="<?php echo esc_attr($image['alt']); ?>"
    <?php if (isset($sizes['large-width'], $sizes['large-height'])) : ?>
      width="<?php echo esc_attr($sizes['large-width']); ?>"
      height="<?php echo esc_attr($sizes['large-height']); ?>"
    <?php endif; ?>
  />
<?php endif; ?>

Twig

Twig
{% if a.image %}
  <img
    src="{{ (a.image.sizes.large ?? a.image.url)|e('html_attr') }}"
    alt="{{ a.image.alt|e('html_attr') }}"
    {% if a.image.sizes['large-width'] is defined and a.image.sizes['large-height'] is defined %}
      width="{{ a.image.sizes['large-width']|e('html_attr') }}"
      height="{{ a.image.sizes['large-height']|e('html_attr') }}"
    {% endif %}
  />
{% endif %}

Το sizes έχει μία καταχώριση για κάθε καταχωρισμένο μέγεθος εικόνας, καθώς και το full: το URL κάτω από το όνομα του μεγέθους και τις διαστάσεις κάτω από τα <size>-width και <size>-height. Αν για ένα συνημμένο δεν έχει δημιουργηθεί μέγεθος WordPress, χρησιμοποιείται το αρχικό αρχείο μαζί με τις διαστάσεις του. Αν το WordPress δεν μπορεί να επιλύσει μια εικόνα ή προεπισκόπηση, το κλειδί sizes απουσιάζει. Για παράδειγμα, ένα PDF χωρίς δημιουργημένη προεπισκόπηση δεν έχει sizes, αλλά ένα PDF με μεταδεδομένα προεπισκόπησης μπορεί να έχει μεγέθη εικόνας. Το sizes είναι null όταν δεν έχουν καταχωριστεί μεγέθη εικόνας ή όταν το φίλτρο files/sizes απενεργοποιεί τα μεγέθη. Αυτό το φίλτρο μπορεί επίσης να μικρύνει τον χάρτη, επομένως ελέγξτε ότι υπάρχει ένα μέγεθος πριν διαβάσετε τις διαστάσεις του, όπως στα παραπάνω παραδείγματα.

Το αντικείμενο δεν έχει κλειδιά width, height, mime, type ή size. Διαβάστε τις διαστάσεις από το sizes ή χρησιμοποιήστε το ID με συναρτήσεις όπως wp_get_attachment_image() και get_post_mime_type().

Μορφές επιστροφής

Το returnFormat αλλάζει την τιμή που επιστρέφει το πεδίο:

returnFormat Τιμή
"object" (προεπιλογή) Ο πίνακας που περιγράφεται παραπάνω.
"id" Το αναγνωριστικό του συνημμένου όπως αποθηκεύτηκε ή λίστα αναγνωριστικών με το "multiple": true.
"url" Το URL ως συμβολοσειρά ή λίστα URL με το "multiple": true. Για τις εικόνες χρησιμοποιείται το μέγεθος που ορίζεται με το returnSize (προεπιλογή full), ενώ για τα άλλα αρχεία χρησιμοποιείται το URL του αρχείου.

Το πεδίο συνδέσμου επιστρέφει ένα αντικείμενο με το URL και τα χαρακτηριστικά:

PHP

PHP
<?php if ($a['link']) : ?>
  <a
    href="<?php echo $a['link']['url']; ?>"
    target="<?php echo $a['link']['target']; ?>"
  >
    <?php echo $a['link']['title']; ?>
  </a>
<?php endif; ?>

Twig

Twig
{% if a.link %}
  <a href="{{ a.link.url }}" target="{{ a.link.target }}">
    {{ a.link.title }}
  </a>
{% endif %}

Εικονίδιο

Το πεδίο εικονιδίου επιστρέφει ένα αντικείμενο με τα κλειδιά set, subSet και icon. Χρησιμοποιήστε τις βοηθητικές συναρτήσεις bs_render_icon() και bs_icon() για να εμφανίσετε το SVG:

PHP

PHP
<?php if ($a['icon']) : ?>
  <div class="icon">
    <?php bs_render_icon($a['icon']); ?>
  </div>
<?php endif; ?>

Twig

Twig
{% if a.icon %}
  <div class="icon">
    {{ bs_icon(a.icon) }}
  </div>
{% endif %}

Το bs_render_icon() εκτυπώνει απευθείας το SVG. Το bs_icon() το επιστρέφει ως συμβολοσειρά.

Χαρακτηριστικά

Ο τύπος πεδίου χαρακτηριστικών επιστρέφει έναν πίνακα ζευγών {attribute, value} για απόδοση ως χαρακτηριστικά HTML. Χρησιμοποιήστε το bs_render_data_attributes() για να τα εμφανίσετε:

PHP

PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
  Content
</div>

Twig

Twig
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
  Content
</div>

Το bs_render_data_attributes() εκτυπώνει απευθείας τα χαρακτηριστικά. Το bs_data_attributes() επιστρέφει τη συμβολοσειρά.

Ομάδα

Τα πεδία ομάδας προσθέτουν το όνομα της ομάδας ως πρόθεμα στα αναγνωριστικά των θυγατρικών χαρακτηριστικών. Χρησιμοποιήστε το bs_get_group() για να εξαγάγετε τα πεδία της ομάδας σε έναν καθαρό πίνακα:

PHP

PHP
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>

Twig

Twig
{% set group = fn('bs_get_group', a, 'settings') %}
<h1>{{ group.title }}</h1>
<p>{{ group.description }}</p>

Αυτό αφαιρεί το πρόθεμα της ομάδας από τα κλειδιά χαρακτηριστικών. Για παράδειγμα, το $a['settings_title'] γίνεται $group['title'].

Η βοηθητική συνάρτηση λειτουργεί επίσης όταν η ομάδα προέρχεται από επαναχρησιμοποιημένο προσαρμοσμένο πεδίο:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "attributes": [
        { "id": "kicker", "type": "text" },
        { "id": "title", "type": "text" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [
      { "type": "custom/section-header" }
    ]
  }
}
Twig
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>

Επαναλήπτης

Επαναλάβετε τα στοιχεία του επαναλήπτη:

PHP

PHP
<?php foreach ($a['items'] as $item) : ?>
  <div class="item">
    <h3><?php echo $item['title']; ?></h3>
    <p><?php echo $item['description']; ?></p>
  </div>
<?php endforeach; ?>

Twig

Twig
{% for item in a.items %}
  <div class="item">
    <h3>{{ item.title }}</h3>
    <p>{{ item.description }}</p>
  </div>
{% endfor %}

Βιβλίο συνταγών για μοτίβα πεδίων