Suasmeninti fragmentai spartinančiuosiuose puslapiuose
Statiniame podėlyje saugomas puslapis visiems pateikiamas vienodas. Toks ir yra podėliavimo tikslas, bet kartu tai ir problema: antraštėje norisi pasisveikinti su prisijungusiu klientu „Sveiki, Ada“, o krepšelio piktogramoje rodyti tris prekes. Jei šablonas parenka turinį pagal dabartinį naudotoją, podėlyje arba visiems išsaugomas vieno lankytojo pasisveikinimas, arba puslapio tenka visai nepodėliuoti.
Blockstudio dinaminės salos atskiria šiuos du dalykus. Podėliuojamame HTML yra podėliui saugi vietos žymė. Įkėlus puslapį, nedidelė vykdymo aplinka paprašo WordPress suasmeninto fragmento paties lankytojo užklausos kontekste ir juo pakeičia vietos žymę. Puslapį galima podėliuoti, o tiesiogiai atnaujinamas tik fragmentas.
Šiame vadove sukuriamos dvi salos: pasisveikinimas ir krepšelio prekių skaičius. Taip pat aptariama, kas yra podėliuojamame puslapyje, kaip atrodo fragmento užklausa ir kaip galinis taškas nustato lankytojo tapatybę. Vadovas papildo temą Pateikimas WordPress kaip statinio HTML.
Kaip veikia dinaminė sala
- Blokas atvaizduoja savo vietos žymę žymeklio elemente. Žymeklyje yra bloko pavadinimas, leidžiamų atributų sąrašas ir serverio sugeneruotas parašas.
- Kadangi atvaizduojamame puslapyje yra žymeklis, Blockstudio įterpia salos vykdymo aplinką. Puslapiuose be salų salos JavaScript neįkeliama.
- Vykdymo aplinka surenka paruoštus žymeklius ir siunčia vieną grupinę
POSTį/wp-json/blockstudio/v1/island/render. - Galinis taškas patikrina kiekvieną parašą, atvaizduoja bloką lankytojo užklausos kontekste ir grąžina fragmentus.
- Vykdymo aplinka pakeičia kiekvieną vietos žymę ir išsiunčia įvykius.
Blokų redaktoriuje blokas atvaizduojamas įprastai, be vietos žymės.
1 veiksmas: pasisveikinimo blokas
Sukurkite bloką iš trijų failų:
blocks/
└── greeting/
├── block.json
├── placeholder.php
└── index.php
{
"apiVersion": 3,
"name": "acme/greeting",
"title": "Greeting",
"category": "widgets",
"icon": "admin-users",
"description": "Account link that greets signed-in visitors.",
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "span",
"attributes": ["guestLabel"],
"cache": {
"ttl": 300,
"per": "user"
}
},
"attributes": [
{ "id": "guestLabel", "type": "text", "label": "Guest label", "default": "Sign in" }
]
}
}
mode: "dynamic" leidžia šiam blokui veikti kaip salai, siunčiančiai fragmento užklausą.
tag nustato žymeklio elementą, todėl salą galima įterpti į navigacijos juostą. attributes yra blokų atributų leidžiamų reikšmių sąrašas, perduodamas su fragmento užklausa; kas į jį neįtraukta, nesiunčiama ir nepasirašoma. cache aptariama toliau.
Podėliuojamame puslapyje pateikiama vietos žymė. Ji turi būti saugi rodyti kiekvienam lankytojui, todėl joje negali būti naudotojo duomenų. Nuoroda „Paskyra“ tinka visiems:
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">Account</a>
Pagrindinis šablonas atvaizduoja tikrąjį fragmentą:
<?php
$user = wp_get_current_user();
?>
<?php if ( $user->exists() ) : ?>
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">
<?php echo esc_html( sprintf( 'Hi, %s', $user->display_name ) ); ?>
</a>
<?php else : ?>
<a href="<?php echo esc_url( wp_login_url() ); ?>">
<?php echo esc_html( $a['guestLabel'] ); ?>
</a>
<?php endif; ?>
Čia galima pasirinkti turinį pagal dabartinį naudotoją: šis šablonas vykdomas tik fragmento užklausai, o ne podėliuojamam puslapiui.
Įdėkite jį ten, kur atvaizduojama antraštė:
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>
Tinka ir blokų žymos: <bs:acme-greeting /> arba
<block name="acme/greeting" />.
2 veiksmas: kas yra podėliuojamame puslapyje
Atvaizduotas serveryje blokas sukuria tik žymeklį ir vietos žymę:
<span data-bs-island="acme/greeting" data-bs-island-mode="dynamic" data-bs-island-phase="placeholder" data-bs-island-props="{"guestLabel":"Sign in"}" data-bs-island-signature="a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043" data-bs-island-loading="eager"><!--blockstudio/acme/greeting--><a href="https://example.com/account/">Account</a>
</span>
Atvaizduokite bloką vieną kartą kaip anoniminis lankytojas ir vieną kartą kaip prisijungęs naudotojas. Abi eilutės bus visiškai vienodos baitas į baitą. Būtent to reikia statiniam išankstiniam atvaizdavimui, kai įjungtas serveLoggedIn: nesvarbu, kas inicijavo atvaizdavimą, išsaugotas dokumentas yra vienodas ir jame negali atsidurti asmeninė informacija.
3 veiksmas: fragmento užklausa
Vykdymo aplinka siunčia visų paruoštų salų duomenis viena užklausa:
{
"islands": [
{
"clientId": "a1",
"name": "acme/greeting",
"attributes": {
"guestLabel": "Sign in"
},
"signature": "a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043"
}
]
}
Atsakymo įrašai susiejami pagal clientId. Prisijungusio lankytojo atveju:
{
"a1": "<!--blockstudio/acme/greeting--> <a href=\"https://example.com/account/\">\n Hi, Ada </a>\n"
}
Nepatikrinimo nepraėjęs įrašas grąžinamas kaip klaidos kodas, o ne HTML, ir dėl to likusi grupinė užklausa nesutrinka. Čia antrojo įrašo guestLabel buvo pakeistas be atitinkamo parašo, o trečiajame nurodytas blokas, kuris nėra dinaminė sala:
{
"a1": "<!--blockstudio/acme/greeting--> <a href=\"https://example.com/wp-login.php\">\n Sign in </a>\n",
"a2": {
"error": "blockstudio_island_invalid_signature"
},
"a3": {
"error": "blockstudio_island_not_allowed"
}
}
Kiekviename atsakyme yra Cache-Control: no-store, no-cache, must-revalidate, max-age=0,
Pragma: no-cache ir X-Robots-Tag: noindex. Galinis taškas veikia po /wp-json, kurį statinis išankstinis atvaizdavimas visada apeina. Todėl nei kilmės serverio podėlis, nei kilmės serverio antraštes paisantis CDN fragmento neišsaugos.
Kas yra lankytojas
Vykdymo aplinka siunčia užklausą su credentials: 'same-origin', todėl naršyklė prideda prisijungimo WordPress slapuką. WordPress REST API paprastai nepaiso autentifikavimo pagal slapuką be vienkartinio rakto, o jo negalima įtraukti į podėliuojamą puslapį. Salos galinis taškas tai tvarko pats: tos pačios kilmės naršyklės užklausai jis patikrina logged_in slapuką ir prieš atvaizduodamas atkuria naudotojo sesiją.
Ta pati kilmė nustatoma pagal Sec-Fetch-Site antraštę ir, jei yra, Origin antraštę, palyginant su home_url(). Iš kitos kilmės gauta užklausa, kurioje pasitaiko slapukas, atvaizduojama kaip anoniminio lankytojo, todėl kita svetainė niekada negauna asmeninio lankytojo fragmento. Praktiškai:
| Užklausa | Kaip atvaizduojama |
|---|---|
| Tos pačios kilmės gavimo užklausa su galiojančiu prisijungimo slapuku | kaip prisijungusio naudotojo |
| Kitos kilmės užklausa su tuo pačiu slapuku | anonimiškai |
| Nėra slapuko | anonimiškai |
Kuris puslapis tai?
Pridėkite "context": true prie blockstudio.island, kai fragmentui reikia jo puslapio tapatybės. Tada žymeklis greta atributų pasirašo užklausto puslapio įrašo ID ir įrašo tipą. Fragmente $block['postId'], $block['postType'], get_the_ID() ir get_queried_object_id() nurodo tą puslapį. Užklausos ciklo viduje tai vis tiek reiškia išorinį užklaustą puslapį, o ne ciklo elementą.
Puslapio kontekstas pasirenkamas ir taip pat įtraukiamas į fragmentų podėlio raktą. Galinis taškas dar kartą patikrina prieigą net ir prie podėlyje esančių fragmentų, todėl pasirašytas žymeklis neatskleidžia puslapio, kuris vėliau tapo privačiu arba apsaugotu slaptažodžiu. Konfigūraciją ir saugumo informaciją rasite Puslapio kontekstas. Savavališki URL ar užklausos parametrai neatkuriami.
4 veiksmas: savaime atsinaujinantis krepšelio prekių skaičius
Antroji sala parodo kitą vietos žymės stilių ir dvi vykdymo aplinkos parinktis. Vietoj atskiro vietos žymės failo šablonas tikrina $isIslandPlaceholder:
{
"apiVersion": 3,
"name": "acme/cart-count",
"title": "Cart Count",
"category": "widgets",
"icon": "cart",
"description": "Number of items in the visitor's cart.",
"blockstudio": {
"island": {
"mode": "dynamic",
"loading": "visible",
"event": "acme:cart-updated"
},
"attributes": []
}
}
<?php
$count = (int) apply_filters( 'acme/cart_count', 0 );
?>
<?php if ( $isIslandPlaceholder ) : ?>
<a href="/cart/" class="cart-count">Cart</a>
<?php else : ?>
<a href="/cart/" class="cart-count">
Cart <span class="cart-count__badge"><?php echo esc_html( (string) $count ); ?></span>
</a>
<?php endif; ?>
Visose šablonų kalbose naudojamos tos pačios vėliavėlės: isIsland,
isIslandPlaceholder, isIslandFragment ir islandPhase ("normal",
"hydrate", "placeholder" arba "fragment"). Čia prekių skaičius gaunamas iš acme/cart_count filtro, kurio reikšmę nustato jūsų el. prekybos kodas. Kai filtras grąžina 3, galinis taškas atsako:
{"c1":"<!--blockstudio/acme/cart-count--> <a href=\"/cart/\" class=\"cart-count\">\n Cart <span class=\"cart-count__badge\">3</span>\n </a>\n"}
loading: "visible" atideda užklausą, kol žymeklis patenka į matymo sritį, naudodama IntersectionObserver. Vienu metu pasirodžiusios matomos salos vis tiek siunčiamos viena užklausa. event nurodo lango įvykį, kurį suaktyvinus sala gaunama iš naujo, todėl po įdėjimo į krepšelį jūsų scenarijui tereikia apie tai pranešti:
window.dispatchEvent(new Event('acme:cart-updated'));
Reagavimas išorinės sąsajos kode
Įvykiai sklinda nuo žymeklio, todėl vienas klausytojas ties document apima visas salas. event.detail.name nurodo bloko pavadinimą:
document.addEventListener('blockstudio:island:rendered', (event) => {
if (event.detail.name !== 'acme/cart-count') return;
event.target.querySelector('.cart-count__badge')?.classList.add('is-fresh');
});
document.addEventListener('blockstudio:island:error', (event) => {
console.warn('Island failed', event.detail.name, event.detail.error);
});
Pakeitus turinį, vykdymo aplinka iškviečia blockstudio:island:rendered, tada blockstudio:island:hydrate. Jei nepavyksta, vietos rezervavimo žymeklis lieka vietoje ir suveikia blockstudio:island:error. Hidruotos salos ("island": "hydrate") visai nepradeda užklausos: visas jų HTML jau yra puslapyje, o jos gauna tik įvykį hydrate. Tai tinka talpyklai saugiems interaktyviems blokams, pavyzdžiui, skirtukams.
Fragmentų talpyklos naudojimas
Pagal numatytuosius nustatymus fragmentai atvaizduojami su kiekviena užklausa. Aukščiau pateiktame pasisveikinimo pavyzdyje įjungta trumpalaikė talpykla:
{
"cache": {
"ttl": 300,
"per": "user"
}
}
per: "user" atskiria talpykloje saugomus fragmentus pagal WordPress naudotojo ID, o anoniminės užklausos pagal šį parametrą niekada nesaugomos talpykloje, todėl du anoniminiai lankytojai negali bendrinti įrašo, skirto konkrečiam naudotojui. per: "global" bendrina tą patį fragmentą, kai sutampa blokas ir jo atributai. Tai tinka dinamiškam, bet neasmeniniam turiniui, pavyzdžiui, atsargų kiekiui. ttl numatytoji trukmė yra 60 sekundžių, o cache: true yra 60 sekundžių visuotinio galiojimo talpykla.
Saugumo modelis
Galinis punktas yra viešas, bet tai nėra bendrosios paskirties blokų atvaizdavimo priemonė. Įrašas atvaizduojamas tik tada, kai tenkinamos visos šios sąlygos:
- blokas užregistruotas, dinaminis, o
island.modenustatytas įdynamic - parašas atitinka bloko pavadinimą ir po filtravimo likusius atributus: tik raktus, esančius ir bloko schemoje, ir salos leidžiamų elementų sąraše
Parašas yra HMAC-SHA256, apskaičiuotas pagal normalizuotą bloko pavadinimą ir atributus, naudojant svetainės, kurioje jis pateikiamas, auth druską. Parašai sukuriami atvaizdavimo metu toje svetainėje ir niekada neįrašomi į temą. Iš to kyla dvi pasekmės. Staging aplinkoje atvaizduotas dokumentas turi staging parašus, todėl dokumentus reikia atvaizduoti svetainėje, kuri juos pateiks. Pasukus WordPress druskas, visi saugomuose dokumentuose esantys parašai tampa negaliojantys, todėl pasukę druską išvalykite statinio išankstinio atvaizdavimo talpyklą.
Viena užklausa priima iki 50 salų; jei jų daugiau, grąžinamas HTTP 413. Ribą pakeiskite naudodami blockstudio/islands/max_per_request. Parašų kabliai (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) skirti prieglobos sistemoms, kurioms reikia kitokios schemos.
Kada salos nenaudoti
Fragmentų nėra pradiniame HTML, todėl tikrinimo robotai jų nemato. Su SEO susijusį turinį palikite įprastame atvaizdavime. Dinamines salas naudokite turiniui, kuris gali būti pateiktas po puslapio karkaso: paskyros nuorodoms, krepšelio būsenai, rekomendacijoms ir prieigos leidimais valdomiems valdikliams. Kai visas puslapis yra asmeninis, pavyzdžiui, paskyros skydelis, vietoj to nurodykite jo kelią dynamicPaths ir atvaizduokite puslapį tiesiogiai.
Tolesni veiksmai
- Salų žinynas: visos parinktys, vietos rezervavimo reikšmių paieškos tvarka, PHP API ir kabliai.
- Statinių WordPress failų pateikimasHTML: talpykla, kuriai skirtos šios salos.
- Statinio išankstinio atvaizdavimo žinynas:
serveLoggedIn, dinaminiai keliai ir ankstyvas pateikimas. - Interaktyvūs komponentai: kliento pusės elgsena blokams, kuriems reikia daugiau nei prijungimo įvykio.