Pāriet uz saturu

Lietotnes ekrāna veidošana ar komplektā iekļauto UI

Lielākajai daļai WordPress projektu agrāk vai vēlāk vajag ekrānu, kas drīzāk līdzinās lietotnei, nevis lapai: ierakstu sarakstu, pogu, kas atver veidlapu, un paziņojumu pēc saglabāšanas. Parasti šim nolūkam izmanto JavaScript ietvaru, REST kontrolieru kopu un komponentu bibliotēku, kas visi tiek uzturēti līdzās tēmai.

Blockstudio jau ir iekļautas visas šīs daļas. db.php nodrošina bloku krātuvi, validāciju un CRUD galapunktus. rpc.php pievieno pielāgotas servera darbības. Komplektā iekļautie UI komponenti nodrošina dialogu, veidlapas laukus, pogas, emblēmas un īslaicīgus paziņojumus. Tos savieno Interactivity API krātuve. Šajā ceļvedī vienā bloka mapē no sākuma līdz beigām izveidosim vienu ekrānu:

  • Projektu tabula, kas tiek atveidota serverī un sinhronizēta klientā.
  • Dialogs Jauns projekts ar veidlapu, kuras dati tiek validēti atbilstoši shēmai.
  • Pogas Arhivēt un Atjaunot, kas izsauc funkciju RPC ar optimistisku atjauninājumu un atcelšanu.
  • Pogas Dzēst, kas tieši izmanto datu API.
  • Īslaicīgs paziņojums pēc veiksmīgas izveides un cits — kad izmaiņas neizdodas saglabāt.

Pirms sākat

Komplektā iekļautos komponentus var izvēlēties ieslēgt. Aktivizējiet tos failā blockstudio.json:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "ui": {
    "enabled": true
  }
}

Ekrāns atrodas vienā blokā:

Kods
acme/
└── blockstudio/
    └── projects/
        ├── block.json
        ├── db.php
        ├── rpc.php
        ├── index.php
        ├── script.inline.js
        └── style.inline.css

1. darbība: datu modelis

PHP
<?php
return [
    'storage'    => 'sqlite',
    'capability' => [
        'create' => 'edit_posts',
        'read'   => 'edit_posts',
        'update' => 'edit_posts',
        'delete' => 'edit_posts',
    ],
    'fields'     => [
        'name'   => [
            'type'      => 'string',
            'required'  => true,
            'minLength' => 2,
            'maxLength' => 80,
        ],
        'owner'  => [
            'type'     => 'string',
            'format'   => 'email',
            'required' => true,
        ],
        'status' => [
            'type'     => 'string',
            'enum'     => ['active', 'archived'],
            'required' => true,
        ],
    ],
];

Katrai darbībai nepieciešama iespēja edit_posts, tāpēc, ja pieprasījums veikts bez pieteikšanās, galapunkti atbild ar 401, un mainīt datus var tikai redaktori un lietotāji ar augstākām tiesībām. SQLite krātuve saglabā ierakstus projects/db/default.sqlite, līdzās kodam.

status ir required, nevis ietver default. Izmantojot SQLite un tabulas krātuvi, shēma izveides laikā neaizpilda trūkstošu vērtību, tāpēc ierakstam, kas izveidots bez status, tiek saglabāta tukša vērtība. Ja lauks ir obligāts un tiek nosūtīts no veidlapas, katra rinda paliek derīga.

Pievienojiet pāris ierakstu, izmantojot komandrindu:

Apvalks
wp bs db create acme/projects --name="Website relaunch" --owner=ana@example.com --status=active
wp bs db create acme/projects --name="Q3 report" --owner=ben@example.com --status=archived
wp bs db list acme/projects
Kods
Success: Record created (ID: 1).
Success: Record created (ID: 2).
id	name	owner	status	created_at	updated_at
2	Q3 report	ben@example.com	archived	...
1	Website relaunch	ana@example.com	active	...

Saraksts tiek atgriezts, sākot ar jaunāko ierakstu, tāpat kā tabulā.

2. darbība: servera darbība

No lietotāja viedokļa arhivēšana nav vienkārša lauka rediģēšana, tāpēc tai izveido atsevišķu funkciju:

PHP
<?php
use Blockstudio\Db;

