Ö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-namekendi 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:
{
"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:
namespace/type-name
Geçerli örnekler:
acme/dimensionsacme/text-optionstheme/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:
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:
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.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
JavaScript Kaydı
Düzenleyici betiği, eşleşen React kontrolünü kaydeder:
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:
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
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
<?php echo esc_html($a['title'] ?? ''); ?>
</div>
Twig
<div class="mt-{{ a.margin.top }}">
{{ a.title }}
</div>
Blade
<div class="mt-{{ $a['margin']['top'] ?? '' }}">
{{ $a['title'] ?? '' }}
</div>
İç içe nesne yolları eklenti şablonlarında da çalışır:
{
"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.
{
"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.