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

Δημιουργία προσαρμοσμένου τύπου πεδίου

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

Ένας προσαρμοσμένος τύπος πεδίου μετατρέπει το ζεύγος σε ένα πεδίο. Καταχωρίζετε έναν τύπο όπως το acme/price μία φορά, στο PHP και στο JavaScript, και έπειτα τον χρησιμοποιείτε σε οποιοδήποτε block.json όπως ένα εγγενές πεδίο: σε ανώτατο επίπεδο, μέσα σε ομάδες και επαναλήπτες, με αποθήκευση στα μεταδεδομένα ανάρτησης ή στις επιλογές, καθώς και σε πρότυπα PHP, Twig και Blade. Το Blockstudio παράγει το γνώρισμα WordPress και το σχήμα REST αποθήκευσης από την καταχώριση.

Αυτό διαφέρει από ένα προσαρμοσμένο πεδίο. Μια αναφορά custom/{name} επαναχρησιμοποιεί μια ομάδα υπαρχόντων πεδίων. Ένας προσαρμοσμένος τύπος πεδίου προσθέτει ένα νέο στοιχείο ελέγχου με τη δική του μορφή τιμής.

Αυτός ο οδηγός δημιουργεί το acme/price από την αρχή έως το τέλος: την καταχώριση PHP, το στοιχείο ελέγχου επεξεργαστή, ένα block τιμολόγησης που το χρησιμοποιεί σε ανώτατο επίπεδο και μέσα σε έναν επαναλήπτη, αποθήκευση μεταδεδομένων ανάρτησης με αυστηρό σχήμα REST και το αποδιδόμενο αποτέλεσμα.

Καταχώριση του τύπου στο PHP

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

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

	bs_register_field_type( 'acme/price', array(
		'attribute'     => 'object',
		'default'       => array(),
		'editor_script' => 'acme-field-price',
		'storage'       => array(
			'type'        => 'object',
			'rest_schema' => array(
				'type'                 => 'object',
				'properties'           => array(
					'amount'   => array( 'type' => 'number', 'minimum' => 0 ),
					'currency' => array( 'type' => 'string', 'pattern' => '^[A-Z]{3}$' ),
				),
				'additionalProperties' => false,
			),
		),
	) );
} );

Το attribute είναι ο τύπος γνωρίσματος WordPress, εδώ object. Το storage.type είναι ο τύπος τιμής που χρησιμοποιείται όταν το πεδίο αποθηκεύεται στα μεταδεδομένα ανάρτησης ή στις επιλογές, και το storage.rest_schema είναι το σχήμα WordPress με το οποίο επικυρώνονται οι εγγραφές του REST. Χωρίς rest_schema, μια τιμή αντικειμένου αποκτά ένα επιεικές σχήμα που δέχεται οποιεσδήποτε ιδιότητες.

Καταχωρίστε στο init με την προεπιλεγμένη προτεραιότητα. Το Blockstudio εντοπίζει τα blocks αργά στο init και ένας τύπος που δεν έχει καταχωριστεί μέχρι τότε παραλείπεται από τα δημιουργημένα γνωρίσματα block.

Το bs_register_field_type() επιστρέφει true σε περίπτωση επιτυχίας και false όταν το όνομα ή ο ορισμός δεν είναι έγκυρος. Τα ονόματα πρέπει να είναι πεζά, να έχουν χώρο ονομάτων και να χωρίζονται με παύλες. Δύο χώροι ονομάτων είναι δεσμευμένοι:

Όνομα Αποτέλεσμα
acme/price true
Acme/Price false, όχι πεζά
custom/price false, δεσμευμένο για επαναχρησιμοποιήσιμες ομάδες πεδίων
blockstudio/price false, δεσμευμένο για τον πυρήνα του Blockstudio

Το bs_unregister_field_type() αφαιρεί μια καταχώριση, ενώ το φίλτρο blockstudio/field_types δέχεται τους ίδιους ορισμούς ως πίνακα με κλειδιά τα ονόματα.

Δημιουργία του στοιχείου ελέγχου επεξεργαστή

Το σενάριο που καταχωρίστηκε παραπάνω παρέχει το στοιχείο React. Χρησιμοποιεί τα στοιχεία WordPress που είναι ήδη φορτωμένα στον επεξεργαστή, επομένως δεν απαιτείται βήμα δημιουργίας:

JavaScript
const { createElement: el } = wp.element;
const { Flex, FlexBlock, FlexItem, SelectControl, TextControl } = wp.components;

window.blockstudio.registerFieldType('acme/price', {
  component(props) {
    const value =
      props.value && typeof props.value === 'object' && !Array.isArray(props.value)
        ? props.value
        : {};
    const currencies = props.currencies || ['EUR'];

    return el(
      Flex,
      { align: 'flex-end' },
      el(
        FlexBlock,
        {},
        el(TextControl, {
          label: props.label,
          type: 'number',
          min: 0,
          step: 0.01,
          disabled: props.disabled,
          value: value.amount ?? '',
          onChange(next) {
            props.onChange({ ...value, amount: next === '' ? 0 : Number(next) });
          },
        }),
      ),
      el(
        FlexItem,
        {},
        el(SelectControl, {
          label: 'Currency',
          hideLabelFromVision: true,
          disabled: props.disabled,
          value: value.currency || currencies[0],
          options: currencies.map((code) => ({ label: code, value: code })),
          onChange(next) {
            props.onChange({ ...value, currency: next });
          },
        }),
      ),
    );
  },
});