return [
    'set_status' => [
        'callback'   => function (array $params) {
            $id     = (int) ($params['id'] ?? 0);
            $status = (string) ($params['status'] ?? '');
            $db     = Db::get('acme/projects');

            if (!$db->get_record($id)) {
                return new \WP_Error('not_found', 'Project not found.', ['status' => 404]);
            }

            return $db->update($id, ['status' => $status]);
        },
        'capability' => 'edit_posts',
    ],
];

Db::update() validē atbilstoši shēmai, tāpēc enum failā db.php joprojām pārbauda vērtību. Ja funkciju izsauc ar nezināmu statusu, tā atgriež tāda paša formāta kļūdu kā datu API:

JSON
{"code":"blockstudio_db_validation","message":"Validation failed.","data":{"status":400,"errors":{"status":["Must be one of: active, archived."]}}}

Funkciju var izsaukt arī no komandrindas:

Apvalks
wp bs rpc call acme/projects set_status --id=2 --status=active
Kods
{
    "id": 2,
    "name": "Q3 report",
    "owner": "ben@example.com",
    "status": "active",
    ...
}

3. darbība: bloka definīcija

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/projects",
  "title": "Projects",
  "category": "widgets",
  "icon": "list-view",
  "supports": {
    "interactivity": true
  },
  "blockstudio": {
    "interactivity": {
      "enqueue": true
    }
  }
}

supports.interactivity liek WordPress serverī apstrādāt veidnes direktīvas, lai tabulas rindas tiktu atveidotas, pirms tiek izpildīts JavaScript.

4. darbība: veidne

PHP
<?php
$can_edit = current_user_can('edit_posts');
$projects = $can_edit ? \Blockstudio\Db::get('acme/projects')->list() : [];

wp_interactivity_state('acme/projects', [
    'projects'    => array_values($projects),
    'hasProjects' => !empty($projects),
    'notice'      => '',
    'isArchived'  => function () {
        $context = wp_interactivity_get_context();

        return 'archived' === ($context['project']['status'] ?? '');
    },
]);
?>
<div
    useBlockProps
    class="projects"
    data-wp-interactive="acme/projects"
    data-wp-on-document--formsuccess="actions.created"
>
<?php if (!$can_edit) : ?>
    <p>Sign in with an editor account to manage projects.</p>
<?php else : ?>
    <div class="projects__bar">
        <bs:bsui-text content="Projects" variant="title" tag="h2" />
        <bs:bsui-dialog>
            <bs:bsui-dialog-trigger trigger_label="New project" />
            <bs:bsui-dialog-backdrop />
            <bs:bsui-dialog-popup>
                <bs:bsui-dialog-header>
                    <bs:bsui-dialog-title content="New project" />
                    <bs:bsui-dialog-description content="Projects start out active." />
                </bs:bsui-dialog-header>
                <bs:bsui-dialog-content>
                    <bs:bsui-form block="acme/projects">
                        <bs:bsui-field name="name">
                            <bs:bsui-field-label text="Name" />
                            <bs:bsui-input name="name" placeholder="Spring campaign" required="true" />
                            <bs:bsui-field-error />
                        </bs:bsui-field>
                        <bs:bsui-field name="owner">
                            <bs:bsui-field-label text="Owner email" />
                            <bs:bsui-input name="owner" type="email" placeholder="owner@example.com" required="true" />
                            <bs:bsui-field-error />
                        </bs:bsui-field>
                        <input type="hidden" name="status" value="active" />
                        <bs:bsui-space size="2" />
                        <bs:bsui-button label="Create project" />
                    </bs:bsui-form>
                </bs:bsui-dialog-content>
                <bs:bsui-dialog-footer>
                    <bs:bsui-dialog-close label="Cancel" />
                </bs:bsui-dialog-footer>
            </bs:bsui-dialog-popup>
        </bs:bsui-dialog>
    </div>

    <table class="projects__table">
        <thead>
            <tr>
                <th scope="col">Name</th>
                <th scope="col">Owner</th>
                <th scope="col">Status</th>
                <th scope="col">Actions</th>
            </tr>
        </thead>
        <tbody>
            <template data-wp-each--project="state.projects" data-wp-each-key="context.project.id">
                <tr>
                    <td data-wp-text="context.project.name"></td>
                    <td data-wp-text="context.project.owner"></td>
                    <td>
                        <span data-wp-bind--hidden="state.isArchived"><bs:bsui-badge label="Active" variant="success" /></span>
                        <span data-wp-bind--hidden="!state.isArchived"><bs:bsui-badge label="Archived" variant="secondary" /></span>
                    </td>
                    <td class="projects__actions">
                        <span data-wp-on--click="actions.toggleArchived">
                            <span data-wp-bind--hidden="state.isArchived"><bs:bsui-button label="Archive" variant="outline" size="sm" /></span>
                            <span data-wp-bind--hidden="!state.isArchived"><bs:bsui-button label="Restore" variant="outline" size="sm" /></span>
                        </span>
                        <span data-wp-on--click="actions.remove"><bs:bsui-button label="Delete" variant="ghost" size="sm" /></span>
                    </td>
                </tr>
            </template>
        </tbody>
    </table>

    <p class="projects__empty" data-wp-bind--hidden="state.hasProjects">No projects yet.</p>

    <div class="projects__toasts">
        <bs:bsui-toast-provider>
            <div data-wp-interactive="acme/projects" data-wp-bind--hidden="!state.isCreatedNotice" data-wp-on--click="actions.dismissNotice">
                <bs:bsui-toast message="Project created." />
            </div>
            <div data-wp-interactive="acme/projects" data-wp-bind--hidden="!state.isFailedNotice" data-wp-on--click="actions.dismissNotice">
                <bs:bsui-toast message="That change was not saved." />
            </div>
        </bs:bsui-toast-provider>
    </div>
