Perėjimas nuo ACF Blocks
Jei kūrėte pasirinktinius WordPress blokus naudodami ACF (Advanced Custom Fields), pereiti prie Blockstudio nesudėtinga. Sąvokos panašios: apibrėžiate laukus, rašote šabloną, ir blokas atsiranda redaktoriuje. Skirtumas tas, kad Blockstudio savaime aptinka blokų aplankus, laukus apibrėžia savo schemoje block.json, o kiekvienam šablonui perduoda jų reikšmes viename $a masyve.
Šiame vadove žingsnis po žingsnio aprašomas perkėlimas ir pateikiami gretinami ACF bei Blockstudio šablonų pavyzdžiai.
Esminis skirtumas
Nuo ACF 6.0 versijos ACF blokas yra block.json su acf raktu, nurodančiu jo atvaizdavimo šabloną, o kiekvienas bloko aplankas registruojamas atskiru register_block_type() iškvietimu. Laukai gaunami iš laukų grupės, susietos su bloku naudojant bloko vietos taisyklę (sukurtos administravimo srityje, sinchronizuotos per vietinį JSON arba užregistruotos naudojant acf_add_local_field_group()), arba nuo ACF PRO 6.8.1 versijos – iš įterptojo acf.fields masyvo tame pačiame block.json. Blockstudio registravimo iškvietimą pakeičia automatiniu atradimu pagal failus: sukurkite aplanką su block.json ir index.php, ir blokas bus užregistruotas automatiškai.
ACF:
{
"name": "acf/hero",
"title": "Hero",
"acf": {
"renderTemplate": "template.php"
}
}
add_action( 'init', function () {
register_block_type( __DIR__ . '/blocks/hero' );
} );
acf_add_local_field_group([
'key' => 'group_hero',
'title' => 'Hero Fields',
'fields' => [
['key' => 'field_title', 'name' => 'title', 'type' => 'text', 'label' => 'Title'],
['key' => 'field_image', 'name' => 'image', 'type' => 'image', 'label' => 'Background', 'return_format' => 'array'],
],
'location' => [[['param' => 'block', 'operator' => '==', 'value' => 'acf/hero']]],
]);
<?php
$title = get_field('title');
$image = get_field('image');
?>
<div class="hero" <?php if ($image) : ?>style="background-image: url(<?php echo esc_url($image['url']); ?>)"<?php endif; ?>>
<h1><?php echo esc_html($title); ?></h1>
</div>
Blockstudio:
{
"name": "my-theme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "image", "type": "files", "label": "Background", "multiple": false }
]
}
}
<div useBlockProps class="hero" <?php if ($a['image']) : ?>style="background-image: url(<?php echo esc_url($a['image']['url']); ?>)"<?php endif; ?>>
<h1><?php echo esc_html($a['title']); ?></h1>
</div>
Nereikia nei registravimo iškvietimo, nei atvaizdavimo grįžtamojo iškvietimo funkcijos: registravimą apibrėžia aplankų struktūra, o laukai yra block.json šalia šablono. Šablone naudojama $a, o ne iškviečiama get_field().
Bloko registravimas
ACF
Dabartiniai ACF blokai registruojami iš block.json su acf raktu (renderTemplate arba renderCallback, taip pat tokiomis parinktimis kaip blockVersion). Jie įkeliami kiekvienam bloko aplankui atskirai iškviečiant register_block_type(), paprastai faile init, esančiame functions.php, arba įskiepio faile. Senesniuose blokuose vis dar gali būti naudojama acf_register_block_type(), kurią ACF dokumentuose pažymėjo kaip pasenusią nuo ACF 6.0 versijos; ji vis dar veikia, todėl tokius blokus perkelkite tuo pačiu būdu.
Blockstudio
Sukurkite aplanką temos blockstudio/ kataloge (arba blocks/, jei taip patogiau). Pridėkite block.json su standartiniais WordPress bloko metaduomenimis ir blockstudio raktu. Viskas.
theme/
└── blockstudio/
└── hero/
├── block.json
└── index.php
block.json naudoja standartinį WordPress block.json formatą su blockstudio raktu laukams ir konfigūracijai:
{
"name": "my-theme/hero",
"title": "Hero",
"category": "theme",
"icon": "cover-image",
"description": "Full-width hero section with background image.",
"blockstudio": {
"attributes": []
}
}
Prieiga prie laukų reikšmių
Tai dažniausias pakeitimas, kurį atliksite perkeldami.
| ACF | Blockstudio |
|---|---|
get_field('title') |
$a['title'] |
get_field('title', $post_id) |
$a['title'] (visada pasiekiama) |
the_field('title') |
<?php echo $a['title']; ?> |
have_rows('items') / the_row() |
foreach ($a['items'] as $item) |
get_sub_field('name') |
$item['name'] |
$a kintamasis yra trumpesnė $attributes forma ir apima visas dabartinio bloko laukų reikšmes. Jis visada pasiekiamas šablone, tiek redaktoriuje, tiek sąsajoje.
Šablono kintamieji
Blockstudio kiekviename šablone pateikia kelis kintamuosius:
| Kintamasis | Trumpinys | Aprašas |
|---|---|---|
$attributes |
$a |
Visos laukų reikšmės |
$block |
$b |
Bloko metaduomenys (pavadinimas, antraštė, dir, url, postId) |
$context |
$c |
Pirminio bloko kontekstas |
$content |
InnerBlocks turinys | |
$post_id |
Dabartinio įrašo ID (veikia redaktoriuje ir sąsajoje; post_id arba postId sistemoje Twig) |
Laukų tipų atitikmenys
Daugumai ACF laukų tipų yra tiesioginis atitikmuo Blockstudio. JSON sintaksė kitokia, tačiau sąvokos lengvai susiejamos.
Teksto ir turinio laukai
ACF:
['name' => 'title', 'type' => 'text', 'label' => 'Title', 'default_value' => 'Hello']
['name' => 'bio', 'type' => 'textarea', 'label' => 'Bio', 'rows' => 4]
['name' => 'content', 'type' => 'wysiwyg', 'label' => 'Content']
Blockstudio:
{ "id": "title", "type": "text", "label": "Title", "default": "Hello" }
{ "id": "bio", "type": "textarea", "label": "Bio", "rows": 4 }
{ "id": "content", "type": "wysiwyg", "label": "Content" }
Jei norite redaguojamo teksto blokų redaktoriuje (ne tik teksto įvesties lauko), naudokite richtext tipą su komponentu <RichText />:
{ "id": "heading", "type": "richtext" }
<RichText attribute="heading" tag="h1" placeholder="Enter heading" />
Vaizdų ir failų laukai
ACF laukai image ir file atitinka Blockstudio tipą files:
ACF:
['name' => 'photo', 'type' => 'image', 'return_format' => 'array']
['name' => 'gallery', 'type' => 'gallery', 'return_format' => 'array']
['name' => 'document', 'type' => 'file', 'return_format' => 'array']
Blockstudio:
{ "id": "photo", "type": "files", "label": "Photo", "multiple": false }
{ "id": "gallery", "type": "files", "label": "Gallery", "multiple": true }
{ "id": "document", "type": "files", "label": "Document", "multiple": false, "allowedTypes": ["application/pdf"] }
Grąžinamo objekto struktūra panaši:
// ACF
$image = get_field('photo');
echo $image['url'];
echo $image['alt'];
// Blockstudio
echo $a['photo']['url'];
echo $a['photo']['alt'];
Galimos savybės: ID, title, alt, caption, description, href, url, sizes. Matmenys pateikiami sizes, pavyzdžiui, $a['photo']['sizes']['full-width'].
Sąrašas, radijo mygtukai ir žymimieji langeliai
ACF:
[
'name' => 'color',
'type' => 'select',
'choices' => ['red' => 'Red', 'blue' => 'Blue'],
'return_format' => 'value',
]
Blockstudio:
{
"id": "color",
"type": "select",
"label": "Color",
"options": [
{ "value": "red", "label": "Red" },
{ "value": "blue", "label": "Blue" }
]
}
Naudokite "returnFormat": "both", kad gautumėte ir reikšmę, ir etiketę:
echo $a['color']['value']; // "red"
echo $a['color']['label']; // "Red"
Tas pats šablonas taikomas radio ir checkbox tipams.
Perjungiklis ir loginės reikšmės
ACF:
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']
Blockstudio:
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }
Nuorodos laukas
ACF:
['name' => 'cta', 'type' => 'link', 'return_format' => 'array']
// Template
$link = get_field('cta');
echo $link['url'];
echo $link['title'];
echo $link['target'];
Blockstudio:
{ "id": "cta", "type": "link", "label": "CTA", "opensInNewTab": true }
echo $a['cta']['url'];
echo $a['cta']['title'];
echo $a['cta']['target'];
Spalva ir gradientas
ACF:
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']
Blockstudio:
{ "id": "bgColor", "type": "color", "label": "Background" }
{ "id": "bgGradient", "type": "gradient", "label": "Background Gradient" }
Tipas color susiejamas su WordPress spalvų palete. Tipas gradient suteikia gradiento parinkiklį.
Skaičius, intervalas ir data
ACF:
['name' => 'count', 'type' => 'number', 'min' => 1, 'max' => 10]
['name' => 'opacity', 'type' => 'range', 'min' => 0, 'max' => 100, 'step' => 5]
['name' => 'eventDate', 'type' => 'date_picker']
Blockstudio:
{ "id": "count", "type": "number", "label": "Count", "min": 1, "max": 10 }
{ "id": "opacity", "type": "range", "label": "Opacity", "min": 0, "max": 100, "step": 5 }
{ "id": "eventDate", "type": "date", "label": "Event Date" }
Kartotuvai
ACF kartotuvo laukas tiesiogiai atitinka Blockstudio tipą repeater. ACF šablonuose paprastai naudojama have_rows() / the_row() / get_sub_field() (kartotuvui skirta get_field() taip pat grąžina eilučių masyvą); Blockstudio turi tik paprastą PHP masyvą, jau esantį $a.
ACF:
['name' => 'features', 'type' => 'repeater', 'sub_fields' => [
['name' => 'title', 'type' => 'text'],
['name' => 'description', 'type' => 'textarea'],
]]
// Template
if (have_rows('features')) :
while (have_rows('features')) : the_row();
echo get_sub_field('title');
echo get_sub_field('description');
endwhile;
endif;
Blockstudio:
{
"id": "features",
"type": "repeater",
"label": "Features",
"min": 1,
"max": 10,
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "description", "type": "textarea", "label": "Description" }
]
}
<?php foreach ($a['features'] as $feature) : ?>
<h3><?php echo esc_html($feature['title']); ?></h3>
<p><?php echo esc_html($feature['description']); ?></p>
<?php endforeach; ?>
Blockstudio kartotuvuose galima įdėti vieną į kitą, daugiausia iki 3 lygių.
Grupės
ACF grupės laukas atitinka Blockstudio tipą group. Grupės viduje esančių laukų ID papildomi grupės ID priešdėliu.
ACF:
['name' => 'author', 'type' => 'group', 'sub_fields' => [
['name' => 'name', 'type' => 'text'],
['name' => 'role', 'type' => 'text'],
]]
// Template
$author = get_field('author');
echo $author['name'];
echo $author['role'];
Blockstudio:
{
"id": "author",
"type": "group",
"title": "Author",
"attributes": [
{ "id": "name", "type": "text", "label": "Name" },
{ "id": "role", "type": "text", "label": "Role" }
]
}
<?php $author = bs_get_group($a, 'author'); ?>
<p><?php echo esc_html($author['name']); ?></p>
<p><?php echo esc_html($author['role']); ?></p>
bs_get_group() pagalbinė funkcija pašalina grupės priešdėlį iš laukų ID, kad juos būtų patogu pasiekti. Be jos laukus pasiektumėte kaip $a['author_name'] ir $a['author_role'].
Sąlyginė logika
Tiek ACF, tiek Blockstudio palaiko sąlyginę logiką, pagal kitų laukų reikšmes rodančią arba slepiančią laukus.
ACF:
['name' => 'showSubtitle', 'type' => 'true_false'],
[
'name' => 'subtitle',
'type' => 'text',
'conditional_logic' => [[['field' => 'field_showSubtitle', 'operator' => '==', 'value' => '1']]]
]
Blockstudio:
{ "id": "showSubtitle", "type": "toggle", "label": "Show Subtitle" },
{
"id": "subtitle",
"type": "text",
"label": "Subtitle",
"conditions": [[{ "id": "showSubtitle", "operator": "==", "value": true }]]
}
Blockstudio sąlygose tiesiogiai nurodomi laukų ID (ne laukų raktai). Galimi operatoriai: ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.
Blockstudio taip pat palaiko visuotines sąlygas pagal įrašo tipą, įrašo ID, naudotojo vaidmenį ir naudotojo ID:
{
"conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}
InnerBlocks
Tiek ACF, tiek Blockstudio palaiko InnerBlocks, kad į pasirinktinį bloką būtų galima įdėti kitų blokų, naudojant tą pačią <InnerBlocks /> žymą ir tuos pačius allowedBlocks, template bei templateLock atributus, todėl ši šablono dalis paprastai perkeliama nepakeista.
Blockstudio:
<div useBlockProps class="my-wrapper">
<InnerBlocks
allowedBlocks='<?php echo esc_attr(wp_json_encode(["core/heading", "core/paragraph", "core/image"])); ?>'
template='<?php echo esc_attr(wp_json_encode([
["core/heading", ["placeholder" => "Section title"]],
["core/paragraph", ["placeholder" => "Section content"]]
])); ?>'
templateLock="insert"
/>
</div>
Žymą <InnerBlocks /> redaktoriuje pakeičia komponentas React, o sąsajoje – atvaizduotas bloko turinys.
Įrašo metaduomenų saugojimas
Tiek ACF Blocks, tiek Blockstudio laukų reikšmes pagal numatytuosius nustatymus saugo įrašo turinyje kaip bloko atributus, o ne įrašo metaduomenyse. Tai reiškia, kad laukų reikšmių negalima užklausti naudojant WP_Query, nebent pasirenkate saugojimą metaduomenyse.
ACF pridėjo pasirenkamą blokų saugojimą įrašo metaduomenyse ACF PRO 6.3 versijoje per usePostMeta: true – po vieną aukščiausio lygio bloką kiekviename puslapyje. Blockstudio turi kiekvieno lauko pasirenkamą mechanizmą, naudojantį ypatybę storage:
{
"id": "featured",
"type": "toggle",
"label": "Featured",
"storage": {
"type": "postMeta",
"postMetaKey": "is_featured"
}
}
Meta raktas automatiškai užregistruojamas su show_in_rest. Pasiekite jį bet kur naudodami get_post_meta($post_id, 'is_featured', true).
Visos svetainės reikšmėms (pvz., ACF parinkčių puslapiams) naudokite parinkčių saugyklą:
{
"storage": {
"type": "option",
"optionKey": "site_company_name"
}
}
Esamų blokų išplėtimas
ACF blokų vietos taisyklė susieja laukų grupes tik su ACF blokais; ji neprideda laukų prie pagrindinių ar trečiųjų šalių blokų. ACF būdas pasiekti pagrindinius blokus, pvz., antraštę, pastraipą, vaizdą ir mygtuką, yra WordPress blokų susiejimai API, susiejantys esamus blokų atributus su ACF laukų reikšmėmis. Blockstudio gali pridėti naujų laukų ir valdiklių prie bet kurio užregistruoto bloko per plėtinių failus.
Sukurkite plėtinio failą savo blockstudio kataloge:
{
"name": "core/heading",
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "accentColor",
"type": "color",
"label": "Accent Color",
"set": [{ "attribute": "style", "value": "color: {attributes.accentColor}" }]
}
]
}
}
Ypatybė set automatiškai pritaiko lauko reikšmę bloko HTML. Naudokite pakaitos simbolius, kad vienu metu išplėstumėte kelis blokus: "name": "core/*".
Perkėlimo kontrolinis sąrašas
- Sukurkite bloko aplanką kataloge
theme/blockstudio/{block-name}/sublock.jsonirindex.php. - Perkelkite laukų apibrėžtis iš bloko laukų grupės (Local JSON,
acf_add_local_field_group()arba tiesioginioacf.fieldsmasyvo) įblockstudio.attributesmasyvą faileblock.json. Pakeiskitenameįid, pašalinkitekeyir prireikus pakoreguokite tipų pavadinimus. - Atnaujinkite prieigą šablone iš
get_field('name')į$a['name']. Pakeiskitehave_rows()ciklus įforeach ($a['repeater'] as $item). - Pakeiskite
get_sub_field()tiesiogine prieiga prie masyvo:$item['fieldId']. - Pridėkite
useBlockPropsprie išorinio šablono elemento, kad redaktorius būtų tinkamai integruotas. - Perkelkite sąlyginę logiką iš ACF
conditional_logicį Blockstudioconditions, nurodydami laukų ID, o ne laukų raktus. - Pridėkite saugojimą laukams, kurie anksčiau buvo užklausiami per
get_post_meta()arba naudojamiWP_Query. - Pašalinkite ACF registravimo kodą:
register_block_type()iškvietimus ir perkeltų blokųacfraktus (arba jųacf_register_block_type()iškvietimus), taip pat jų laukų grupes, nesvarbu, ar jos yra Local JSON,acf_add_local_field_group(), tiesioginiameacf.fieldsmasyve, ar administravimo aplinkoje. - Patikrinkite redaktoriuje, ar laukai rodomi tinkamai, tada peržiūrėkite svetainės išvestį.