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

Προσαρμοσμένοι τύποι πεδίων

Οι προσαρμοσμένοι τύποι πεδίων επιτρέπουν σε ένα θέμα ή πρόσθετο να προσθέσει νέα στοιχεία ελέγχου πεδίων Blockstudio. Διαφέρουν από τα προσαρμοσμένα πεδία:

  • Το custom/{name} αναφέρεται σε μια επαναχρησιμοποιήσιμη ομάδα υπαρχόντων πεδίων.
  • Το namespace/type-name χρησιμοποιεί έναν καταχωρισμένο τύπο πεδίου με δικό του στοιχείο ελέγχου επεξεργαστή και μορφή τιμής.

Το Blockstudio παρέχει το σύστημα καταχώρισης. Το θέμα ή το πρόσθετό σας παρέχει το στοιχείο ελέγχου.

Πότε να τα χρησιμοποιήσετε

Χρησιμοποιήστε έναν προσαρμοσμένο τύπο πεδίου όταν ένα έργο χρειάζεται ένα εξειδικευμένο στοιχείο ελέγχου επεξεργασίας, το οποίο θα πρέπει να συμπεριφέρεται παντού όπως ένα εγγενές πεδίο Blockstudio:

  • χαρακτηριστικά μπλοκ
  • επαναχρησιμοποιήσιμες ομάδες πεδίων custom/{name}
  • ομάδες, καρτέλες και επαναλήπτες
  • πρότυπα PHP, Twig και Blade
  • μεταδεδομένα άρθρων και αποθήκευση επιλογών
  • πρότυπα επεκτάσεων, όπως το {attributes.margin.top}

Για παράδειγμα, ένα στοιχείο ελέγχου διαστημάτων μπορεί να αποθηκεύσει ένα αντικείμενο αντί για τέσσερα ξεχωριστά πεδία κειμένου:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "label": "Margin",
        "sides": ["top", "right", "bottom", "left"],
        "default": {
          "top": "sm",
          "right": "md",
          "bottom": "sm",
          "left": "md"
        }
      }
    ]
  }
}

Ονοματοδοσία

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

Text
namespace/type-name

Έγκυρα παραδείγματα:

  • acme/dimensions
  • acme/text-options
  • theme/spacing-token

Δεσμευμένοι χώροι ονομάτων:

  • Το custom/ προορίζεται για επαναχρησιμοποιήσιμες ομάδες προσαρμοσμένων πεδίων.
  • Το blockstudio/ προορίζεται για τον πυρήνα του Blockstudio.

Τα μη έγκυρα ονόματα αγνοούνται από το φίλτρο API και απορρίπτονται από τη βοηθητική συνάρτηση API.

Καταχώριση PHP

Καταχωρίστε τα μεταδεδομένα του τύπου πεδίου στο PHP:

PHP
add_action('init', function () {
    wp_register_script(
        'acme-field-dimensions',
        get_stylesheet_directory_uri() . '/fields/dimensions.js',
        ['blockstudio-blocks', 'wp-components', 'wp-element'],
        '1.0.0',
        true
    );

    bs_register_field_type('acme/dimensions', [
        'attribute'     => 'object',
        'default'       => [],
        'editor_script' => 'acme-field-dimensions',
        'storage'       => [
            'type'        => 'object',
            'rest_schema' => [
                'type'                 => 'object',
                'additionalProperties' => ['type' => 'string'],
            ],
        ],
    ]);
});

Το bs_register_field_type() επιστρέφει true όταν η καταχώριση είναι επιτυχής και false όταν το όνομα ή ο ορισμός δεν είναι έγκυρος. Μπορείτε να καταργήσετε μια χειροκίνητη καταχώριση με το bs_unregister_field_type().

Μπορείτε επίσης να χρησιμοποιήσετε το φίλτρο API:

PHP
add_filter('blockstudio/field_types', function (array $types): array {
    $types['acme/dimensions'] = [
        'attribute'     => 'object',
        'default'       => [],
        'editor_script' => 'acme-field-dimensions',
    ];

    return $types;
});

Κλειδιά ορισμού

Κλειδί Τύπος Περιγραφή
attribute string, array, null WordPress τύπος γνωρίσματος. Χρησιμοποιήστε string, number, boolean, object, array ή έναν πίνακα με αυτούς τους τύπους.
default mixed Προεπιλογή επιπέδου μητρώου όταν ένα πεδίο δεν ορίζει δική του προεπιλογή.
source string WordPress προέλευση γνωρίσματος για προσαρμοσμένες περιπτώσεις σειριοποίησης.
produces_attribute boolean Ορίστε το false για στοιχεία ελέγχου μόνο για προβολή. Η προεπιλογή είναι true.
editor_script string or array Καταχωρισμένο αναγνωριστικό script ή αναγνωριστικά προς φόρτωση στον επεξεργαστή block όταν χρησιμοποιείται ο τύπος.
editor_style string or array Καταχωρισμένο αναγνωριστικό στυλ ή αναγνωριστικά προς φόρτωση στον επεξεργαστή block όταν χρησιμοποιείται ο τύπος.
storage array Τύπος τιμής αποθήκευσης και υποδείξεις σχήματος REST για μεταδεδομένα αναρτήσεων και επιλογές.
supports array Προαιρετικές σημαίες δυνατοτήτων για το δικό σας στοιχείο ελέγχου.
translate boolean Ορίστε το true όταν η τιμή είναι κείμενο προς μετάφραση από το WPML. Απαιτείται το attribute string.

