Pereiti prie turinio

Salos

Blokų salos leidžia blokui naudoti įprastą Blockstudio atvaizdavimo grandinę, o konkrečiai užklausai skirtą išvestį perkelti iš pradinio HTML atsakymo.

Tai naudinga, kai puslapį reikia intensyviai talpinti į podėlį, tačiau vienas blokas vis tiek priklauso nuo esamo lankytojo, sesijos, krepšelio, teisių ar kito esamos užklausos konteksto.

Blockstudio blokai vis tiek yra dinaminiai WordPress blokai. Salos nepaverčia jų iš anksto sukompiliuotais statiniais HTML. Vietoj to, Blockstudio pakeičia tai, kas atvaizduojama per pirmąją užklausą:

  • hidratuotos salos atvaizduoja įprastą talpyklai saugią HTML ir gauna prijungimo įvykį
  • dinaminės salos pirmiausia atvaizduoja talpyklai saugų pakaitalą, tada lankytojo naršyklėje gauna tikrąją dalį

Režimai

Hidratuotos salos

Naudokite hidratuotą salą, kai serverio išvestį saugu talpinti į podėlį, o blokui reikia tik sąsajos prijungimo signalo.

JSON
{
  "name": "acme/tabs",
  "blockstudio": {
    "island": "hydrate"
  }
}

Visa bloko HTML yra pradiniame atsakyme. Salos vykdymo aplinka dėl jos nesiunčia REST užklausos. Ji išsiunčia blockstudio:island:hydrate žymos elementui, kad sąsajos kodas galėtų prijungti elgseną.

Dinaminės salos

Naudokite dinaminę salą, kai tikrąją bloko išvestį reikia atvaizduoti lankytojo užklausos kontekste.

JSON
{
  "name": "acme/cart-count",
  "blockstudio": {
    "island": "dynamic"
  }
}

Pradiniame atsakyme yra tik pakaitalas. Naršyklė sugrupuoja visas paruoštas dinamines salas į vieną užklausą adresu:

Text
POST /wp-json/blockstudio/v1/island/render

Galinis punktas atvaizduoja tik registruotus Blockstudio blokus, kurie yra dinaminiai ir kurių blockstudio.island.mode nustatytas į dynamic.

Konfigūracija

island reikšmė gali būti trumpinys arba objektas.

JSON
{
  "blockstudio": {
    "island": true
  }
}

true ir "hydrate" reiškia hidratuotą režimą. "dynamic" reiškia dinaminį režimą.

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "tag": "section",
      "attributes": ["productId", "variant"],
      "placeholder": "cart-placeholder.php",
      "loading": "visible",
      "event": "cart:updated",
      "cache": {
        "ttl": 60,
        "per": "user"
      }
    }
  }
}
Savybė Tipas Numatytoji reikšmė Aprašymas
mode "hydrate" arba "dynamic" "hydrate" Salos režimas.
tag string "div" Žymeklio apgaubiamoji žyma.
attributes string[] visi bloko atributai Į dinaminio fragmento užklausas siunčiamas atributų leidžiamasis sąrašas.
placeholder string aptinkamas automatiškai Santykinis vietaženklių šablono kelias.
loading "eager" arba "visible" "eager" Kada vykdymo aplinka turėtų gauti dinaminę salą.
event string nenustatyta Lango įvykio pavadinimas, kuris atnaujina dinaminę salą.
context boolean false Pasirašo ir atkuria užklausto puslapio įrašo ID bei tipą dinaminiams fragmentams.
cache boolean arba object false Pasirenkama fragmentų talpyklos politika.

Puslapio kontekstas

Dinaminiai fragmentai paprastai atvaizduojami nepriklausomai nuo puslapio apvalkalo. Įtraukite puslapio tapatybę, jei jūsų blokas naudoja konkretaus puslapio nustatymus ar susijusį turinį:

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "context": true,
      "cache": { "ttl": 60, "per": "global" }
    }
  }
}