Το στοιχείο λαμβάνει κάθε ιδιότητα του ορισμού πεδίου, οπότε το κλειδί currencies που βάλατε στο block.json φτάνει ως props.currencies. Λαμβάνει επίσης σταθερές ιδιότητες: value, onChange, field, defaultValue, attributes, block, clientId, disabled και inRepeater με repeaterId όταν αποδίδεται μέσα σε γραμμή επαναλήπτη. Το onChange αποθηκεύει την τιμή ακριβώς όπως δόθηκε. Οι προσαρμοσμένες τιμές παρακάμπτουν την κανονικοποίηση επιλογών που εφαρμόζουν τα εγγενή πεδία select, radio, color και gradient.

Προστατευτείτε από τιμές που δεν είναι αντικείμενα, όπως κάνουν οι πρώτες γραμμές. Ένα block που αποθηκεύτηκε πριν υπάρξει το πεδίο ή με διαφορετική μορφή θα πρέπει να εξακολουθεί να ανοίγει στον επεξεργαστή.

Το Blockstudio τοποθετεί στην ουρά το acme-field-price στον επεξεργαστή block μόνο όταν έχει καταχωριστεί block που χρησιμοποιεί το acme/price. Αν το σενάριο αποτύχει να καταχωρίσει το στοιχείο ελέγχου, ο επεξεργαστής διατηρεί την αποθηκευμένη τιμή και εμφανίζει μια μη επεξεργάσιμη ειδοποίηση στη θέση του πεδίου, ενώ το frontend εξακολουθεί να αποδίδει την τιμή.

Χρήση σε block

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

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/pricing",
  "title": "Pricing",
  "blockstudio": {
    "attributes": [
      {
        "id": "price",
        "type": "acme/price",
        "label": "Starting price",
        "currencies": ["EUR", "USD"],
        "default": { "amount": 19, "currency": "EUR" },
        "storage": {
          "type": "postMeta",
          "postMetaKey": "acme_price"
        }
      },
      {
        "id": "tiers",
        "type": "repeater",
        "label": "Tiers",
        "min": 0,
        "max": 4,
        "attributes": [
          { "id": "name", "type": "text", "label": "Name", "default": "" },
          {
            "id": "price",
            "type": "acme/price",
            "label": "Price",
            "currencies": ["EUR", "USD"],
            "default": { "amount": 0, "currency": "EUR" },
            "storage": {
              "type": "postMeta",
              "postMetaKey": "acme_tier_prices"
            }
          }
        ]
      }
    ]
  }
}

Μια τιμή default σε επίπεδο πεδίου υπερισχύει της προεπιλογής μητρώου. Το Blockstudio μετατρέπει και τα δύο πεδία σε γνωρίσματα WordPress από την καταχώριση. Ο καταχωρισμένος τύπος block έχει:

JSON
{
  "price": {
    "blockstudio": true,
    "type": "object",
    "field": "acme/price",
    "id": "price",
    "default": { "amount": 19, "currency": "EUR" },
    "storage": { "type": "postMeta", "postMetaKey": "acme_price" }
  },
  "tiers": {
    "blockstudio": true,
    "type": "array",
    "field": "repeater",
    "id": "tiers",
    "attributes": [
      { "blockstudio": true, "type": "string", "field": "text", "default": "", "id": "name" },
      {
        "blockstudio": true,
        "type": "object",
        "field": "acme/price",
        "id": "price",
        "default": { "amount": 0, "currency": "EUR" },
        "storage": { "type": "postMeta", "postMetaKey": "acme_tier_prices" }
      }
    ]
  }
}

Απόδοση της τιμής

Στο πρότυπο, η τιμή είναι ένας συνηθισμένος πίνακας. Περιορίστε τον τύπο της πριν τον χρησιμοποιήσετε, επειδή μια αποθηκευμένη τιμή είναι τόσο αξιόπιστη όσο το τελευταίο στοιχείο που την έγραψε:

PHP
<?php
/** @var array{price: mixed, tiers: array<int, array{name: string, price: mixed}>} $a */
$format = static function ( mixed $price ): string {
	if ( ! is_array( $price ) ) {
		return '';
	}
	$amount   = is_numeric( $price['amount'] ?? null ) ? (float) $price['amount'] : 0.0;
	$currency = is_string( $price['currency'] ?? null ) ? $price['currency'] : '';

	return number_format_i18n( $amount, 2 ) . ' ' . $currency;
};
?>
<section useBlockProps class="acme-pricing">
  <p>From <?php echo esc_html( $format( $a['price'] ) ); ?></p>
  <?php foreach ( $a['tiers'] ?: array() as $tier ) : ?>
    <div class="acme-tier">
      <h3><?php echo esc_html( $tier['name'] ); ?></h3>
      <p><?php echo esc_html( $format( $tier['price'] ?? null ) ); ?></p>
    </div>
  <?php endforeach; ?>
