
# Drobė

Drobėje pateikiama sumažinto mastelio Figma tipo visų Blockstudio valdomų puslapių apžvalga. Kiekvienas puslapis atvaizduojamas kaip veikianti „iframe“ piešimo sritis vienoje horizontalioje eilutėje. Slinkite dviem pirštais jutikliniame kilimėlyje, o priartinkite gnybdami arba slinkdami laikydami Ctrl.

## Suaktyvinimas

Drobė pasiekiama kaip paslėptas administravimo puslapis. Eikite adresu:

```
/wp-admin/admin.php?page=blockstudio-canvas
```

Puslapis pasiekiamas tik tada, kai `dev.canvas.enabled` yra `true`, o dabartinis naudotojas turi `edit_posts` galimybę.

## Nustatymai

Įjunkite drobę ir sukonfigūruokite jos veikimą temos `blockstudio.json`:

```json title="blockstudio.json"
{
  "dev": {
    "canvas": {
      "enabled": true,
      "adminBar": false
    }
  }
}
```

| Savybė | Tipas | Numatytoji reikšmė | Aprašymas |
|----------|------|---------|-------------|
| `enabled` | `boolean` | `false` | Įjungti drobės funkciją. |
| `adminBar` | `boolean` | `true` | Rodyti WordPress administravimo juostą piešimo sričių „iframe“ languose. Nustatykite `false`, jei norite švaresnės peržiūros. |

Abu nustatymai taip pat pasiekiami kaip filtrai:

```php
add_filter('blockstudio/settings/dev/canvas/enabled', '__return_true');
add_filter('blockstudio/settings/dev/canvas/admin_bar', '__return_false');
```

## Rodiniai

Perjunkite rodinius naudodami išskleidžiamąjį meniu viršutiniame dešiniajame kampe.

- **Puslapiai**: visi Blockstudio valdomi puslapiai, rodomi kaip viso pločio piešimo sritys vienoje eilutėje.
- **Blokai**: visi registruoti Blockstudio blokai tinklelyje; kiekvienas atvaizduojamas su numatytosiomis atributų reikšmėmis.

## Viešasis katalogas ir dokumentų API

`Canvas` pateikia versijuotą, vartotojui neutralų PHP kontraktą įrankiams, kuriems reikia to paties registruoto turinio, tačiau jie nenori iš naujo kurti Blockstudio aptikimo ar atvaizdavimo logikos:

```php
use Blockstudio\Canvas;

$all = Canvas::inventory();

$changed = Canvas::inventory([
  'blocks' => ['theme/hero'],
  'pages' => ['about'],
]);

$documents = Canvas::documents([
  'patterns' => ['theme/featured'],
  'templates' => ['front-page'],
]);
```

Dabartinė versija pasiekiama kaip `Canvas::SCHEMA_VERSION`. Katalogo rezultatuose pateikiama:

- `inventory`: normalizuoti `pages`, `blocks`, `patterns`, `templates`, `parts` ir viešosios `ui` šeimos pavyzdžiai
- `order`: stabili skirtingų tipų rodymo tvarka
- `sources`: tikslūs pasirinkti šaltinio keliai su kiekvieno įrašo kilmės duomenimis; puslapio įrašo `source` yra jo stabili šaltinio tapatybė, o `path` – fizinio atvaizdavimo šablono kelias
- `warnings` ir `errors`: struktūruotos problemos, o ne sugeneruota išvestis
- `deleted`: prašyti identifikatoriai, kurių nebėra
- `selection`: normalizuotas pasirinkimas ir informacija, ar jis buvo tikslinis

`Canvas::documents()` prie kiekvieno pasirinkto įrašo prideda po visą atvaizdavimo dokumentą. Kiekviename dokumente yra jo turinys, surinktas HTML, nuo priklausomybių uždaras blokų pavadinimų sąrašas ir tikslūs CSS, JavaScript, moduliai, interaktyvumo įkrovos kodas, sujungti UI globalieji objektai bei Tailwind išvestis. Puslapių dokumentuose naudojamas semantinis `<main>` turinio apvalkalas; iškvietėjai gali jį pakeisti arba išjungti bendromis atvaizdavimo dokumento parinktimis. Kiekvienas pasirinktas puslapis atvaizduojamas atskirame atkurtame svetainės priekinės dalies WordPress kontekste, todėl užklausų sąlygos, body klasės filtrai, trumpieji kodai, maketai, peradresavimai ir `wp_enqueue_scripts` iškvietimai veikia to puslapio, o ne administravimo ar REST užklausos, kurios prašė Canvas rezultato, kontekste. Iškvietėjo pateiktos body klasės sujungiamos su puslapio kontekstinėmis klasėmis, o priekinės dalies įkėlimo registrai izoliuojami kiekvienam dokumentui. Canvas šiuos gyvavimo ciklo iškvietimus nustato pagal viešus WordPress funkcijų pavadinimus, todėl kontekstas išsaugomas ir tada, kai Blockstudio įkeliamas per Composer arba perkeltą programos vardų sritį.

