انتقل إلى المحتوى

إنشاء شاشة تطبيق باستخدام UI المضمّنة

تحتاج معظم مشاريع WordPress في نهاية المطاف إلى شاشة تشبه التطبيق أكثر من الصفحة: قائمة بالسجلات، وزر يفتح نموذجًا، ورسالة تأكيد عند نجاح الحفظ. والحل المعتاد هو إطار عمل JavaScript ومجموعة من وحدات التحكم REST ومكتبة مكونات، تُصان جميعها بجانب القالب.

يتضمن Blockstudio هذه العناصر جميعًا. توفر db.php تخزينًا للكتل والتحقق من الصحة ونقاط نهاية CRUD. وتضيف rpc.php إجراءات خادم مخصصة. توفر مكونات UI المضمّنة مربعات الحوار وحقول النماذج والأزرار والشارات والتنبيهات. ويربطها مخزن Interactivity API. يشرح هذا الدليل إنشاء شاشة كاملة خطوة بخطوة داخل مجلد كتلة واحد:

  • جدول للمشاريع يُعرض على الخادم ويظل متزامنًا على العميل.
  • مربع حوار مشروع جديد يتضمن نموذجًا يتحقق من صحة البيانات وفق المخطط.
  • زرا أرشفة واستعادة يستدعيان دالة RPC مع تحديث تفاؤلي وإمكانية التراجع.
  • أزرار حذف تستخدم بيانات API مباشرة.
  • تنبيه بعد إنشاء ناجح وآخر عند تعذر حفظ تغيير.

قبل البدء

المكونات المضمّنة اختيارية. فعّلها في blockstudio.json:

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

توجد الشاشة في كتلة واحدة:

الكود
acme/
└── blockstudio/
    └── projects/
        ├── block.json
        ├── db.php
        ├── rpc.php
        ├── index.php
        ├── script.inline.js
        └── style.inline.css

الخطوة 1: نموذج البيانات

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,
        ],
    ],
];

تتطلب كل عملية صلاحية edit_posts، لذا ترد نقاط النهاية بالرمز 401 على الطلبات من المستخدمين غير المسجلين، ولا يمكن تغيير البيانات إلا للمحررين ومن هم أعلى منهم. يخزن SQLite السجلات في projects/db/default.sqlite بجانب الكود.

إن status من النوع required بدلًا من أن يحمل default. مع تخزين SQLite والجداول، لا يملأ المخطط قيمة مفقودة عند الإنشاء، لذلك يُخزن السجل الذي يُنشأ من دون status بقيمة فارغة. اشتراط الحقل وإرساله من النموذج يحافظ على صحة كل صف.

أضف بضع سجلات تجريبية من سطر الأوامر:

سطر الأوامر
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
الكود
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	...

تُعاد القائمة من الأحدث إلى الأقدم، وهو الترتيب الذي يستخدمه الجدول.

الخطوة 2: إجراء على الخادم

الأرشفة ليست تعديلًا عاديًا لحقل من وجهة نظر المستخدم، لذا تُنفذ عبر دالة مسماة:

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() من صحة البيانات وفق المخطط، لذا يظل enum في db.php مسؤولًا عن حماية القيمة. يؤدي استدعاء الدالة بحالة غير معروفة إلى إرجاع صيغة الخطأ نفسها التي تعيدها بيانات API:

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

يمكن استدعاء الدالة من سطر الأوامر أيضًا:

سطر الأوامر
wp bs rpc call acme/projects set_status --id=2 --status=active
الكود
{
    "id": 2,
    "name": "Q3 report",
    "owner": "ben@example.com",
    "status": "active",
    ...
}

الخطوة 3: تعريف الكتلة

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 ‏WordPress يعالج توجيهات القالب على الخادم، وهذا ما يعرض صفوف الجدول قبل تشغيل أي JavaScript.

الخطوة 4: القالب

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>

تستحق أربعة أجزاء من هذا القالب إلقاء نظرة أقرب.

