İçeriğe geç

Özel Alan Türü Oluşturma

Bazı değerler birden fazla temel değerden oluşur. Fiyat, tutar ve para biriminden meydana gelir. Yerleşik alanlarla bunu yan yana bir sayı alanı ve bir seçim alanı olarak modelliyorsunuz; fiyatı gösteren her blokta bu ikiliyi, etiketleri ve ikisini bir arada tutan mantığı tekrarlıyorsunuz. Yazı metasına iki anahtar, yineleyiciye ise birbirine paralel iki liste olarak kaydediliyor.

Özel alan türü, bu ikiliyi tek bir alana dönüştürür. acme/price gibi bir türü PHP ve JavaScript içinde bir kez kaydedersiniz; ardından üst düzeyde, grupların ve yineleyicilerin içinde, yazı metasına veya seçenek depolamasına kaydederek ve PHP, Twig ve Blade şablonlarında yerel bir alan gibi herhangi bir block.json içinde kullanabilirsiniz. Blockstudio, WordPress özniteliğini ve depolama REST şemasını kayıttan türetir.

Bu, bir özel alan öğesinden farklıdır. custom/{name} referansı mevcut alanlardan oluşan bir grubu yeniden kullanır. Özel alan türü ise kendi değer biçimine sahip yeni bir denetim ekler.

Bu kılavuzda acme/price baştan sona oluşturuluyor: PHP kaydı, düzenleyici denetimi, alanı üst düzeyde ve yineleyici içinde kullanan bir fiyatlandırma bloğu, katı bir REST şemasıyla yazı metasına depolama ve oluşturulan çıktı.

Türü PHP içinde kaydedin

PHP tarafı; öznitelik türünü, varsayılanı, denetimi sağlayan düzenleyici betiğini ve değerin blok dışında nasıl saklanacağını tanımlar:

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 öznitelik türüdür; burada değeri object olur. storage.type, alan yazı meta verilerinde veya seçeneklerde saklandığında kullanılan değer türüdür; storage.rest_schema ise WordPress tarafından REST yazmalarının doğrulanmasında kullanılan şemadır. rest_schema yoksa nesne değeri, her türlü özelliği kabul eden esnek bir şema alır.

init öğesini varsayılan öncelikte kaydedin. Blockstudio, blokları init üzerinde geç keşfeder; o zamana kadar kaydedilmemiş bir tür, oluşturulan blok özniteliklerine dahil edilmez.

bs_register_field_type() başarı durumunda true, ad veya tanım geçersiz olduğunda false döndürür. Adlar küçük harfli, ad alanlı ve tireli olmalıdır; iki ad alanı ayrılmıştır:

Ad Sonuç
acme/price true
Acme/Price false; küçük harf değil
custom/price false; yeniden kullanılabilir alan grupları için ayrılmıştır
blockstudio/price false; Blockstudio çekirdeği için ayrılmıştır

bs_unregister_field_type() bir kaydı kaldırır; blockstudio/field_types filtresi ise ada göre anahtarlanmış bir dizi olarak aynı tanımları kabul eder.

Düzenleyici denetimini oluşturun

Yukarıda kaydedilen betik, React bileşenini sağlar. Düzenleyicide zaten yüklü olan WordPress bileşenlerini kullandığından derleme adımı gerekmez:

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 });
          },
        }),
      ),
    );
  },
});

Bileşen, alan tanımının tüm özelliklerini alır; bu nedenle block.json içine koyduğunuz currencies anahtarı, props.currencies olarak gelir. Ayrıca şu sabit özellikleri de alır: value, onChange, field, defaultValue, attributes, block, clientId, disabled ve repeaterId ile birlikte inRepeater (bir yineleyici satırında oluşturulurken). onChange, değeri tam olarak verildiği haliyle saklar. Özel değerler, yerel select, radio, color ve gradient alanlarının uyguladığı seçenek normalleştirmesinden geçmez.

İlk satırlarda olduğu gibi, nesne olmayan değerlere karşı koruma ekleyin. Alan henüz yokken veya farklı bir biçimde kaydedilmiş bir blok da düzenleyicide açılabilmelidir.

Blockstudio, acme/price kullanan bir blok kaydedilmişse acme-field-price öğesini yalnızca blok düzenleyicisinde kuyruğa ekler. Betik denetimi kaydedemezse düzenleyici, kaydedilmiş değeri korur ve alanın yerine düzenlenemeyen bir bildirim gösterir; ön yüz ise değeri oluşturmaya devam eder.