</section>

Το ?: array() είναι σημαντικό. Ένας επαναλήπτης χωρίς γραμμές φτάνει στο πρότυπο ως false, όχι ως κενός πίνακας, και μια σκέτη foreach πάνω του προκαλεί προειδοποίηση PHP. Η γραμμή @var εξηγείται παρακάτω στην ενότητα στατικής ανάλυσης.

Απόδοση του block με μια αρχική τιμή και δύο βαθμίδες:

PHP
echo bs_block( array(
	'name' => 'acme/pricing',
	'data' => array(
		'price' => array( 'amount' => 19, 'currency' => 'EUR' ),
		'tiers' => array(
			array( 'name' => 'Starter', 'price' => array( 'amount' => 19, 'currency' => 'EUR' ) ),
			array( 'name' => 'Team', 'price' => array( 'amount' => 49, 'currency' => 'EUR' ) ),
		),
	),
) );
HTML
<!--blockstudio/acme/pricing--><section class="acme-pricing wp-block-acme-pricing">
  <p>From 19.00 EUR</p>
      <div class="acme-tier">
      <h3>Starter</h3>
      <p>19.00 EUR</p>
    </div>
      <div class="acme-tier">
      <h3>Team</h3>
      <p>49.00 EUR</p>
    </div>
  </section>

Χωρίς καθόλου δεδομένα, εφαρμόζεται η προεπιλεγμένη τιμή πεδίου και το block αποδίδεται ως From 19.00 EUR χωρίς βαθμίδες. Τα Twig και Blade διαβάζουν την ίδια τιμή με τα a.price.amount και $a['price']['amount'], ενώ τα πρότυπα επέκτασης μπορούν να την προσπελάσουν ως {attributes.price.amount}.

Αποθήκευση και σχήμα REST

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

JSON
{
  "type": "object",
  "single": true,
  "show_in_rest": {
    "schema": {
      "type": "object",
      "properties": {
        "amount": { "type": "number", "minimum": 0 },
        "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
      },
      "additionalProperties": false
    }
  }
}

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

JSON
{
  "type": "array",
  "single": true,
  "show_in_rest": {
    "schema": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "amount": { "type": "number", "minimum": 0 },
          "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
        },
        "additionalProperties": false
      }
    }
  }
}

Η αποθήκευση μιας ανάρτησης που περιέχει το block συγχρονίζει και τα δύο κλειδιά. Με τις δύο βαθμίδες από παραπάνω, το get_post_meta( $id, 'acme_price', true ) επιστρέφει {"amount":19,"currency":"EUR"} και το acme_tier_prices επιστρέφει τη λίστα τιμών των γραμμών:

JSON
[
  { "amount": 19, "currency": "EUR" },
  { "amount": 49, "currency": "EUR" }
]

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

JSON
{
  "code": "rest_invalid_pattern",
  "message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
  "data": { "status": 400 }
}

Τα μεταδεδομένα είναι αντίγραφο. Τα γνωρίσματα block στο περιεχόμενο της ανάρτησης παραμένουν η πηγή και κάθε αποθήκευση τα συγχρονίζει ξανά με τα διαμορφωμένα κλειδιά, οπότε μια τιμή που γράφτηκε απευθείας στα μεταδεδομένα αντικαθίσταται την επόμενη φορά που αποθηκεύεται η ανάρτηση. Η αποθήκευση επιλογών λειτουργεί με τον ίδιο τρόπο μέσω του register_setting(). Οι προσαρμοσμένοι τύποι πεδίων, συμπεριλαμβανομένης της αποθήκευσης βάσει πίνακα μέσα σε επαναλήπτες, είναι διαθέσιμοι από την έκδοση Blockstudio 7.5.0.

Στατική ανάλυση

Η επέκταση PHPStan αναγνωρίζει τους ενσωματωμένους τύπους πεδίων, όχι εκείνους που καταχωρίζει ένα έργο κατά την εκτέλεση. Σε ένα block που χρησιμοποιεί το acme/price, αναφέρει άγνωστο τύπο πεδίου και χαρακτηρίζει την τιμή ως mixed:

Text
  2      block.json field "price" has unknown type "acme/price" in
         blockstudio/pricing/block.json
         🪪  blockstudio.blockJson.type

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

Neon
parameters:
    level: max
    ignoreErrors:
        -
            identifier: blockstudio.blockJson.type
            message: '#unknown type "acme/price"#'

Με αυτή τη ρύθμιση και το παραπάνω πρότυπο, η ανάλυση περνά. Στην έκδοση 7.6, το πρότυπο χρειάζεται επίσης τη γραμμή @var, με το mixed στις θέσεις των προσαρμοσμένων πεδίων. Από την έκδοση 7.7, το Blockstudio συμπεραίνει μόνο του αυτή τη μορφή και η γραμμή μπορεί να αφαιρεθεί. Δείτε την ενότητα Ελεγμένα πρότυπα με PHPStan για την εκτέλεση της ανάλυσης.

Επόμενα βήματα