<?php endif; ?>
</div>

Apskatīsim četras šīs veidnes daļas tuvāk.

Servera stāvoklis sagatavo sākotnējo attēlojumu. wp_interactivity_state() nodod ierakstus gan servera direktīvu procesoram, gan klienta krātuvei. Veidne data-wp-each serverī tiek izvērsta īstās rindās — katram ierakstam ir viens tr. isArchived ir noslēgums: servera apstrādes laikā WordPress to izpilda katrai rindai, un wp_interactivity_get_context() atgriež šīs rindas kontekstu, tāpēc arhivētajām rindām pareizā emblēma un poga ir redzamas jau pirms hidratācijas. Pārlūkā pārņem tāda paša nosaukuma krātuves getter. hasProjects ir vienkārša vērtība tā paša iemesla dēļ: bez tās serveris nezinātu, vai paslēpt rindkopu par tukšu sarakstu.

Dialogs un veidlapa ir sistēmas komponenti. trigger_label tiek nodots bsui/button, kas atrodas aktivizētājā, kā aprakstīts ceļvedī UISastāvs. bsui/form kopā ar block="acme/projects" serializē tās laukus, izmantojot FormData, un nosūta datus šī bloka izveides galapunktam. Katram bsui/field ir ievades lauka nosaukums, tāpēc shēmas kļūdas par katru lauku tiek parādītas zem pareizā vadības elementa. Iesniedzot tukšu veidlapu, zem lauka Nosaukums parādās “Jābūt vismaz 2 rakstzīmēm.”, zem lauka Īpašnieka e-pasts — “Jābūt derīgai e-pasta adresei.”, bet veidlapas apakšā — “Validācija neizdevās.” Slēptā ievade status tiek nosūtīta kopā ar veidlapas datiem, tāpēc jaunie projekti atbilst obligātā lauka prasībai.

Tabulas marķējumu veidojat jūs. bsui/table ir piemērots veidnē rakstītām rindām: tā galvenes šūnas kārto, pārvietojot esošos elementus tr, kas konfliktētu ar data-wp-each, kurš pārvalda rindas. Pirms versijas Blockstudio 7.7 tās daļas ievietoja arī div tieši elementā table, thead, tbody un tr, un pārlūkprogrammas to pārvieto ārpus tabulas. Rindām, kas nāk no krātuves, rakstiet elementu table paši un šūnās ievietojiet sistēmas komponentus. Emblēmas un pogas rindas veidnē ir parasti bsui/badge un bsui/button tagi. Katra poga atrodas elementā span ar klikšķa direktīvu, tāpēc poga paliek sistēmas poga, bet darbība pieder jūsu krātuvei.