### Tikslaus pasirinkimo semantika

Pasirinkimas yra griežtas:

- Jei nėra atpažįstamų tipų raktų, įkeliami visi tipai.
- `true`, `null` arba `"*"` įkelia visus to tipo įrašus.
- Eilutė arba sąrašas įkelia tik tikslius ID, pavadinimus, nuorodas, kelius arba šaltinio kelius.
- Tuščia eilutė, sąrašas arba `false` neįkelia nė vieno to tipo įrašo.
- Kai nurodomas bent vienas tipo raktas, kiti tipai neaptinkami, nesinchronizuojami, neatvaizduojami ir nekompiliuojami.

Taip pakeitimų užklausos yra saugios ir dideliems projektams. Esami blokai ir puslapiai randami jų kanoniniuose registruose. Kai priekinės dalies užklausoje įkelta tik išsaugota puslapio projekcija, Canvas tik skaitymo režimu aptinka šaltinius ir sujungia atitinkančius įrašų ID bei nuolatines nuorodas, nesinchronizuodama turinio. Tas pats tapatybės sujungimas taikomas, kai loginis aptikimo šaltinis pirmiausia užpildo šaltiniais pagrįstą registrą, todėl kontekstinis puslapio atvaizdavimas vis tiek naudoja atitinkamą valdomą WordPress įrašą. Nauja tiesioginės sesijos topologija aptinkama tik aplink pakeistą katalogą, o pasirinkti šablonų ir Site Editor šablonų šaltiniai kompiliuojami tik po pasirinkimo.

REST atnaujinimo galinis įvesties taškas taiko tą pačią taisyklę esamiems `blocks` ir `pages` užklausos parametrams. Pavyzdžiui, `?blocks=theme/hero` grąžina tą bloką ir jokių puslapių; mišriam atsakymui naudokite abu parametrus. Iškvietus galinį įvesties tašką nenurodžius nė vieno parametro, išlaikomas visas senasis atsakymas.

## Tiesioginis režimas

Tiesioginiame režime failų pakeitimams aptikti ir drobei atnaujinti realiuoju laiku naudojami Server-Sent Events (SSE). Redaguojant bloko ar puslapio šabloną arba stilių lentelę, paveiktos piešimo sritys automatiškai atnaujinamos maždaug per vieną sekundę.

Tiesioginį režimą įjunkite arba išjunkite išskleidžiamajame meniu. Kai jis aktyvus, rodomas pulsuojantis žalias indikatorius. Nustatymas išsaugomas tarp sesijų naudojant localStorage.

Tiesioginis režimas seka pakeitimus `.php`, `.json`, `.css`, `.scss`, `.js`, `.twig` ir `.html` failuose, esančiuose blokų ir puslapių kataloguose. Žinomi pakeitimai atnaujina tik registruotą bloką arba puslapį. Iš tiesų naujam blokui ar puslapiui aptikti atliekamas vienas konkretaus katalogo topologijos patikrinimas, todėl turinį galima kurti ir tada, kai tiesioginė sesija jau atidaryta, iš naujo nenuskaitant nesusijusių šaltinių.

## Fokusavimo režimas

Spustelėkite bet kurios piešimo srities žymą, kad įjungtumėte fokusavimo režimą. Pasirinkta sritis užpildo visą peržiūros langą ir ją galima slinkti vertikaliai. Paspauskite Escape arba uždarymo mygtuką, kad grįžtumėte į apžvalgą.

## Valdikliai

| Veiksmas | Įvestis |
|--------|-------|
| Slinkti | Slinkimas / vilkimas dviem pirštais jutikliniame kilimėlyje |
| Keisti mastelį | Ctrl+slinkimas arba gnybimas |
| Pritaikyti rodiniui | Išskleidžiamasis meniu |
| Padidinti iki 100% | Išskleidžiamasis meniu |
| Fokusuoti piešimo sritį | Spustelėti piešimo srities žymą |
| Išeiti iš fokusavimo režimo | Escape / uždarymo mygtukas |

## Sauga

Drobės scenarijus ir puslapio duomenys įkeliami tik įvykdžius visas sąlygas:

- Nustatymas `dev.canvas.enabled` yra `true`.
- Dabartinis naudotojas turi galimybę `edit_posts`.

Vieši lankytojai niekada nemato drobės scenarijaus ar puslapio metaduomenų.
