Μετάβαση από ACF Blocks
Αν δημιουργείτε προσαρμοσμένα μπλοκ WordPress με το ACF (Advanced Custom Fields), η μετάβαση στο Blockstudio είναι απλή. Οι έννοιες είναι παρόμοιες: ορίζετε πεδία, γράφετε ένα πρότυπο και το μπλοκ εμφανίζεται στον επεξεργαστή. Οι διαφορές είναι ότι το Blockstudio εντοπίζει μόνο του τους φακέλους μπλοκ, δηλώνει τα πεδία στο δικό του σχήμα μέσα στο block.json και παρέχει σε κάθε πρότυπο τις τιμές των πεδίων του ως έναν πίνακα $a.
Αυτός ο οδηγός περιγράφει τη μετάβαση βήμα προς βήμα, με συγκρίσεις των μοτίβων ACF και Blockstudio δίπλα-δίπλα.
Η βασική διαφορά
Από την έκδοση ACF 6.0, ένα μπλοκ ACF είναι ένα block.json με κλειδί acf που ορίζει το πρότυπο απόδοσής του, ενώ κάθε φάκελος μπλοκ καταχωρίζεται με δική του κλήση register_block_type(). Τα πεδία προέρχονται από ομάδα πεδίων που έχει συνδεθεί στο μπλοκ με κανόνα τοποθεσίας Block (δημιουργημένη στον πίνακα διαχείρισης, συγχρονισμένη μέσω του Local JSON ή καταχωρισμένη με το acf_add_local_field_group()) ή, από την έκδοση ACF PRO 6.8.1, από έναν ενσωματωμένο πίνακα acf.fields στο ίδιο block.json. Το Blockstudio αντικαθιστά την κλήση καταχώρισης με αυτόματη ανακάλυψη βάσει αρχείων: δημιουργήστε έναν φάκελο με ένα block.json και ένα index.php και το μπλοκ καταχωρίζεται αυτόματα.
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>
Δεν χρειάζεται κλήση καταχώρισης ούτε επανάκληση απόδοσης: η δομή φακέλων αποτελεί την καταχώριση και τα πεδία βρίσκονται στο block.json δίπλα στο πρότυπο. Το πρότυπο διαβάζει το $a αντί να καλεί το get_field().
Καταχώριση μπλοκ
ACF
Τα τρέχοντα μπλοκ ACF καταχωρίζονται από ένα block.json με κλειδί acf (renderTemplate ή renderCallback, μαζί με επιλογές όπως το blockVersion), που φορτώνεται με ρητή κλήση register_block_type() για κάθε φάκελο μπλοκ, συνήθως στο init μέσα στο functions.php ή σε αρχείο πρόσθετου. Τα παλαιότερα μπλοκ μπορεί να χρησιμοποιούν ακόμη το acf_register_block_type(), το οποίο το ACF έχει τεκμηριώσει ως παρωχημένο από την έκδοση ACF 6.0· εξακολουθεί να λειτουργεί, οπότε μεταβείτε με τον ίδιο τρόπο και για αυτά τα μπλοκ.
Blockstudio
Δημιουργήστε έναν φάκελο στον κατάλογο blockstudio/ του θέματός σας (ή στο blocks/, αν προτιμάτε). Προσθέστε ένα block.json με τα τυπικά μεταδεδομένα μπλοκ WordPress και ένα κλειδί blockstudio. Αυτό ήταν.
theme/
└── blockstudio/
└── hero/
├── block.json
└── index.php
Το block.json χρησιμοποιεί την τυπική μορφή WordPress block.json με το κλειδί blockstudio για πεδία και διαμόρφωση:
{
"name": "my-theme/hero",
"title": "Hero",
"category": "theme",
"icon": "cover-image",
"description": "Full-width hero section with background image.",
"blockstudio": {
"attributes": []
}
}
Πρόσβαση στις τιμές πεδίων
Αυτή είναι η συνηθέστερη αλλαγή που θα κάνετε κατά τη μετάβαση.
| ACF | Blockstudio |
|---|---|
get_field('title') |
$a['title'] |
get_field('title', $post_id) |
$a['title'] (διαθέσιμο πάντα) |
the_field('title') |
<?php echo $a['title']; ?> |
have_rows('items') / the_row() |
foreach ($a['items'] as $item) |
get_sub_field('name') |
$item['name'] |
Η μεταβλητή $a είναι συντομογραφία του $attributes και περιέχει όλες τις τιμές πεδίων για το τρέχον μπλοκ. Είναι πάντα διαθέσιμη στο πρότυπο, τόσο στον επεξεργαστή όσο και στο frontend.
Μεταβλητές προτύπου
Το Blockstudio παρέχει αρκετές μεταβλητές σε κάθε πρότυπο:
| Μεταβλητή | Συντομογραφία | Περιγραφή |
|---|---|---|
$attributes |
$a |
Όλες οι τιμές πεδίων |
$block |
$b |
Μεταδεδομένα μπλοκ (name, title, dir, url, postId) |
$context |
$c |
Πλαίσιο γονικού μπλοκ |
$content |
Περιεχόμενο InnerBlocks | |
$post_id |
Τρέχον αναγνωριστικό ανάρτησης (λειτουργεί στον επεξεργαστή και στο frontend· post_id ή postId στο Twig) |
Αντιστοίχιση τύπων πεδίων
Οι περισσότεροι τύποι πεδίων ACF έχουν άμεσο αντίστοιχο στο Blockstudio. Η σύνταξη JSON διαφέρει, αλλά οι έννοιες αντιστοιχίζονται εύκολα.
Πεδία κειμένου και περιεχομένου
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" }
Για επεξεργάσιμο κείμενο στον επεξεργαστή μπλοκ (όχι απλώς ένα πεδίο εισαγωγής κειμένου), χρησιμοποιήστε τον τύπο richtext με το στοιχείο <RichText />:
{ "id": "heading", "type": "richtext" }
<RichText attribute="heading" tag="h1" placeholder="Enter heading" />
Πεδία εικόνας και αρχείων
Τα πεδία image και file του ACF αντιστοιχούν στον τύπο files του Blockstudio:
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"] }
Η δομή του αντικειμένου που επιστρέφεται είναι παρόμοια:
// ACF
$image = get_field('photo');
echo $image['url'];
echo $image['alt'];
// Blockstudio
echo $a['photo']['url'];
echo $a['photo']['alt'];
Διαθέσιμες ιδιότητες: ID, title, alt, caption, description, href, url, sizes. Οι διαστάσεις βρίσκονται στο sizes, για παράδειγμα $a['photo']['sizes']['full-width'].
Επιλογή, κουμπί επιλογής και πλαίσιο ελέγχου
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" }
]
}
Χρησιμοποιήστε το "returnFormat": "both" για να λάβετε τόσο την τιμή όσο και την ετικέτα:
echo $a['color']['value']; // "red"
echo $a['color']['label']; // "Red"
Το ίδιο μοτίβο ισχύει για τους τύπους radio και checkbox.
Εναλλαγή και αληθές/ψευδές
ACF:
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']
Blockstudio:
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }
Πεδίο συνδέσμου
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'];
Χρώμα και διαβάθμιση
ACF:
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']
Blockstudio:
{ "id": "bgColor", "type": "color", "label": "Background" }
{ "id": "bgGradient", "type": "gradient", "label": "Background Gradient" }
Ο τύπος color ενσωματώνεται στην παλέτα χρωμάτων WordPress. Ο τύπος gradient παρέχει επιλογέα διαβάθμισης.
Αριθμός, εύρος και ημερομηνία
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" }
Επαναλήπτες
Το πεδίο επαναλήπτη του ACF αντιστοιχεί απευθείας στον τύπο repeater του Blockstudio. Τα πρότυπα ACF συνήθως κάνουν επανάληψη με have_rows() / the_row() / get_sub_field() (το get_field() σε επαναλήπτη επιστρέφει επίσης έναν πίνακα γραμμών)· το Blockstudio διαθέτει μόνο τον απλό πίνακα PHP, ήδη σε $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 υποστηρίζουν ένθετη δομή (επαναλήπτης μέσα σε επαναλήπτη) έως 3 επίπεδα.
Ομάδες
Το πεδίο ομάδας του ACF αντιστοιχεί στον τύπο group του Blockstudio. Τα αναγνωριστικά πεδίων μέσα στις ομάδες έχουν ως πρόθεμα το αναγνωριστικό της ομάδας.
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() αφαιρεί το πρόθεμα ομάδας από τα αναγνωριστικά πεδίων, για εύκολη πρόσβαση. Χωρίς αυτό, θα αποκτούσατε πρόσβαση στα πεδία ως $a['author_name'] και $a['author_role'].
Λογική υπό συνθήκη
Τόσο το ACF όσο και το Blockstudio υποστηρίζουν λογική συνθηκών για την εμφάνιση και την απόκρυψη πεδίων με βάση τις τιμές άλλων πεδίων.
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 αναφέρονται απευθείας στα αναγνωριστικά πεδίων (όχι στα κλειδιά πεδίων). Διαθέσιμοι τελεστές: ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.
Το Blockstudio υποστηρίζει επίσης καθολικές συνθήκες με βάση τον τύπο ανάρτησης, το αναγνωριστικό ανάρτησης, τον ρόλο χρήστη και το αναγνωριστικό χρήστη:
{
"conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}
InnerBlocks
Τόσο το ACF όσο και το Blockstudio υποστηρίζουν InnerBlocks για ένθεση άλλων μπλοκ στο προσαρμοσμένο μπλοκ σας, με την ίδια ετικέτα <InnerBlocks /> και τα ίδια χαρακτηριστικά allowedBlocks, template και templateLock, επομένως αυτό το μέρος ενός προτύπου συνήθως μεταφέρεται αυτούσιο.
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>
Η ετικέτα <InnerBlocks /> αντικαθίσταται με το στοιχείο React στον επεξεργαστή και με το αποδοσμένο περιεχόμενο του μπλοκ στο frontend.
Αποθήκευση μεταδεδομένων ανάρτησης
Τόσο το ACF Blocks όσο και το Blockstudio αποθηκεύουν από προεπιλογή τις τιμές των πεδίων ως χαρακτηριστικά μπλοκ στο περιεχόμενο της δημοσίευσης και όχι στα μεταδεδομένα της. Αυτό σημαίνει ότι δεν μπορείτε να αναζητήσετε τις τιμές των πεδίων με το WP_Query, εκτός αν επιλέξετε την αποθήκευση στα μεταδεδομένα.
Το ACF πρόσθεσε προαιρετική αποθήκευση στα μεταδεδομένα της δημοσίευσης για μπλοκ στο ACF PRO 6.3 μέσω του usePostMeta: true, για ένα μπλοκ ανώτατου επιπέδου ανά σελίδα. Το Blockstudio διαθέτει μηχανισμό προαιρετικής ενεργοποίησης ανά πεδίο, με χρήση της ιδιότητας storage:
{
"id": "featured",
"type": "toggle",
"label": "Featured",
"storage": {
"type": "postMeta",
"postMetaKey": "is_featured"
}
}
Το κλειδί μεταδεδομένων καταχωρίζεται αυτόματα με το show_in_rest. Αποκτήστε πρόσβαση σε αυτό από οπουδήποτε με το get_post_meta($post_id, 'is_featured', true).
Για τιμές σε ολόκληρο τον ιστότοπο (όπως σελίδες επιλογών ACF), χρησιμοποιήστε αποθήκευση επιλογών:
{
"storage": {
"type": "option",
"optionKey": "site_company_name"
}
}
Επέκταση υπαρχόντων μπλοκ
Ο κανόνας τοποθεσίας μπλοκ του ACF συνδέει ομάδες πεδίων μόνο με μπλοκ ACF· δεν προσθέτει πεδία στα βασικά μπλοκ ή σε μπλοκ τρίτων. Η λύση του ACF για βασικά μπλοκ όπως Επικεφαλίδα, Παράγραφος, Εικόνα και Κουμπί είναι το WordPress Block Bindings API, που συνδέει υπάρχοντα χαρακτηριστικά μπλοκ με τιμές πεδίων του ACF. Το Blockstudio μπορεί να προσθέσει νέα πεδία και στοιχεία ελέγχου σε οποιοδήποτε καταχωρισμένο μπλοκ μέσω αρχείων επέκτασης.
Δημιουργήστε ένα αρχείο επέκτασης στον κατάλογο blockstudio:
{
"name": "core/heading",
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "accentColor",
"type": "color",
"label": "Accent Color",
"set": [{ "attribute": "style", "value": "color: {attributes.accentColor}" }]
}
]
}
}
Η ιδιότητα set εφαρμόζει αυτόματα την τιμή του πεδίου στο HTML του μπλοκ. Χρησιμοποιήστε χαρακτήρες μπαλαντέρ για να επεκτείνετε πολλά μπλοκ ταυτόχρονα: "name": "core/*".
Λίστα ελέγχου μετεγκατάστασης
- Δημιουργήστε τον φάκελο του μπλοκ στο
theme/blockstudio/{block-name}/με ταblock.jsonκαιindex.php. - Μεταφέρετε τους ορισμούς πεδίων από την ομάδα πεδίων του μπλοκ (Local JSON,
acf_add_local_field_group()ή ενσωματωμένο πίνακαacf.fields) στον πίνακαblockstudio.attributesστοblock.json. Αλλάξτε τοnameσεid, αφαιρέστε τοkeyκαι προσαρμόστε τα ονόματα τύπων όπου χρειάζεται. - Ενημερώστε την πρόσβαση στο πρότυπο από
get_field('name')σε$a['name']. Αντικαταστήστε τους βρόχουςhave_rows()μεforeach ($a['repeater'] as $item). - Αντικαταστήστε το
get_sub_field()με άμεση πρόσβαση στον πίνακα:$item['fieldId']. - Προσθέστε το
useBlockPropsστο εξωτερικότερο στοιχείο του προτύπου σας για σωστή ενσωμάτωση στον επεξεργαστή. - Μεταφέρετε τη λογική υπό όρους από το
conditional_logicτου ACF στοconditionsτου Blockstudio, χρησιμοποιώντας αναγνωριστικά πεδίων αντί για κλειδιά πεδίων. - Προσθέστε αποθήκευση για όσα πεδία αναζητούνταν προηγουμένως μέσω του
get_post_meta()ή χρησιμοποιούνταν στοWP_Query. - Αφαιρέστε τον κώδικα καταχώρισης ACF: τις κλήσεις
register_block_type()και τα κλειδιάacfτων μπλοκ που μεταφέρθηκαν (ή τις κλήσεις τουςacf_register_block_type()), καθώς και τις ομάδες πεδίων τους, είτε βρίσκονται στο Local JSON, στοacf_add_local_field_group(), σε ενσωματωμένο πίνακαacf.fieldsή στην περιοχή διαχείρισης. - Δοκιμάστε στον επεξεργαστή για να επιβεβαιώσετε ότι τα πεδία εμφανίζονται σωστά και, στη συνέχεια, ελέγξτε το αποτέλεσμα στον ιστότοπο.