Īslaicīgais paziņojums ir prezentācijas komponents. bsui/toast-provider atveido pieklājīgu tiešraides reģionu, bet bsui/toast — statusa paziņojumu ar aizvēršanas pogu. Pakalpojuma sniedzējs pats nenosaka savu atrašanās vietu ekrānā, un aizvēršanas poga nenoslēpj no marķējuma atveidotu paziņojumu. Tāpēc ekrāns veic abas darbības: ietvars ar position: fixed novieto reģionu, bet katrs paziņojums atrodas div, kura hidden saistījums un klikšķa apstrādātājs pieder ekrāna krātuvei. Klikšķis uz aizvēršanas pogas tiek nodots augstāk pa DOM koku līdz šim div.

5. darbība: krātuve

JavaScript
import { store, getContext } from '@wordpress/interactivity';

const BLOCK = 'acme/projects';
let noticeTimer;

// bs.fn() and bs.db() resolve with the error body on a failed request.
// Throwing here is what lets bs.mutate() roll the optimistic change back.
const ok = (request) =>
    request.then((result) => {
        if (result?.code) {
            throw result;
        }
        return result;
    });

const notify = (notice) => {
    state.notice = notice;
    clearTimeout(noticeTimer);
    noticeTimer = setTimeout(() => {
        state.notice = '';
    }, 4000);
};

const { state } = store(BLOCK, {
    state: {
        get hasProjects() {
            return state.projects.length > 0;
        },
        get isArchived() {
            return getContext().project.status === 'archived';
        },
        get isCreatedNotice() {
            return state.notice === 'created';
        },
        get isFailedNotice() {
            return state.notice === 'failed';
        },
    },
    actions: {
        created(event) {
            const record = event.detail;
            if (!record?.id || !('owner' in record)) {
                return;
            }

            event.preventDefault();
            state.projects = [record, ...state.projects];
            store('bsui/dialog').actions.close();
            notify('created');
        },
        dismissNotice() {
            state.notice = '';
        },
        *toggleArchived() {
            const project = getContext().project;
            const status = project.status === 'archived' ? 'active' : 'archived';

            try {
                yield bs.mutate({
                    fn: () => ok(bs.fn('set_status', { id: project.id, status }, BLOCK)),
                    state,
                    key: 'projects',
                    action: 'update',
                    id: project.id,
                    optimistic: { status },
                });
            } catch (error) {
                notify('failed');
            }
        },
        *remove() {
            const project = getContext().project;

            try {
                yield bs.mutate({
                    fn: () => ok(bs.db(BLOCK).delete(project.id)),
                    state,
                    key: 'projects',
                    action: 'delete',
                    id: project.id,
                });
            } catch (error) {
                notify('failed');
            }
        },
    },
});

Veidlapas notikumu apstrāde. Ja saglabāšana izdodas, bsui/form nosūta notikumu formsuccess, kas izplatās augšup pa DOM koku, to var atcelt un kurā izveidotais ieraksts ir pieejams laukā event.detail. Ja saglabāšana neizdodas, tiek nosūtīts formerror ar kļūdas pamattekstu. Apstrādātājs ir piesaistīts dokumentam (data-wp-on-document--formsuccess), nevis ekrāna saknes elementam, jo atvērta dialoga uznirstošais logs tiek pārvietots uz document.body, tāpēc tā notikumi vairs neizplatās caur bloku. Pārbaude owner ignorē notikumus no citām veidlapām tajā pašā lapā.

Izsaucot event.preventDefault(), tiek novērsts tas, ka veidlapas laukus aizstāj paziņojums par veiksmīgu darbību; pati veidlapa tik un tā tiek atiestatīta. Pēc tam darbība pievieno ierakstu saraksta sākumā, aizver dialogu ar bsui/dialog krātuves darbību close un parāda īslaicīgu paziņojumu. close aizver augšējo atvērto dialogu un atgriež fokusu tā aktivizētājam, tāpēc pēc izveides tastatūras fokuss atgriežas pie pogas Jauns projekts.

Kļūdu gadījumā izmaiņas tiek atceltas. bs.mutate() optimistiski uzreiz piemēro izmaiņas un atjauno iepriekšējās vērtības, ja fn solījums tiek noraidīts. bs.fn() un bs.db() netiek noraidīti HTTP kļūdu gadījumā: WP_Error no RPC funkcijas, validācijas kļūda vai trūkstošs ieraksts tiek atgriezts kā kļūdas pamatteksts. Palīgfunkcija ok() pārvērš rezultātu ar code par noraidījumu, tāpēc rinda atgriežas iepriekšējā stāvoklī un parādās kļūmes paziņojums. Bez tās kļūdains atjauninājums kļūdas pamattekstu sapludinātu ar rindu, bet pēc neveiksmīgas dzēšanas rinda paliktu noņemta.

