Pielāgoti lauku tipi
Pielāgoti lauku tipi ļauj tēmai vai spraudnim pievienot jaunas Blockstudio lauku vadīklas. Tās atšķiras no pielāgotajiem laukiem:
custom/{name}apzīmē atkārtoti izmantojamu esošo lauku grupu.namespace/type-nameizmanto reģistrētu lauka tipu ar savu redaktora vadīklu un vērtības struktūru.
Blockstudio nodrošina reģistrācijas sistēmu. Jūsu tēma vai spraudnis nodrošina vadīklu.
Kad tos izmantot
Izmantojiet pielāgotu lauka tipu, ja projektam nepieciešama īpašam mērķim paredzēta rediģēšanas vadīkla, kurai visur jādarbojas kā iebūvētam Blockstudio laukam:
- bloka atribūti
- atkārtoti izmantojamas
custom/{name}lauku grupas - grupas, cilnes un atkārtotāji
- PHP, Twig un Blade veidnes
- ierakstu metadati un opciju krātuve
- paplašinājumu veidnes, piemēram,
{attributes.margin.top}
Piemēram, atstarpju vadīkla var saglabāt vienu objektu četru atsevišķu teksta lauku vietā:
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "right", "bottom", "left"],
"default": {
"top": "sm",
"right": "md",
"bottom": "sm",
"left": "md"
}
}
]
}
}
Nosaukumu veidošana
Pielāgotu lauku tipu nosaukumiem jābūt ar mazajiem burtiem, nosaukumvietu un vārdiem, kas atdalīti ar defisēm:
namespace/type-name
Derīgi piemēri:
acme/dimensionsacme/text-optionstheme/spacing-token
Rezervētās nosaukumvietas:
custom/ir rezervēta atkārtoti izmantojamām pielāgoto lauku grupām.blockstudio/ir rezervēta Blockstudio kodolam.
Nederīgus nosaukumus filtrs API ignorē, bet palīgfunkcija API noraida.
PHP reģistrācija
Reģistrējiet lauka tipa metadatus failā 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() atgriež true, ja reģistrācija izdodas, un false,
ja nosaukums vai definīcija nav derīga. Manuālu reģistrāciju var atcelt ar
bs_unregister_field_type().
Varat izmantot arī filtru API:
add_filter('blockstudio/field_types', function (array $types): array {
$types['acme/dimensions'] = [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
];
return $types;
});
Definīcijas atslēgas
| Atslēga | Tips | Apraksts |
|---|---|---|
attribute |
string, array, null |
WordPress atribūta tips. Izmantojiet string, number, boolean, object, array vai šo tipu masīvu. |
default |
jaukts | Reģistra līmeņa noklusējuma vērtība, ja laukam nav norādīta sava noklusējuma vērtība. |
source |
virkne | WordPress atribūta avots pielāgotas serializācijas gadījumiem. |
produces_attribute |
Būla vērtība | Iestatiet uz false tikai attēlošanai paredzētām vadīklām. Noklusējuma vērtība ir true. |
editor_script |
virkne vai masīvs | Reģistrēta skripta rokturis vai rokturi, ko iekļaut bloku redaktorā, kad tips tiek izmantots. |
editor_style |
virkne vai masīvs | Reģistrēta stila rokturis vai rokturi, ko iekļaut bloku redaktorā, kad tips tiek izmantots. |
storage |
masīvs | Krātuves vērtības tipa un REST shēmas norādes ziņu metadatiem un opcijām. |
supports |
masīvs | Neobligāti iespēju karodziņi jūsu vadīklai. |
translate |
Būla vērtība | Iestatiet uz true, ja vērtība ir teksts, ko var tulkot ar WPML. Nepieciešams attribute string. |
Definīcija ar translate vērtību, kas nav Būla vērtība, vai ar translate, kas iestatīts uz true, un attribute, kura vērtība nav string, ir nederīga.
bs_register_field_type() atgriež false, un filtrs API to ignorē.
WPML
wp bs wpml config pēc reģistrācijas vien nevar noteikt, vai pielāgotā lauka tipa vērtība ir teksts, tāpēc šādus laukus izlaiž un par katru parāda brīdinājumu. Reģistrējot lauka tipu, kurā tiek glabāta vienkārša teksta virkne, iestatiet translate uz true, un komanda tā laukus deklarēs tāpat kā text laukus. Laukam joprojām var norādīt izņēmumu, izmantojot "translate": false. Skatiet Tulkojamie laukiWPML.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
JavaScript reģistrācija
Redaktora skripts reģistrē atbilstošo React vadīklu:
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() atgriež true, ja reģistrācija tiek pieņemta. Lai noņemtu klienta puses reģistrāciju:
window.blockstudio.unregisterFieldType('acme/dimensions');
Komponentam tiek nodoti lauka definīcijas rekvizīti un šie nemainīgie rekvizīti:
| Rekvizīts | Apraksts |
|---|---|
type |
Lauka tipa nosaukums. |
id |
Lauka ID. |
field |
Pilna lauka definīcija no block.json. |
value |
Pašreizējā saglabātā vērtība. |
defaultValue |
Lauka noklusējuma vērtība. |
onChange |
Saglabāt jaunu vērtību tieši. |
attributes |
Pašreizējie bloka atribūti. |
block |
Pašreizējā bloka tipa definīcija. |
clientId |
Pašreizējā redaktora bloka klienta ID. |
inRepeater |
Vai lauks atrodas atkārtotāja rindā. |
repeaterId |
Pašreizējais atkārtotāja ceļš, ja tāds ir. |
disabled |
Vai lauks redaktorā ir atspējots. |
Pielāgotu lauku tipu vērtības tiek glabātas tieši. Tās netiek normalizētas kā iebūvētās
opcijas, select, radio, color vai gradient.
Vērtību attēlošana
Objektu vērtības ir pieejamas tāpat kā jebkurš cits Blockstudio atribūts.
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>
Ligzdoti objektu ceļi darbojas arī paplašinājumu veidnēs:
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
Krātuve
Ja pielāgotu lauka tipu izmanto kopā ar postMeta vai option krātuvi,
Blockstudio izmanto reģistrēto krātuves vērtības tipu un REST shēmu.
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"storage": {
"type": "postMeta",
"postMetaKey": "acme_margin"
}
}
Vērtībām array un object definējiet storage.rest_schema lauka tipa
reģistrācijā. Atkārtotāju pēcteči turpina izmantot masīvos balstītu krātuvi, jo
atkārtotājā tiek glabātas rindas.
Rezerves darbība
Ja PHP pazīst lauka tipu, bet redaktora skripts nereģistrē atbilstošu vadīklu, Blockstudio patur saglabāto vērtību un redaktorā rāda paziņojumu, ko nevar rediģēt. Priekšgala attēlošana joprojām saņem saglabāto vērtību.
Ja lauka tips nav reģistrēts failā PHP, Blockstudio neiekļauj to
ģenerētajos WordPress atribūtos. Reģistrējiet PHP definīciju, pirms tiek
sākta bloku noteikšana, parasti failā init pirms Blockstudio veido blokus.