Bir blokta kullanın

Bir fiyatlandırma bloğu bu türü iki kez kullanır: biri blok dışında sorgulanabilmesi gereken başlangıç fiyatı, diğeri ise katmanlar yineleyicisindeki her satır için:

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"
            }
          }
        ]
      }
    ]
  }
}

Alan düzeyinde verilen default, kayıt varsayılanını geçersiz kılar. Blockstudio, her iki alanı da kayıttaki WordPress özniteliklerine dönüştürür. Kaydedilen blok türü şunları içerir:

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" }
      }
    ]
  }
}

Değeri oluşturun

Şablondaki değer sıradan bir dizidir. Kullanmadan önce türünü sınayın; çünkü saklanan değerin güvenilirliği, onu yazan son şeyin güvenilirliğine bağlıdır:

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() önemlidir. Satırı olmayan bir yineleyici şablona boş dizi olarak değil, false olarak ulaşır; üzerinde doğrudan foreach kullanmak PHP uyarısına yol açar. @var satırı aşağıda, statik analiz bölümünde açıklanıyor.

Blok; başlangıç fiyatı ve iki katmanla oluşturuluyor:

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>

Hiç veri yoksa alanın varsayılan değeri uygulanır ve blok From 19.00 EUR olarak, katman olmadan oluşturulur. Twig ve Blade aynı değeri a.price.amount ve $a['price']['amount'] gibi okur; uzantı şablonları da bu değere {attributes.price.amount} olarak erişebilir.

Depolama ve REST şeması

Her iki alan da postMeta depolamasını tanımlar; böylece blok oluşturulurken Blockstudio iki meta anahtarı kaydeder. Üst düzey alan, kayıtlı depolama şemasını olduğu gibi kullanır:

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
    }
  }
}

Yineleyici içindeki alan her satır için bir değer saklar. Bu nedenle meta anahtarı dizi tabanlıdır ve aynı şema öğe şemasına dönüşür:

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
      }
    }
  }
}

Bloğu içeren bir yazı kaydedildiğinde iki anahtar da eşitlenir. Yukarıdaki iki katmanla get_post_meta( $id, 'acme_price', true ), {"amount":19,"currency":"EUR"} döndürür; acme_tier_prices ise satır fiyatlarının listesini döndürür:

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

Her iki anahtar da yazının REST yanıtında meta altında görünür ve REST yazma işlemleri şemaya göre doğrulanır. Para birimi küçük harfle yazılan bir değer reddedilir:

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

Meta bir kopyadır. Yazı içeriğindeki blok öznitelikleri asıl kaynak olarak kalır ve her kaydetme işleminde yeniden yapılandırılmış anahtarlara eşitlenir. Bu nedenle doğrudan metaya yazılan bir değer, yazı bir sonraki kez kaydedildiğinde değiştirilir. Seçenek depolaması da register_setting() üzerinden aynı şekilde çalışır. Yineleyicilerdeki dizi tabanlı depolama dahil olmak üzere özel alan türleri, Blockstudio 7.5.0 sürümünden itibaren kullanılabilir.

Statik analiz

PHPStan uzantısı yerleşik alan türlerini bilir; projede çalışma zamanında kaydedilen türleri bilmez. acme/price kullanan bir blokta alan türünü bilinmiyor olarak bildirir ve değerini mixed türünde belirtir:

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

Projede kendi türleriniz için bu tanıyı yok sayın ve şablondaki tür sınamasını koruyun; PHPStan, mixed değerini max düzeyinde kabul etmek için buna ihtiyaç duyar:

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

Bu yapılandırma ve yukarıdaki şablonla analiz başarılı olur. 7.6 sürümünde şablon ayrıca, özel alanların bulunduğu yerlere mixed gelecek şekilde @var satırını gerektirir; Blockstudio 7.7 ise bu yapıyı kendiliğinden çıkarır ve satır kaldırılabilir. Analizi çalıştırmak için PHPStan ile Denetlenen Şablonlar bölümüne bakın.

Sonraki adımlar

  • Özel Alan Türleri: tüm tanım anahtarları, API filtresi ve bileşen özelliklerinin tam listesi.
  • Depolama: her alan için yazı meta verisi ve seçenek depolaması.
  • Alan Örüntüleri Rehberi: gruplar, yineleyiciler ve yeniden kullanılabilir alan yapıları.
  • Özel Alanlar: custom/{name} aracılığıyla yeniden kullanılabilir alan grupları.