Žymeklyje yra užklausto puslapio postId ir postType, įrašytų į data-bs-island-context. Abi reikšmės pasirašomos naudojant bloko pavadinimą, leidžiamuosius atributus ir aptarnaujančios svetainės paslaptį. Jų negalima pakeisti ar pridėti prie užklausos nepanaikinus parašo galiojimo. Vykdymo aplinka siunčia jas kartu su esama paketine fragmentų užklausa, įskaitant matomus ir įvykių inicijuojamus atnaujinimus. Tai taip pat veikia su bs_render_block(), bs_block() ir blokų žymomis.

Atvaizduojant fragmentą, $block['postId'], $block['postType'], get_the_ID() ir get_queried_object_id() nurodo tą puslapį. Po to atkuriamos WordPress užklausos ir įrašo globalios reikšmės, taip pat ir įvykus atvaizdavimo išimčiai. Tai yra užklaustas puslapis, o ne elementas Query Loop viduje. Savavališki URL parametrai neatkuriami, taip pat neatkuriamas pradinis užklausos URL. Jei reikia puslapio HTML kanoninio URL, naudokite get_permalink($block['postId']). Archyvai ir atvaizdavimai be užklausto įrašo puslapio tapatybės nesiunčia.

Prieš tikrindamas fragmentų talpyklą, galinis punktas patikrina, ar puslapis vis dar egzistuoja, ar jo įrašo tipas atitinka pasirašytąjį ir ar dabartinis lankytojas gali jį skaityti. Galiojantis parašas nepanaikina privačių įrašų ar apsaugos slaptažodžiu, salos tinkamumo, atributų leidžiamųjų sąrašų ar jūsų bloko leidimų patikrų. Kai puslapio tapatybė pateikiama, ji visada įtraukiama į fragmento talpyklos raktą, todėl tas pats blokas su tais pačiais atributais skirtinguose puslapiuose niekada nesidalija fragmentu. Naudokite per: "user" arba išjunkite fragmentų talpyklą, jei išvestis priklauso ir nuo lankytojo.

Jei context praleistas arba false, esami žymekliai ir nuo konteksto nepriklausanti elgsena lieka nepakitę. Nedėkite konfidencialių duomenų į viešą žymeklį.

Dinaminiai pakaitalai

Dinaminės salos turi atvaizduoti pakaitalą, kurį saugu naudoti bendroje viso puslapio talpykloje. Pakaitalo šakoje neįtraukite konkrečiam lankytojui skirtų duomenų.

Blockstudio pakaitalų ieško tokia tvarka:

  1. aiškiai nurodytas kelias island.placeholder
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. įprastas šablonas su pakaitalų vėliavėlėmis
PHP
<div class="cart-count-placeholder">
  Loading cart...
</div>

Jei pakaitalo failo nėra, įprastame šablone naudokite šablono vėliavėles:

PHP
<?php if ( $isIslandPlaceholder ) : ?>
  <div class="cart-count-placeholder">Loading cart...</div>
<?php else : ?>
  <div class="cart-count">
    <?php echo esc_html( acme_cart_count() ); ?>
  </div>
<?php endif; ?>

Tos pačios reikšmės pasiekiamos šablonuose PHP, Twig ir Blade:

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

islandPhase yra "normal", "hydrate", "placeholder" arba "fragment".

Vykdymo elgsena

Blockstudio įterpia salos vykdymo aplinką tik tada, kai atvaizduotame puslapyje yra salos žyma. Puslapiuose be salų neįkeliama papildoma salos JavaScript.

Dinaminėms saloms vykdymo aplinka:

  1. surenka visas paruoštas žymas
  2. pašalina pasikartojančias identiškas bloko pavadinimo, atributų ir parašo poras
  3. siunčia vieną sugrupuotą REST užklausą
  4. pakeičia kiekvieną pakaitalą grąžinta dalimi
  5. išsiunčia blockstudio:island:rendered
  6. išsiunčia blockstudio:island:hydrate

loading: "eager" salos atvaizduojamos iškart, kai paleidžiama vykdymo aplinka. loading: "visible" salos laukia IntersectionObserver. Jei kelios matomos salos vienu metu patenka į peržiūros sritį, jų užklausos sugrupuojamos į vieną.