حالة الخادم تجهّز العرض الأول. يمرر wp_interactivity_state() السجلات إلى معالج التوجيهات على الخادم وإلى مخزن العميل. يتوسع القالب data-wp-each إلى صفوف فعلية على الخادم، صف tr لكل سجل. إن isArchived دالة إغلاق: يقيّمها WordPress لكل صف أثناء المعالجة على الخادم، ويعيد wp_interactivity_get_context() سياق ذلك الصف، فتظهر الشارات والأزرار المناسبة للصفوف المؤرشفة قبل التهيئة. وفي المتصفح، يتولى مُلحق المخزن بالاسم نفسه المهمة. أما hasProjects فهي قيمة عادية للسبب نفسه: من دونها لن يعرف الخادم ما إذا كان عليه إخفاء فقرة الحالة الفارغة.

مربع الحوار والنموذج من مكونات النظام. يُمرر trigger_label إلى bsui/button داخل المشغّل، كما هو موضح في تركيب UI. يقوم bsui/form مع block="acme/projects" بتسلسل حقوله باستخدام FormData وإرسالها إلى نقطة نهاية الإنشاء الخاصة بتلك الكتلة. ويحمل كل bsui/field اسم حقل الإدخال، فتظهر أخطاء التحقق الخاصة بكل حقل أسفل عنصر التحكم الصحيح. يؤدي إرسال النموذج الفارغ إلى عرض «يجب ألا يقل الطول عن حرفين.» تحت الاسم و«يجب إدخال عنوان بريد إلكتروني صالح.» تحت بريد المالك الإلكتروني، إضافة إلى «فشل التحقق.» أسفل النموذج. ينتقل حقل الإدخال المخفي status مع بيانات النموذج، وبذلك تستوفي المشاريع الجديدة الحقل المطلوب.

الجدول مكتوب بعلاماتك الخاصة. يناسب bsui/table الصفوف المكتوبة في القالب: إذ ترتب خلايا العنوان الصفوف بنقل عناصر tr الموجودة، وهو ما يتعارض مع تولي data-wp-each إدارة الصفوف. وقبل الإصدار 7.7 من Blockstudio، كانت أجزاؤه تضع أيضًا عنصر div مباشرة داخل table وthead وtbody وtr، فتنقله المتصفحات خارج الجدول. للصفوف القادمة من مخزن، اكتب عنصر table بنفسك وضع مكونات النظام داخل الخلايا. الشارات والأزرار في قالب الصف هي وسوم bsui/badge وbsui/button عادية. يقع كل زر داخل عنصر span يحمل توجيه النقر، فيبقى الزر زر النظام بينما ينتمي الإجراء إلى مخزنك.

التنبيه للعرض فقط. يعرض bsui/toast-provider منطقة حية مهذبة، ويعرض bsui/toast رسالة حالة مع زر إغلاق. لا يحدد المزوّد موضعه على الشاشة، ولا يخفي زر الإغلاق تنبيهًا معروضًا من العلامات. لذلك تنفذ الشاشة الأمرين: يضع غلاف يحمل position: fixed المنطقة، ويقع كل تنبيه داخل div يرتبط hidden فيه ومعالج النقر بمخزن الشاشة. وتنتقل النقرة على زر الإغلاق إلى div ذلك.

الخطوة 5: المخزن

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');
            }
        },
    },
});

الاستجابة للنموذج. عند نجاح الحفظ، يرسل bsui/form حدث formsuccess ينتقل إلى العناصر الأب، ويمكن إلغاؤه، ويحمل السجل المنشأ في event.detail. وعند فشل الحفظ، يرسل formerror مع نص الخطأ. يوجد المستمع على المستند (data-wp-on-document--formsuccess) بدلًا من العنصر الجذر للشاشة، لأن نافذة الحوار المنبثقة المفتوحة تُنقل إلى document.body، فلا تعود أحداثها تنتقل عبر الكتلة. ويتجاهل فحص owner الأحداث القادمة من نماذج أخرى في الصفحة نفسها.

يمنع استدعاء event.preventDefault() النموذج من استبدال حقوله برسالة النجاح؛ لكنه يظل يعيد ضبط نفسه. ثم يضيف الإجراء السجل إلى البداية، ويغلق مربع الحوار باستخدام إجراء close في مخزن bsui/dialog، ويعرض التنبيه. يغلق close مربع الحوار المفتوح في المقدمة ويعيد التركيز إلى المشغّل، لذا يعود تركيز لوحة المفاتيح بعد الإنشاء إلى مشروع جديد.

