Pereiti prie turinio

Tinkinti laukai

Tinkinti laukai leidžia apibrėžti pakartotinai naudojamas laukų grupes, kurias galima nurodyti keliuose blokuose. Laikykite juos laukų šablonais: apibrėžkite vieną kartą ir naudokite visur.

Tinkinti laukai nėra tas pats, kas tinkinti laukų tipai. Naudokite custom/{name} pakartotinai naudojamoms esamų laukų grupėms. Naudokite vardų sritį turintį tinkintą laukų tipą, pvz., acme/dimensions, kai tema arba papildinys registruoja naują redaktoriaus valdiklį ir reikšmės struktūrą.

Registravimas failų sistemoje

Savo blockstudio katalogo fields/ kataloge sukurkite failą field.json:

Kodas
theme/
└── blockstudio/
    └── fields/
        └── hero/
            └── field.json
JSON
{
  "$schema": "https://blockstudio.dev/schema/field",
  "name": "hero",
  "title": "Hero Section",
  "attributes": [
    {
      "id": "heading",
      "type": "text",
      "label": "Heading",
      "default": "Hello World"
    },
    { "id": "description", "type": "textarea", "label": "Description" },
    { "id": "enabled", "type": "toggle", "label": "Enabled" }
  ]
}

Registravimas naudojant PHP filtrą

Tinkintus laukus registruokite programiškai naudodami filtrą blockstudio/fields:

PHP
add_filter('blockstudio/fields', function ($fields) {
    $fields['cta'] = [
        'title'      => 'Call to Action',
        'attributes' => [
            ['id' => 'text', 'type' => 'text', 'label' => 'Button Text'],
            ['id' => 'url', 'type' => 'text', 'label' => 'URL'],
        ],
    ];
    return $fields;
});

Naudojimas su block.json

Nurodykite tinkintą lauką naudodami tipą custom/{name}:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero" }]
  }
}

Taip įterpiami laukai, apibrėžti tinkinto lauko apraše. Įterptieji laukai naudoja pradinius ID (heading, description, enabled).

Tinkintuose laukuose taip pat galima pakartotinai naudoti visas grupių apibrėžtis:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "title": "Header",
      "attributes": [
        { "id": "kicker", "type": "text", "label": "Kicker" },
        { "id": "title", "type": "text", "label": "Title" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/section-header" }]
  }
}

Grupės antriniai elementai saugomi kaip section-header_kicker, section-header_title ir t. t. Šablonuose naudokite bs_get_group(), kad išskleistumėte juos į tvarkingą grupės objektą.

ID struktūra

Naudokite idStructure laukų ID prefiksui pridėti arba jiems pakeisti. Vietos rezervavimo ženklas {id} pakeičiamas pradiniu lauko ID:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
  }
}

Taip sukuriami laukai su šiais ID: hero_heading, hero_description, hero_enabled.

Pakeitimai

Tinkinkite atskirus laukus pagal egzempliorių naudodami overrides. Raktai yra pradiniai lauko ID iš aprašo:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "custom/hero",
        "idStructure": "hero_{id}",
        "overrides": {
          "heading": { "default": "Welcome", "label": "Title" },
          "enabled": { "id": "active" }
        }
      }
    ]
  }
}

Perrašytos savybės sujungiamos su pradiniu lauko aprašu. id perrašymas apeina šabloną idStructure. Aukščiau pateiktame pavyzdyje enabled tampa active, o ne hero_enabled.

Sujungimas vyksta tik vienu lygiu: perrašyta savybė pakeičia visą pradinę savybę. options perrašymas reiškia visą parinkčių sąrašą, o ne jo papildymą; tas pats galioja conditions ir grupės attributes. Nuorodos sąlygos vis tiek pridedamos vėliau.

JSON
{
  "type": "custom/background",
  "overrides": {
    "background": {
      "options": [
        { "value": "white", "label": "White" },
        { "value": "grey", "label": "Grey" }
      ]
    }
  }
}

Šiame bloke siūlomos tik balta ir pilka spalvos, kad ir kiek parinkčių būtų nurodyta apraše.

Sąlygos

Sąlygos tinkintų laukų apibrėžtyse automatiškai perrašomos, kai taikomas idStructure. Laukas, kurio rodymas priklauso nuo gretimo lauko sąlygos, veiks ir po išskleidimo.

JSON
{
  "name": "font-size",
  "attributes": [
    { "id": "enable", "type": "toggle", "label": "Modify font size" },
    {
      "id": "min",
      "type": "number",
      "label": "Min Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    },
    {
      "id": "max",
      "type": "number",
      "label": "Max Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    }
  ]
}
JSON
{ "type": "custom/font-size", "idStructure": "title_font_{id}" }

Blockstudio išskleidžia tai į title_font_enable, title_font_min, title_font_max ir perrašo sąlygas, kad jos nurodytų title_font_enable, o ne enable. Perjungikliai veikia lygiai taip, tarsi laukai būtų apibrėžti tiesiogiai.

Nuorodos lygmens sąlygos

Prie nuorodos pridėkite conditions, kad jos būtų taikomos kiekvienam išskleistam laukui. Tai naudinga, kai norite paslėpti visą grupę pagal išorinį perjungiklį:

JSON
{
  "type": "custom/font-size",
  "idStructure": "subtitle_font_{id}",
  "conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}

Šios sąlygos sujungiamos su sąlygomis, jau apibrėžtomis lauko apraše. Sąlygų ID taip pat perrašomi naudojant idStructure.

Keli tinkinti laukai

Viename bloke galite naudoti kelis tinkintus laukus kartu su įprastais laukais:

JSON
{
  "blockstudio": {
    "attributes": [
      { "id": "intro", "type": "text", "label": "Intro" },
      { "type": "custom/hero", "idStructure": "hero_{id}" },
      { "type": "custom/cta", "idStructure": "cta_{id}" }
    ]
  }
}

Įdėjimas

Tinkinti laukai veikia grupėse, kortelėse ir kartotuvuose:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "group",
        "id": "content",
        "title": "Content",
        "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
      }
    ]
  }
}

Papildomi aptikimo keliai

Naudokite filtrą blockstudio/fields/paths, kad pridėtumėte papildomų katalogų laukams aptikti:

PHP
add_filter('blockstudio/fields/paths', function ($paths) {
    $paths[] = get_stylesheet_directory() . '/blockstudio/fields';
    return $paths;
});

Statinė analizė

blockstudio/phpstan paketas išplečia failuose apibrėžtas custom/* nuorodas, tikrindamas PHP, Twig, Blade, blokų žymas ir išvedamas atributų struktūras. Išplėtimas taiko tas pačias įdėjimo, idStructure ir overrides taisykles, kurios aprašytos aukščiau.

Jei apibrėžtys yra už analizuojamo projekto ribų, pridėkite bibliotekos katalogą prie blockstudioScanRoots faile phpstan.neon. Laukai, registruoti tik naudojant filtrą blockstudio/fields PHP, egzistuoja vykdymo metu ir negali būti nustatyti atliekant statinę analizę.