Προσαρμοσμένοι τύποι πεδίων
Οι προσαρμοσμένοι τύποι πεδίων επιτρέπουν σε ένα θέμα ή πρόσθετο να προσθέσει νέα στοιχεία ελέγχου πεδίων Blockstudio. Διαφέρουν από τα προσαρμοσμένα πεδία:
- Το
custom/{name}αναφέρεται σε μια επαναχρησιμοποιήσιμη ομάδα υπαρχόντων πεδίων. - Το
namespace/type-nameχρησιμοποιεί έναν καταχωρισμένο τύπο πεδίου με δικό του στοιχείο ελέγχου επεξεργαστή και μορφή τιμής.
Το Blockstudio παρέχει το σύστημα καταχώρισης. Το θέμα ή το πρόσθετό σας παρέχει το στοιχείο ελέγχου.
Πότε να τα χρησιμοποιήσετε
Χρησιμοποιήστε έναν προσαρμοσμένο τύπο πεδίου όταν ένα έργο χρειάζεται ένα εξειδικευμένο στοιχείο ελέγχου επεξεργασίας, το οποίο θα πρέπει να συμπεριφέρεται παντού όπως ένα εγγενές πεδίο Blockstudio:
- χαρακτηριστικά μπλοκ
- επαναχρησιμοποιήσιμες ομάδες πεδίων
custom/{name} - ομάδες, καρτέλες και επαναλήπτες
- πρότυπα PHP, Twig και Blade
- μεταδεδομένα άρθρων και αποθήκευση επιλογών
- πρότυπα επεκτάσεων, όπως το
{attributes.margin.top}
Για παράδειγμα, ένα στοιχείο ελέγχου διαστημάτων μπορεί να αποθηκεύσει ένα αντικείμενο αντί για τέσσερα ξεχωριστά πεδία κειμένου:
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "right", "bottom", "left"],
"default": {
"top": "sm",
"right": "md",
"bottom": "sm",
"left": "md"
}
}
]
}
}
Ονοματοδοσία
Τα ονόματα προσαρμοσμένων τύπων πεδίων πρέπει να είναι με πεζά γράμματα, να έχουν χώρο ονομάτων και να χρησιμοποιούν παύλες:
namespace/type-name
Έγκυρα παραδείγματα:
acme/dimensionsacme/text-optionstheme/spacing-token
Δεσμευμένοι χώροι ονομάτων:
- Το
custom/προορίζεται για επαναχρησιμοποιήσιμες ομάδες προσαρμοσμένων πεδίων. - Το
blockstudio/προορίζεται για τον πυρήνα του Blockstudio.
Τα μη έγκυρα ονόματα αγνοούνται από το φίλτρο API και απορρίπτονται από τη βοηθητική συνάρτηση API.
Καταχώριση PHP
Καταχωρίστε τα μεταδεδομένα του τύπου πεδίου στο 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() επιστρέφει true όταν η καταχώριση είναι επιτυχής και false όταν το όνομα ή ο ορισμός δεν είναι έγκυρος. Μπορείτε να καταργήσετε μια χειροκίνητη καταχώριση με το bs_unregister_field_type().
Μπορείτε επίσης να χρησιμοποιήσετε το φίλτρο API:
add_filter('blockstudio/field_types', function (array $types): array {
$types['acme/dimensions'] = [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
];
return $types;
});
Κλειδιά ορισμού
| Κλειδί | Τύπος | Περιγραφή |
|---|---|---|
attribute |
string, array, null |
WordPress τύπος γνωρίσματος. Χρησιμοποιήστε string, number, boolean, object, array ή έναν πίνακα με αυτούς τους τύπους. |
default |
mixed | Προεπιλογή επιπέδου μητρώου όταν ένα πεδίο δεν ορίζει δική του προεπιλογή. |
source |
string | WordPress προέλευση γνωρίσματος για προσαρμοσμένες περιπτώσεις σειριοποίησης. |
produces_attribute |
boolean | Ορίστε το false για στοιχεία ελέγχου μόνο για προβολή. Η προεπιλογή είναι true. |
editor_script |
string or array | Καταχωρισμένο αναγνωριστικό script ή αναγνωριστικά προς φόρτωση στον επεξεργαστή block όταν χρησιμοποιείται ο τύπος. |
editor_style |
string or array | Καταχωρισμένο αναγνωριστικό στυλ ή αναγνωριστικά προς φόρτωση στον επεξεργαστή block όταν χρησιμοποιείται ο τύπος. |
storage |
array | Τύπος τιμής αποθήκευσης και υποδείξεις σχήματος REST για μεταδεδομένα αναρτήσεων και επιλογές. |
supports |
array | Προαιρετικές σημαίες δυνατοτήτων για το δικό σας στοιχείο ελέγχου. |
translate |
boolean | Ορίστε το true όταν η τιμή είναι κείμενο προς μετάφραση από το WPML. Απαιτείται το attribute string. |
Ένας ορισμός με τιμή translate που δεν είναι boolean ή με το
translate ορισμένο σε true και ένα attribute διαφορετικό από string είναι μη έγκυρος.
Το bs_register_field_type() επιστρέφει false και το φίλτρο API τον αγνοεί.
WPML
Το wp bs wpml config δεν μπορεί να διαπιστώσει μόνο από την καταχώριση αν η τιμή
ενός προσαρμοσμένου τύπου πεδίου είναι κείμενο, οπότε παραλείπει αυτά τα πεδία και εμφανίζει μια
προειδοποίηση για το καθένα. Ορίστε το translate σε true στην καταχώριση ενός τύπου πεδίου
που αποθηκεύει απλό κείμενο, και η εντολή δηλώνει τα πεδία του όπως τα πεδία text. Ένα πεδίο μπορεί και πάλι να εξαιρεθεί με το "translate": false. Δείτε
WPMLΤεκμηρίωση.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
Καταχώριση JavaScript
Το σενάριο του επεξεργαστή καταχωρίζει το αντίστοιχο στοιχείο ελέγχου React:
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() επιστρέφει true όταν η καταχώριση γίνεται αποδεκτή. Καταργήστε μια καταχώριση από την πλευρά του προγράμματος-πελάτη με:
window.blockstudio.unregisterFieldType('acme/dimensions');
Το στοιχείο λαμβάνει τις ιδιότητες του ορισμού πεδίου, καθώς και τις εξής σταθερές ιδιότητες:
| Ιδιότητα | Περιγραφή |
|---|---|
type |
Όνομα τύπου πεδίου. |
id |
ID πεδίου. |
field |
Πλήρης ορισμός πεδίου από το block.json. |
value |
Τρέχουσα αποθηκευμένη τιμή. |
defaultValue |
Προεπιλεγμένη τιμή πεδίου. |
onChange |
Αποθηκεύει απευθείας μια νέα τιμή. |
attributes |
Τρέχοντα χαρακτηριστικά μπλοκ. |
block |
Ορισμός τρέχοντος τύπου μπλοκ. |
clientId |
Τρέχον ID μπλοκ προγράμματος-πελάτη του επεξεργαστή. |
inRepeater |
Αν το πεδίο βρίσκεται μέσα σε γραμμή επαναλήπτη. |
repeaterId |
Τρέχουσα διαδρομή επαναλήπτη, αν υπάρχει. |
disabled |
Αν το πεδίο είναι απενεργοποιημένο στον επεξεργαστή. |
Οι τιμές των προσαρμοσμένων τύπων πεδίων αποθηκεύονται απευθείας. Δεν περνούν από την κανονικοποίηση εγγενών επιλογών select, radio, color ή gradient.
Απόδοση τιμών
Οι τιμές αντικειμένων είναι διαθέσιμες όπως κάθε άλλο χαρακτηριστικό Blockstudio.
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>
Οι διαδρομές ένθετων αντικειμένων λειτουργούν επίσης σε πρότυπα επεκτάσεων:
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
Αποθήκευση
Όταν ένας προσαρμοσμένος τύπος πεδίου χρησιμοποιείται με αποθήκευση postMeta ή option, το Blockstudio χρησιμοποιεί τον καταχωρισμένο τύπο τιμής αποθήκευσης και το σχήμα REST.
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"storage": {
"type": "postMeta",
"postMetaKey": "acme_margin"
}
}
Για τιμές array και object, ορίστε το storage.rest_schema στην καταχώριση του τύπου πεδίου. Οι απόγονοι επαναλήπτη εξακολουθούν να χρησιμοποιούν αποθήκευση με βάση πίνακες, επειδή ένας επαναλήπτης αποθηκεύει γραμμές.
Συμπεριφορά εφεδρείας
Αν το PHP γνωρίζει τον τύπο πεδίου, αλλά το σενάριο του επεξεργαστή δεν καταχωρίζει αντίστοιχο στοιχείο ελέγχου, το Blockstudio διατηρεί την αποθηκευμένη τιμή και εμφανίζει μια μη επεξεργάσιμη ειδοποίηση στον επεξεργαστή. Η απόδοση στο frontend εξακολουθεί να λαμβάνει την αποθηκευμένη τιμή.
Αν ένας τύπος πεδίου δεν έχει καταχωριστεί στο PHP, το Blockstudio τον παραλείπει από τα παραγόμενα χαρακτηριστικά WordPress. Καταχωρίστε τον ορισμό PHP πριν εκτελεστεί η ανακάλυψη μπλοκ, συνήθως στο init πριν το Blockstudio δημιουργήσει μπλοκ.