التراجع عند الأخطاء. يطبق bs.mutate() التغيير التفاؤلي فورًا ويستعيد القيم السابقة عند رفض الوعد من fn. لا يرفض bs.fn() وbs.db() عند أخطاء HTTP: إذ تعيد دالة RPC خطأ WP_Error، أو فشل التحقق، أو سجلًا غير موجود، وتُحل جميعها بنص الخطأ. يحول المساعد ok() النتيجة التي تتضمن code إلى حالة رفض، فيعود الصف إلى حالته السابقة ويظهر تنبيه الفشل. ومن دونه، سيدمج التحديث الفاشل نص الخطأ في الصف، وسيُبقي الحذف الفاشل الصف محذوفًا.

تسمية الكتلة. يطبع Blockstudio السكربتات المضمنة بصيغة <script type="module">، ولا تتضمن سكربتات الوحدات document.currentScript، لذا لا يستطيع bs.fn() تحديد الكتلة التي تستدعيه. مرر اسم الكتلة بوصفه الوسيط الثالث، كما يفعل المخزن مع BLOCK.

الخطوة 6: إضافة الشاشة إلى صفحة

تضع الصفحة المعتمدة على ملف الكتلة باستخدام وسمها:

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

يحوّل المحلّل الوسم إلى كتلة أصلية:

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

شغّل wp bs pages sync لإنشاء الصفحة. ويمنعها postStatus: "private" عن الزوار المجهولين، الذين لن يروا على أي حال سوى رسالة تسجيل الدخول.

سلوك الشاشة أثناء التشغيل

عند فتح الصفحة بصفتك محررًا:

  1. يظهر الجدول بصفّيه، ويظهر على الصف المؤرشف شارة مؤرشف وزر استعادة.
  2. يفتح مشروع جديد مربع الحوار. تنتقل النافذة المنبثقة وخلفيتها إلى document.body، وينتقل التركيز إلى حقل الاسم، ويغلق الضغط على Escape أو إلغاء مربع الحوار.
  3. يؤدي إرسال قيم صالحة إلى إرسال POST واحد إلى /wp-json/blockstudio/v1/db/acme-projects/default. يُغلق مربع الحوار، ويظهر الصف الجديد في الأعلى، وتظهر رسالة «تم إنشاء المشروع.» في الزاوية لمدة أربع ثوانٍ.
  4. يغيّر أرشفة الشارة فورًا ويرسل set_status عبر /wp-json/blockstudio/v1/fn/acme/projects/set_status. إذا حُذف السجل في مكان آخر في هذه الأثناء، تعيد الدالة خطأ 404، ويعود الصف إلى حالة نشط، وتظهر رسالة «لم يُحفظ هذا التغيير.».
  5. يزيل حذف الصف فورًا. ويؤدي حذف آخر مشروع إلى ظهور «لا توجد مشاريع بعد.»

التنسيق

تقرأ CSS الخاصة بالشاشة رموز المكتبة، فيتناسق الجدول مع المكونات المحيطة به ويتبع أي تجاوز للسمة لخصائص --bs-ui-*:

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 الخاصة بـ40 منطقة التنبيه أسفل خلفية مربع الحوار، التي تقع عند 50. لتغيير سمة الشاشة بالكامل، تجاوز الرموز كما هو موضح ضمن التنسيق؛ وستتبع المكونات والجدول ذلك.

الخطوات التالية

  • مكونات UI: نظام التصميم والرموز ومجموعة المكونات الكاملة.
  • التركيب UI: العائلات المركبة وتمرير المشغّل ونموذج الطبقات خلف مربع الحوار.
  • قاعدة البيانات: أوضاع التخزين والتحكم في الوصول وbs.db() وbs.mutate().
  • RPC: التحكم في الوصول وطرق HTTP والاستدعاءات بين الكتل.
  • الكتل متكاملة المكدس: عناصر البناء نفسها في تطبيق مهام وتسجيل اشتراك في نشرة إخبارية.