Bloka nosaukuma norādīšana. Blockstudio izvada iekļautos skriptus kā <script type="module">, un moduļu skriptiem nav document.currentScript, tāpēc bs.fn() nevar noteikt, kurš bloks izsauc funkciju. Nododiet bloka nosaukumu kā trešo argumentu, kā to dara krātuve ar BLOCK.

6. darbība: ievietojiet ekrānu lapā

Lapa, kuras pamatā ir faili, ievieto bloku ar tā tagu:

JSON
{
  "$schema": "https://blockstudio.dev/schema/page",
  "name": "projects",
  "title": "Projects",
  "slug": "projects",
  "postStatus": "private"
}
PHP
<h1>Projects</h1>
<bs:acme-projects />

Parsētājs pārveido tagu par vietējo bloku:

HTML
<!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Projects</h1><!-- /wp:heading --><!-- wp:acme/projects /-->

Palaidiet wp bs pages sync, lai izveidotu lapu. postStatus: "private" neļauj to redzēt anonīmiem apmeklētājiem, kuriem jebkurā gadījumā būtu redzams tikai pieteikšanās ziņojums.

Kā ekrāns darbojas izpildes laikā

Atveriet lapu kā redaktors:

  1. Tabulā tiek parādītas abas atveidotās rindas; arhivētajā rindā redzama emblēma Arhivēts un poga Atjaunot.
  2. Poga Jauns projekts atver dialogu. Uznirstošais logs un fons tiek pārvietoti uz document.body, fokuss nonāk laukā Nosaukums, un Escape vai Atcelt dialogu aizver.
  3. Iesniedzot derīgas vērtības, tiek nosūtīts viens POST uz /wp-json/blockstudio/v1/db/acme-projects/default. Dialogs aizveras, jaunā rinda parādās saraksta augšā, un četras sekundes stūrī ir redzams paziņojums “Projekts izveidots.”
  4. Poga Arhivēt uzreiz nomaina emblēmu un nosūta set_status caur /wp-json/blockstudio/v1/fn/acme/projects/set_status. Ja ieraksts pa to laiku ir dzēsts citur, funkcija atgriež kļūdu 404, rinda atgriežas stāvoklī Aktīvs, un parādās paziņojums “Izmaiņas netika saglabātas.”
  5. Poga Dzēst nekavējoties noņem rindu. Izdzēšot pēdējo ierakstu, parādās paziņojums “Projektu vēl nav.”

Stili

Ekrāna CSS izmanto bibliotēkas tokenus, tāpēc tabula atbilst apkārtējiem komponentiem un ievēro jebkurus --bs-ui-* rekvizītu tēmas pielāgojumus:

CSS
.projects__table {
    width: 100%;
    border-collapse: collapse;
    font-size: var(--bs-ui-font-size);
}

.projects__table th,
.projects__table td {
    padding: var(--bs-ui-space-2) var(--bs-ui-space-3);
    border-bottom: 1px solid var(--bs-ui-border);
    text-align: left;
}

/* ... */

.projects__toasts {
    position: fixed;
    right: var(--bs-ui-space-4);
    bottom: var(--bs-ui-space-4);
    z-index: 40;
}

z-index, kas atrodas 40, novieto paziņojumu reģionu zem dialoga fona, kura slānis ir 50. Lai mainītu visas ekrāna tēmu, pielāgojiet tokenus, kā aprakstīts sadaļā stili; izmaiņām sekos gan komponenti, gan tabula.

Nākamās darbības

  • UI komponenti: dizaina sistēma, tokeni un pilns komponentu komplekts.
  • UISastāvs: saistītu komponentu kopas, aktivizētāja parametru nodošana un dialoga slāņu modelis.
  • Datubāze: glabāšanas režīmi, piekļuves kontrole, bs.db() un bs.mutate().
  • RPC: piekļuves kontrole, HTTP metodes un izsaukumi starp blokiem.
  • Pilna steka bloki: tie paši pamatelementi uzdevumu saraksta lietotnē un jaunumu vēstules abonēšanas formā.