İçeriğe geç

Özel Alan Türleri

Özel alan türleri, bir temanın veya eklentinin yeni Blockstudio alan kontrolleri eklemesini sağlar. Bunlar özel alanlardan farklıdır:

  • custom/{name} mevcut alanlardan oluşan yeniden kullanılabilir bir grubu ifade eder.
  • namespace/type-name kendi düzenleyici kontrolüne ve değer yapısına sahip, kaydedilmiş bir alan türünü kullanır.

Blockstudio kayıt sistemini sağlar. Kontrolü temanız veya eklentiniz sağlar.

Ne Zaman Kullanılmalı

Bir projenin her yerde yerel bir Blockstudio alanı gibi davranması gereken, tek bir amaca yönelik düzenleme kontrolüne ihtiyacı olduğunda özel alan türü kullanın:

  • blok nitelikleri
  • yeniden kullanılabilir custom/{name} alan grupları
  • gruplar, sekmeler ve tekrarlayıcılar
  • PHP, Twig ve Blade şablonları
  • içerik metaverileri ve seçenek depolaması
  • {attributes.margin.top} gibi eklenti şablonları

Örneğin, bir aralık kontrolü dört ayrı metin alanı yerine tek bir nesne depolayabilir:

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

Adlandırma

Özel alan türü adları küçük harfli, ad alanı içeren ve tireli olmalıdır:

Text
namespace/type-name

Geçerli örnekler:

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

Ayrılmış ad alanları:

  • custom/ yeniden kullanılabilir özel alan grupları için ayrılmıştır.
  • blockstudio/, Blockstudio çekirdeği için ayrılmıştır.

Geçersiz adlar API filtresi tarafından yok sayılır ve API yardımcı işlevi tarafından reddedilir.

PHP Kaydı

Alan türü üst verilerini PHP içinde kaydedin:

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() kayıt başarılı olduğunda true, ad veya tanım geçersiz olduğunda false döndürür. Elle yapılan bir kaydı bs_unregister_field_type() ile kaldırabilirsiniz.

API filtresini de kullanabilirsiniz:

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

    return $types;
});

Tanım Anahtarları

Anahtar Tür Açıklama
attribute string, array, null WordPress öznitelik türü. string, number, boolean, object, array veya bu türlerden oluşan bir dizi kullanın.
default mixed Bir alan kendi varsayılanını tanımlamadığında kayıt düzeyinde kullanılan varsayılan.
source string Özel serileştirme durumları için WordPress öznitelik kaynağı.
produces_attribute boolean Yalnızca görüntüleme amaçlı kontroller için false olarak ayarlayın. Varsayılan değer true.
editor_script string or array Tür kullanıldığında blok düzenleyiciye eklenecek kayıtlı betik tanıtıcısı veya tanıtıcıları.
editor_style string or array Tür kullanıldığında blok düzenleyiciye eklenecek kayıtlı stil tanıtıcısı veya tanıtıcıları.
storage array Depolama değeri türü ve yazı meta verileri ile seçenekler için REST şema ipuçları.
supports array Kendi kontrolünüz için isteğe bağlı yetenek işaretleri.
translate boolean Değer, WPML tarafından çevrilecek metin olduğunda true olarak ayarlayın. attribute string gerekir.

translate değeri boolean olmayan veya translate değeri true olarak ayarlanmışken attribute değeri string dışında olan bir tanım geçersizdir. bs_register_field_type(), false döndürür ve API filtresi bunu yok sayar.

WPML

wp bs wpml config, kayıt işleminden yalnızca özel alan türünün değerinin metin olup olmadığını anlayamaz; bu nedenle bu alanları dışarıda bırakır ve her biri için bir uyarı yazdırır. Düz metin dizesi depolayan bir alan türünün kaydında translate değerini true olarak ayarlayın. Böylece komut, alanlarını text alanları gibi bildirir. Bir alan yine de "translate": false kullanarak bu davranıştan vazgeçebilir. Ayrıntılar için WPMLtaşınabilir medya referansları bölümüne bakın.

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

JavaScript Kaydı

Düzenleyici betiği, eşleşen React kontrolünü kaydeder:

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() kayıt kabul edildiğinde true döndürür. İstemci kaydını şu şekilde kaldırın:

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

Bileşen, alan tanımı özelliklerine ek olarak şu sabit özellikleri alır:

Özellik Açıklama
type Alan türünün adı.
id Alan kimliği.
field block.json kaynağındaki tam alan tanımı.
value O anda kayıtlı olan değer.
defaultValue Alanın varsayılan değeri.
onChange Yeni bir değeri doğrudan kaydeder.
attributes Geçerli blok nitelikleri.
block Geçerli blok türü tanımı.
clientId Geçerli düzenleyici blok istemci kimliği.
inRepeater Alanın bir tekrarlayıcı satırında olup olmadığı.
repeaterId Varsa geçerli tekrarlayıcı yolu.
disabled Alanın düzenleyicide devre dışı olup olmadığı.

Özel alan türü değerleri doğrudan depolanır. Bunlar yerel select, radio, color veya gradient seçenek normalleştirmesinden geçmez.

Değerleri Görüntüleme

Nesne değerlerine diğer tüm Blockstudio nitelikleri gibi erişilebilir.

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>

İç içe nesne yolları eklenti şablonlarında da çalışır:

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

Depolama

Özel alan türü postMeta veya option depolamasıyla kullanıldığında, Blockstudio kaydedilmiş depolama değeri türünü ve REST şemasını kullanır.

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

array ve object değerleri için alan türü kaydında storage.rest_schema tanımlayın. Tekrarlayıcı satırları depoladığından, tekrarlayıcı alt öğeleri dizi tabanlı depolamayı kullanmaya devam eder.

Geri Dönüş Davranışı

PHP alan türünü biliyor ancak düzenleyici betiği eşleşen bir kontrol kaydetmiyorsa, Blockstudio kayıtlı değeri korur ve düzenleyicide düzenlenemeyen bir bildirim gösterir. Ön uçta işleme yine kayıtlı değeri alır.

PHP içinde bir alan türü kayıtlı değilse, Blockstudio bu türü oluşturulan WordPress niteliklerine dahil etmez. Blok keşfi çalışmadan önce PHP tanımını kaydedin; bu genellikle init, Blockstudio blokları oluşturmadan önce yapılır.