Pereiti prie turinio

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:

JSON
{
  "name": "acf/hero",
  "title": "Hero",
  "acf": {
    "renderTemplate": "template.php"
  }
}
PHP
add_action( 'init', function () {
  register_block_type( __DIR__ . '/blocks/hero' );
} );
PHP
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
<?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:

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "title", "type": "text", "label": "Title" },
      { "id": "image", "type": "files", "label": "Background", "multiple": false }
    ]
  }
}
PHP
<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.

Kodas
theme/
└── blockstudio/
    └── hero/
        ├── block.json
        └── index.php

block.json naudoja standartinį WordPress block.json formatą su blockstudio raktu laukams ir konfigūracijai:

JSON
{
  "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:

PHP
['name' => 'title', 'type' => 'text', 'label' => 'Title', 'default_value' => 'Hello']
['name' => 'bio', 'type' => 'textarea', 'label' => 'Bio', 'rows' => 4]
['name' => 'content', 'type' => 'wysiwyg', 'label' => 'Content']

Blockstudio:

JSON
{ "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 />:

JSON
{ "id": "heading", "type": "richtext" }
PHP
<RichText attribute="heading" tag="h1" placeholder="Enter heading" />

Vaizdų ir failų laukai

ACF laukai image ir file atitinka Blockstudio tipą files:

ACF:

PHP
['name' => 'photo', 'type' => 'image', 'return_format' => 'array']
['name' => 'gallery', 'type' => 'gallery', 'return_format' => 'array']
['name' => 'document', 'type' => 'file', 'return_format' => 'array']

Blockstudio:

JSON
{ "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:

PHP
// 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:

PHP
[
  'name' => 'color',
  'type' => 'select',
  'choices' => ['red' => 'Red', 'blue' => 'Blue'],
  'return_format' => 'value',
]

Blockstudio:

JSON
{
  "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ę:

PHP
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:

PHP
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']

Blockstudio:

JSON
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }

ACF:

PHP
['name' => 'cta', 'type' => 'link', 'return_format' => 'array']

// Template
$link = get_field('cta');
echo $link['url'];
echo $link['title'];
echo $link['target'];

Blockstudio:

JSON
{ "id": "cta", "type": "link", "label": "CTA", "opensInNewTab": true }
PHP
echo $a['cta']['url'];
echo $a['cta']['title'];
echo $a['cta']['target'];

Spalva ir gradientas

ACF:

PHP
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']

Blockstudio:

JSON
{ "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:

PHP
['name' => 'count', 'type' => 'number', 'min' => 1, 'max' => 10]
['name' => 'opacity', 'type' => 'range', 'min' => 0, 'max' => 100, 'step' => 5]
['name' => 'eventDate', 'type' => 'date_picker']

Blockstudio:

JSON
{ "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:

PHP
['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:

JSON
{
  "id": "features",
  "type": "repeater",
  "label": "Features",
  "min": 1,
  "max": 10,
  "attributes": [
    { "id": "title", "type": "text", "label": "Title" },
    { "id": "description", "type": "textarea", "label": "Description" }
  ]
}
PHP
<?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:

PHP
['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:

JSON
{
  "id": "author",
  "type": "group",
  "title": "Author",
  "attributes": [
    { "id": "name", "type": "text", "label": "Name" },
    { "id": "role", "type": "text", "label": "Role" }
  ]
}
PHP
<?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:

PHP
['name' => 'showSubtitle', 'type' => 'true_false'],
[
  'name' => 'subtitle',
  'type' => 'text',
  'conditional_logic' => [[['field' => 'field_showSubtitle', 'operator' => '==', 'value' => '1']]]
]

Blockstudio:

JSON
{ "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:

JSON
{
  "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:

PHP
<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:

JSON
{
  "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ą:

JSON
{
  "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:

JSON
{
  "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

  1. Sukurkite bloko aplanką kataloge theme/blockstudio/{block-name}/ su block.json ir index.php.
  2. Perkelkite laukų apibrėžtis iš bloko laukų grupės (Local JSON, acf_add_local_field_group() arba tiesioginio acf.fields masyvo) į blockstudio.attributes masyvą faile block.json. Pakeiskite name į id, pašalinkite key ir prireikus pakoreguokite tipų pavadinimus.
  3. Atnaujinkite prieigą šablone iš get_field('name') į $a['name']. Pakeiskite have_rows() ciklus į foreach ($a['repeater'] as $item).
  4. Pakeiskite get_sub_field() tiesiogine prieiga prie masyvo: $item['fieldId'].
  5. Pridėkite useBlockProps prie išorinio šablono elemento, kad redaktorius būtų tinkamai integruotas.
  6. Perkelkite sąlyginę logiką iš ACF conditional_logic į Blockstudio conditions, nurodydami laukų ID, o ne laukų raktus.
  7. Pridėkite saugojimą laukams, kurie anksčiau buvo užklausiami per get_post_meta() arba naudojami WP_Query.
  8. Pašalinkite ACF registravimo kodą: register_block_type() iškvietimus ir perkeltų blokų acf raktus (arba jų acf_register_block_type() iškvietimus), taip pat jų laukų grupes, nesvarbu, ar jos yra Local JSON, acf_add_local_field_group(), tiesioginiame acf.fields masyve, ar administravimo aplinkoje.
  9. Patikrinkite redaktoriuje, ar laukai rodomi tinkamai, tada peržiūrėkite svetainės išvestį.