event atnaujina salą, kai įvyksta nurodytas lango įvykis:

JavaScript
window.dispatchEvent(new Event('cart:updated'));

Nesėkmės atveju pakaitalas paliekamas vietoje ir išsiunčiamas blockstudio:island:error.

Dalių galinis punktas

Salos galinis punktas yra viešas, tačiau tai nėra bendros paskirties blokų atvaizdavimo API.

Kiekviena žyma turi:

  • bloko pavadinimą
  • leidžiamų atributų sąrašą
  • serverio sugeneruotą parašą

Galinis punktas atvaizduoja tik tada, kai:

  • blokas yra registruotas
  • blokas yra dinaminis WordPress blokas
  • blokas pažymėtas kaip dinaminė Blockstudio sala
  • gaunami atributai atitinka bloko schemą ir salos leidžiamų atributų sąrašą
  • parašas atitinka normalizuotą bloko pavadinimą ir atributus

Parašai generuojami atvaizdavimo metu aptarnaujančioje WordPress svetainėje, naudojant tos svetainės druskas ir salos duomenis. Jie neeksportuojami ir neįrašomi į temą.

Galinio punkto atsakymai pažymimi kaip netinkami talpinti į podėlį. Jei norite talpinti dalis į podėlį, naudokite island.cache.

Dalių talpinimas į podėlį

Dinaminės dalys pagal numatytuosius nustatymus nėra talpinamos į podėlį.

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "cache": true
    }
  }
}

true naudoja trumpalaikę visuotinę talpyklą. Aiškiai kontrolei naudokite objekto formą:

JSON
{
  "cache": {
    "ttl": 120,
    "per": "user"
  }
}

per: "global" naudoja tą pačią talpyklos iškarpą, kai sutampa blokas, atributai ir pasirenkamas puslapio kontekstas. per: "user" talpyklos įrašą diferencijuoja pagal dabartinio WordPress naudotojo ID.

Atvaizdavimas programiškai

Salos veikia visur, kur atvaizduojami Blockstudio blokai:

PHP
bs_render_block([
  'name' => 'acme/cart-count',
  'data' => ['productId' => 42],
]);

echo bs_block([
  'name' => 'acme/cart-count',
  'data' => ['productId' => 42],
]);

Jos taip pat veikia per blokų žymas:

HTML
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />

Pradinė išvestis vis tiek yra salos žyma ir pakaitalas, o vykdymo aplinka įterpiama, kai atvaizduotame atsakyme yra ta žyma.

PHP API

PHP
Blockstudio\Islands::is_island('acme/cart-count');
Blockstudio\Islands::mode('acme/cart-count');
Blockstudio\Islands::registered();
Blockstudio\Islands::marker('acme/cart-count', $attributes, $html);

marker() tikrina bloko metaduomenis. Dinaminės žymos sukuriamos tik registruotiems dinaminiams Blockstudio blokams, kurių island.mode nustatytas į dynamic.

Kabliukai

Aptikimas ir žymėjimas:

PHP
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder

Galinis punktas ir atvaizdavimas:

PHP
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment

blockstudio/islands/max_per_request keičia didžiausią dinaminių salų skaičių, kurį priima viena sugrupuota galinio punkto užklausa. Numatytoji reikšmė yra 50.

Vykdymo aplinkos konfigūracija:

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

Parašai:

PHP
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature

Gyvavimo ciklo veiksmai:

PHP
blockstudio/islands/registered
blockstudio/islands/rendered

Kada salų nenaudoti

Nenaudokite dinaminės salos SEO svarbiam turiniui. Dinaminių salų dalys nėra pradiniame HTML ir nėra skirtos indeksuoti.

Kai turinį saugu talpinti į podėlį ir jis turi būti matomas tikrinimo robotams, naudokite įprastą atvaizdavimą arba hidratuotą salą. Dinaminę salą naudokite tik turiniui, kuris gali būti pateiktas įkėlus puslapio karkasą, pavyzdžiui, paskyros UI, krepšelio būsenai, suasmenintoms rekomendacijoms ar tik leidimą turintiems naudotojams rodomiems valdikliams.