Ένας ορισμός με τιμή translate που δεν είναι boolean ή με το translate ορισμένο σε true και ένα attribute διαφορετικό από string είναι μη έγκυρος. Το bs_register_field_type() επιστρέφει false και το φίλτρο API τον αγνοεί.

WPML

Το wp bs wpml config δεν μπορεί να διαπιστώσει μόνο από την καταχώριση αν η τιμή ενός προσαρμοσμένου τύπου πεδίου είναι κείμενο, οπότε παραλείπει αυτά τα πεδία και εμφανίζει μια προειδοποίηση για το καθένα. Ορίστε το translate σε true στην καταχώριση ενός τύπου πεδίου που αποθηκεύει απλό κείμενο, και η εντολή δηλώνει τα πεδία του όπως τα πεδία text. Ένα πεδίο μπορεί και πάλι να εξαιρεθεί με το "translate": false. Δείτε WPMLΤεκμηρίωση.

PHP
bs_register_field_type('acme/headline', [
    'attribute' => 'string',
    'translate' => true,
]);

Καταχώριση JavaScript

Το σενάριο του επεξεργαστή καταχωρίζει το αντίστοιχο στοιχείο ελέγχου React:

JavaScript
const { createElement: el } = wp.element;
const { TextControl } = wp.components;

window.blockstudio.registerFieldType('acme/dimensions', {
  component(props) {
    const value =
      props.value &&
      typeof props.value === 'object' &&
      !Array.isArray(props.value)
        ? props.value
        : {};
    const sides = props.sides || ['top', 'right', 'bottom', 'left'];

    return el(
      'div',
      {},
      sides.map((side) =>
        el(TextControl, {
          key: side,
          label: side,
          value: value[side] || '',
          onChange(nextValue) {
            props.onChange({
              ...value,
              [side]: nextValue,
            });
          },
        }),
      ),
    );
  },
});

Το registerFieldType() επιστρέφει true όταν η καταχώριση γίνεται αποδεκτή. Καταργήστε μια καταχώριση από την πλευρά του προγράμματος-πελάτη με:

JavaScript
window.blockstudio.unregisterFieldType('acme/dimensions');

Το στοιχείο λαμβάνει τις ιδιότητες του ορισμού πεδίου, καθώς και τις εξής σταθερές ιδιότητες:

Ιδιότητα Περιγραφή
type Όνομα τύπου πεδίου.
id ID πεδίου.
field Πλήρης ορισμός πεδίου από το block.json.
value Τρέχουσα αποθηκευμένη τιμή.
defaultValue Προεπιλεγμένη τιμή πεδίου.
onChange Αποθηκεύει απευθείας μια νέα τιμή.
attributes Τρέχοντα χαρακτηριστικά μπλοκ.
block Ορισμός τρέχοντος τύπου μπλοκ.
clientId Τρέχον ID μπλοκ προγράμματος-πελάτη του επεξεργαστή.
inRepeater Αν το πεδίο βρίσκεται μέσα σε γραμμή επαναλήπτη.
repeaterId Τρέχουσα διαδρομή επαναλήπτη, αν υπάρχει.
disabled Αν το πεδίο είναι απενεργοποιημένο στον επεξεργαστή.

Οι τιμές των προσαρμοσμένων τύπων πεδίων αποθηκεύονται απευθείας. Δεν περνούν από την κανονικοποίηση εγγενών επιλογών select, radio, color ή gradient.

Απόδοση τιμών

Οι τιμές αντικειμένων είναι διαθέσιμες όπως κάθε άλλο χαρακτηριστικό Blockstudio.

PHP

PHP
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
  <?php echo esc_html($a['title'] ?? ''); ?>
</div>

Twig

Twig
<div class="mt-{{ a.margin.top }}">
  {{ a.title }}
</div>

Blade

Blade
<div class="mt-{{ $a['margin']['top'] ?? '' }}">
  {{ $a['title'] ?? '' }}
</div>

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

JSON
{
  "blockstudio": {
    "extend": "core/group",
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "set": [
          {
            "attribute": "class",
            "value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
          }
        ]
      }
    ]
  }
}

Αποθήκευση

Όταν ένας προσαρμοσμένος τύπος πεδίου χρησιμοποιείται με αποθήκευση postMeta ή option, το Blockstudio χρησιμοποιεί τον καταχωρισμένο τύπο τιμής αποθήκευσης και το σχήμα REST.

JSON
{
  "id": "margin",
  "type": "acme/dimensions",
  "label": "Margin",
  "storage": {
    "type": "postMeta",
    "postMetaKey": "acme_margin"
  }
}

Για τιμές array και object, ορίστε το storage.rest_schema στην καταχώριση του τύπου πεδίου. Οι απόγονοι επαναλήπτη εξακολουθούν να χρησιμοποιούν αποθήκευση με βάση πίνακες, επειδή ένας επαναλήπτης αποθηκεύει γραμμές.

Συμπεριφορά εφεδρείας

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

Αν ένας τύπος πεδίου δεν έχει καταχωριστεί στο PHP, το Blockstudio τον παραλείπει από τα παραγόμενα χαρακτηριστικά WordPress. Καταχωρίστε τον ορισμό PHP πριν εκτελεστεί η ανακάλυψη μπλοκ, συνήθως στο init πριν το Blockstudio δημιουργήσει μπλοκ.