آموزش ساخت بلوک های ویرایشگر بلاک، قسمت 2


من آخرین مقاله را با یک بلوک عملکردی به پایان رساندم که نشان می دهد یکی چیز در ویرایشگر و یکی دیگر چیزی در قسمت جلویی دلیل انجام این کار این بود که بتوانیم ببینیم که چگونه پایه اصلی یک افزونه را برای ویرایشگر Block کنار هم قرار دهیم.

اکنون که در این مرحله هستیم، شروع صحبت در مورد موارد مربوط به ویرایشگر، چیزهای مرتبط با فرانت اند، نحوه شروع سریال سازی داده ها، نحوه شروع خواندن داده ها و غیره بسیار آسان تر است. اما از آنجایی که من سعی می‌کنم کل این سری را به‌عنوان یک مهندس باطن ایجاد بلوک‌ها انجام دهم – که معمولاً به توسعه frontend واگذار می‌شود – می‌خواهم آن را گام به گام پیش ببرم.

در آخرین مقاله نوشتم:

[T]چیزی که در ادامه به بررسی آن خواهیم پرداخت این است که استایل‌هایی را هم برای فرانت‌اند و هم برای ویرایشگر و برخی قابلیت‌های اساسی به بلوک اضافه می‌کنیم.

همانطور که من به نوشتن در مورد یادگیری ساخت بلوک های ویرایشگر بلاک ادامه می دهم، به بررسی اضافه کردن سبک ها به backend و frontend ادامه خواهیم داد.


در این مقاله قصد داریم به موارد زیر بپردازیم:

  • افزودن کنترل‌هایی به بلوک در ویرایشگر، بنابراین ما می‌توانیم محل قرارگیری آن را در خود وردپرس کنترل کنیم (یا حتی آن را از ویرایشگر حذف کنیم)،
  • اطمینان حاصل شود که آنچه در ویرایشگر می بینیم همان چیزی است که در قسمت جلو می بینیم

مانند دفعه قبل، چیزهایی وجود دارد که باید در آنها غوطه ور شویم که به مواد مرجع و پیوندهایی به منابع خارجی نیاز دارند. اما این بخشی از سفر یادگیری ساخت بلوک ها را در نظر بگیرید.

بلوک‌های ویرایشگر مسدود کردن: ویرایش و ذخیره (یا مشاهده)

اولین چیزی که می خواهم به آن اشاره کنم، همانطور که در مقاله اول در مورد آن نوشتم، دو عملکردی است که با آنها کار خواهیم کرد: edit و save.

شخصاً فکر می کنم متأسفانه توابع نامگذاری شده اند. اینطور نیست که آنها کاری را که انجام می دهند نمایندگی نمی کنند، اما نماینده نیستند فقط کاری که آنها انجام می دهند. به عبارت دیگر، آنها کاری بیش از صرفا اجازه ویرایش و ذخیره محتوا را به ما می دهند.

💭 انحراف در نام توابع

edit در واقع آنقدرها هم بد نیست زیرا این تابعی است که به ما اجازه می دهد تا محتوا را واقعاً ویرایش کنیم. ولی save اضافه بار شده است. نه تنها محتوای ذخیره شده را می خواند، بلکه آن را نیز ارائه می دهد. و همانطور که در پست های آینده خواهیم دید، عملکردهای دیگر.

بنابراین اگر عادت دارید در مورد نحوه عملکرد عملکرد backend فکر کنید، در این صورت دور از ذهن نخواهید بود:

  • edit برای ویرایش محتوای ذخیره شده در برخی از انواع داده های ذخیره شده است،
  • save جایی است که داده‌ها پاکسازی می‌شوند و در ذخیره‌گاه داده نوشته می‌شوند،
  • read جایی است که داده ها قبل از نمایش بازیابی و تأیید می شوند،
  • و render یا display تابعی برای نمایش نهایی آن به کاربر است.

اما اکنون بلاک ها اینگونه عمل می کنند. حداقل در زمان نوشتن این مقاله نه. در عوض، ما فقط با آن کار می کنیم edit و save. بنابراین این چیزی است که من در ادامه مقاله از آن استفاده خواهم کرد. می توانید در این مورد بیشتر بخوانید ارجاع مطالب در انتهای مقاله

🗺 جایی که داریم می رویم

برای شروع، موارد زیر را انجام می دهیم:

  1. قابلیتی را اضافه کنید تا بلاک را در وردپرس دستکاری کنید،
  2. برای استایل بلاک ما، استایل هایی بنویسید،
  3. آنها را به سردبیر معرفی کنید،
  4. آنها را به جلو معرفی کنید

دلیل انجام این کار ارائه یک مثال ملموس در مورد اینکه چگونه فایل ها و توابع مختلف در توسعه بلوک نقش دارند. درست است، وجود دارد ممکن است زمانی باشد که در آن می‌خواهید چیزی در ویرایشگر یکطرفه ظاهر شود و نه در صفحه اصلی، بلکه هدفی است که من با این سری از مقالات تلاش می‌کنم تا قابلیت‌هایی به ویرایشگر اضافه شود و در بین آنچه نویسنده می‌بیند و آنچه را که می‌بیند یکسان ارائه شود. کاربر می بیند

عملکرد

به یاد بیاورید که در آخرین مقاله، edit تابع به شکل زیر بود:

edit: () => {
    return (
        "This is content from the editor."
    );
},

و این برای نسخه آزمایشی کافی بود اما فقط یک رشته را ارائه می دهد. بیایید آن را کمی پیشرفته تر کنیم به طوری که یک عنصر HTML را ارائه دهد. با این حال، ما باید بیشتر به توسعه بلوک های خاص وردپرس بپردازیم.

طبق معمول، من به همه اینها در مواد مرجع در پایان مقاله پیوند خواهم داد، اما هر مرحله را در حین کار توضیح خواهم داد.

اول، من می خواهم برخی از قابلیت ها را به بلوک خود اضافه کنم. به طور خاص، من به بلوک توانایی حذف، جابجایی، یا به طور کلی تر تغییر در زمینه ویرایشگر می روم.

به این موضوع باید چند نکته را اضافه کنم. در بالای index.js، من نیاز دارم:

import { useBlockProps } from '@wordpress/block-editor';

سپس، در edit تابع، آن را به شکل زیر به روز کنید:

edit: () => {
    const blockProps = useBlockProps({
        className: 'tm-block-demo-container'
    });
    return (
        <div {...blockProps}>
            This is content from the editor.
        </div>
    );
}

بدیهی است که چند مورد در کد بالا وجود دارد که هنوز توضیح داده نشده است (مانند blockProps و className) اما توضیح را لحظه ای دریافت خواهم کرد.

سبک ها

بیایید چند سبک اساسی را به ویرایشگر معرفی کنیم. به عنوان مثال، اجازه دهید بلوک شامل موارد زیر باشد:

  • یک رنگ پس زمینه،
  • یک رنگ حاشیه و حاشیه،
  • یک رنگ فونت خاص،
  • عرض خاص
  • مقداری بالشتک

ابتدا بیایید یک را ایجاد کنیم index.scss فایل در src فهرست راهنما. این فایل به فایل های دیگری مانند block.json، block.php، و index.php. با این حال، قبل از افزودن هر سبکی، باید مطمئن شویم که انتخابگر مناسب را داریم.

بنابراین در این مرحله، ادامه دهید و کد زیر را در آن بنویسید index.scss:

.tm-block-demo-container {
    color: #fff;
    background: #0d63fd;
    border: 1px solid #0a58ca;
    font-weight: bold;
    padding: 0.5em;
    width: 100%;
}

سپس در همان فایل موارد زیر را قرار دهید (من دوست دارم آن را در بالای فایل قرار دهم registerBlockType فراخوانی تابع):

import './index.scss';

کد تا کنون

توجه داشته باشید که در این مرحله موارد زیر در کد اتفاق می افتد:

  • ما در حال حاضر استفاده می کنیم @wordpress/block-editor که بسته‌ای است که به ما امکان می‌دهد با بلوک‌ها در زمینه ویرایشگر بلاک کار کنیم (می‌دانم کمی زائد به نظر می‌رسد 🤷🏻‍♂️).
  • من یک نام کلاس را به useBlockProps عملکرد درون یک شی،
  • من اضافه می کنم blockProps به div عنصر همراه با جاوا اسکریپت spread نحو،
  • من نقل قول‌های رشته را حذف کرده‌ام، زیرا متن استانداردی است که ارائه می‌شود و ترجیح می‌دهم شامل نقل قول نباشد. 🙂

باید بتوانید دارایی ها را بسازید و تغییراتی را در ویرایشگر مشاهده کنید، مانند کنترل ها، و اگر ابزارهای توسعه دهنده خود را باز کنید، خواهید دید که یک نام کلاس سفارشی همراه با بلوک شما وجود دارد.

من توضیح دقیقی در این مورد به همراه کد کامل و اسکرین شات ها در یک لحظه به اشتراک خواهم گذاشت، اما می خواهم ابتدا وارد توضیح شوم.

توضیح

از اولین پست به یاد بیاورید که ما از ساختارشکنی جاوا اسکریپت برای دسترسی به آن استفاده می کنیم useBlockProps از @wordpress/block-editor بسته بندی این تابع خاص به ما اجازه می دهد تا بخوانیم props به یک متغیر (که من به عنوان const blockProps بالا) که به نوبه خود به Block Editor توانایی دستکاری بلوک داخل ویرایشگر را می دهد.

با این حال صبر کنید. چه هستند props و چرا ما آنها را در تمام این کدهای خاص بلوک می بینیم؟ آنها یک ایده مرکزی برای React هستند.

آنها بخشی از مفهوم قابلیت استفاده مجدد هستند. Props جای ویژگی‌های کلاس را می‌گیرد و به شما اجازه می‌دهد تا رابط‌های ثابتی را در سراسر سلسله مراتب مؤلفه ایجاد کنید.

نحوه کار Props در React – راهنمای مبتدیان

و از آنجایی که ما در حال عبور از یک سفارشی هستیم className به تابع اضافه می شود div، همچنین.

پس از تعیین نام کلاس، اما قبل از ایجاد بلوک، سبک هایی را وارد می کنیم که به بلوک اعمال می شوند. این که سبک ها قبلا نوشته شده باشند یا نه مهم نیست. محتویات فایل درج خواهد شد. بنابراین اگر فایل خالی باشد، هیچ چیز آنجا نخواهد بود. اگر فایل شامل سبک‌هایی باشد، آنها اعمال می‌شوند (با فرض اینکه آنچه را که برای هدف‌گیری بلوک خود نیاز دارید در اختیار دارید – در این مورد در یک لحظه بیشتر).

به هر حال کل {...blockProps} چیزی است که کنترل ها را ظاهر می کند تا بتوانیم بلوک را جابجا یا حذف کنیم. به‌طور دقیق‌تر، این ویژگی‌های اضافی را نیز به عنصر اضافه می‌کند تا وردپرس بتواند آن را به هر شکلی که در زمینه برنامه نیاز دارد دستکاری کند.

در نهایت، className ما مشخص کرده‌ایم چیزی است که به ما توانایی استایل دادن به عنصر را می‌دهد، زیرا یک نام کلاس با یک انتخابگر خاص در اختیار ما قرار می‌دهد که می‌توانیم با استفاده از CSS هدف قرار دهیم. اگرچه این کاملا اختیاری است. نمونه موردی: شاید بلاکی بخواهید که به هدف گذاری خاصی نیاز نداشته باشد. در این صورت، چیزی به تابع منتقل نکنید.

نسخه ی نمایشی کار

با فرض اینکه شما تمام کدهایی را که در بالا به اشتراک گذاشته ام اعمال کرده اید، شما index.json در حال حاضر باید به این شکل باشد:

import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps } from '@wordpress/block-editor';

import metadata from './block.json';
const { name } = metadata;

import './index.scss';

registerBlockType(name, {
    edit: () => {
        const blockProps = useBlockProps({
            className: 'tm-block-demo-container'
        });
        return (
            <div {...blockProps}>
                This is content from the editor.
            </div>
        );
    },
    save: () => {
        return (
            "This is content from the frontend."
        );
    }
});

را index.scss فایل باید شامل موارد زیر باشد:

.tm-block-demo-container {
    color: #fff;
    background: #0d63fd;
    border: 1px solid #0a58ca;
    font-weight: bold;
    padding: 0.5em;
    width: 100%;
}

و آخر چیزی که باید به روز کنیم این است block.php به طوری که در واقع شامل دارایی های Block Editor است که می بینیم. برای این کار موارد زیر را به آن فایل اضافه کنید:

add_action(
    'enqueue_block_assets',
    function () {
        wp_enqueue_style(
            'tm-block-demo-styles',
            plugins_url('build/index.css', dirname(__FILE__)),
            ['wp-edit-blocks']
        );
    }
);

این اهرم enqueue_block_assets تابعی برای اضافه کردن سبک های ذکر شده در بالا.

اکنون در ترمینال خود دستور زیر را صادر کنید:

$ npm run build

و با فرض اینکه از آخرین مقاله هیچ تغییری در نصب خود نداشته باشید، باید چیزی شبیه به این را در ویرایشگر خود مشاهده کنید:

اما ظاهر ظاهری همچنان به این صورت است:

حالا که چی؟

Frontend

نکته خوب این است که ما قبلاً در مورد عملکرد، پیاده سازی و توضیح صحبت کرده ایم، بنابراین افزودن عملکردهای مشابه به frontend بی اهمیت است. حداقل در این مرحله.

بنابراین کاری که اکنون باید انجام دهیم این است که کدهای لازم برای frontend را اضافه کنیم.

برای این مثال، تفاوت چندانی با آنچه قبلا داریم ندارد. در واقع، من استدلال می‌کنم که این کمی ساده‌تر است، زیرا کنترل‌های واقعی مانند frontend وجود ندارد. در عوض، این موضوع به روز رسانی است save عملکردی برای منعکس کردن متنی که در ویرایشگر است (اگر این کار را انتخاب کنید) و استایل های مناسب را اعمال کنید.

و به یاد داشته باشید، برای اعمال سبک ها باید مطمئن شویم:

  • ما از جمله درست است blockProps بنابراین نام کلاس برای CSS اضافه می شود،
  • و ما شیوه نامه را در قسمت جلوی بلوک قرار داده ایم.

توجه داشته باشید که در این مثال، من قصد ندارم قابلیتی برای ویرایش متن اضافه کنم. در مقاله بعدی این کار را انجام خواهم داد. با این حال، من توانایی اطمینان از ظاهر نهایی را معرفی خواهم کرد به نظر می رسد مانند آنچه در ویرایشگر می بینیم و این که frontend هر متنی را که در کد تنظیم شده است، رندر می کند.

برای این کار موارد زیر را به آن اضافه می کنیم save عملکرد درست بالاتر از return بیانیه:

const blockProps = useBlockProps.save();

توجه داشته باشید که این بسیار شبیه به کاری است که در آن انجام شده است edit با یک استثنا: ما در حال بازیابی مقادیر از useBlockProps از طریق آن save عملکرد. اما این عملکرد در واقع چه کاری انجام می دهد؟

این تضمین می کند که نام کلاس بلوک به درستی ارائه شود، علاوه بر هر ویژگی HTML تزریق شده توسط بلوک از API پشتیبانی می کند.

لوازم بسته بندی بلوک

به عبارت دیگر، هر ویژگی که از طریق ویرایشگر به بلوک تزریق می شود، هنگام رندر شدن به بلوک اعمال می شود. هنگامی که بلاک پیچیده تر می شود، این بسیار مفیدتر است.

اما در حال حاضر، ما فقط یک نام کلاس جدید برای معرفی داریم. بنابراین، یک بار دیگر با نحو گسترش، اجازه دهید به روز رسانی save عملکرد:

save: () => {
    const blockProps = useBlockProps.save();
    return (
        <div {...blockProps}>
            This is content from the frontend.
        </div>
    );
}

این انتخابگرهای خاصی را اعمال می کند که می توانیم از طریق CSS هدف قرار دهیم، اما باید آنها را به روز کنیم index.scss تا مطمئن شویم که این کار را انجام می دهیم. اگر بلوک را در قسمت جلو از طریق ابزارهای توسعه دهنده خود مشاهده کنید، متوجه خواهید شد که نام کلاس در بلوک .wp-block-tm-tm-block-demo.

پس آپدیت کنید index.scss به این شکل به نظر برسد:

.tm-block-demo-container,
.wp-block-tm-tm-block-demo {
    color: #fff;
    background: #0d63fd;
    border: 1px solid #0a58ca;
    font-weight: bold;
    padding: 0.5em;
    width: 100%;
}

از آنجایی که قبلاً یک تابع ناشناس برای افزودن شیوه نامه خود به ویرایشگر با استفاده از یک هوک طراحی شده برای آن اضافه کرده ایم، عملکرد را در قسمت جلویی نیز دریافت می کنیم.

اکنون دستور زیر را در ترمینال خود برای به روز رسانی دارایی ها اجرا کنید:

$ npm run build

سپس یک کپی جدید از بلوک را به ویرایشگر خود اضافه کنید. شما باید موارد زیر را ببینید:

حالا یا کلیک کنید ذخیره پیش نویس یا انتشار و پست را در مرورگر خود مشاهده کنید. وقتی این کار را انجام می دهید، باید دقیقاً همان چیزی را که در ویرایشگر می بینید به جز محتوای خود بلوک ببینید:

توجه کنید که در اینجا تنها تفاوت این است که نسخه عمومی بلوک چنین می‌گوید: «این محتوا از قسمت ظاهری است». تغییر ویرایشگر بلوک می‌گوید: «این محتوا از ویرایشگر است».

⏭️ TODO

در آخرین مقاله، من مشخص کردم که عملکرد پایه یک بلوک را به گونه ای تنظیم کنم که بتوان آن را به ویرایشگر اضافه کرد و در قسمت جلویی رندر کرد. این مقاله نحوه استایل دادن به مقاله و همچنین افزودن برخی قابلیت‌های استاندارد را توضیح می‌دهد و مطمئن می‌شود که بلوک هم در ویرایشگر در قسمت جلو و هم در قسمت پشتی یکسان ظاهر می‌شود.

در مقاله بعدی، صحبت در مورد اینکه چگونه می‌توانیم متن را در متن Block Editor ویرایش کنیم، چگونه تغییرات را ذخیره کنیم و سپس آنها را در قسمت جلویی مشاهده کنیم، صحبت خواهیم کرد.

📚 مرجع

  • ویرایش و ذخیره کنید. هنگام ثبت یک بلوک، edit و save توابع رابطی را برای نحوه نمایش یک بلوک در ویرایشگر، نحوه عملکرد و دستکاری آن و نحوه ذخیره آن فراهم می کنند.
  • @wordpress/block-editor. این ماژول به شما امکان ایجاد و استفاده از ویرایشگرهای بلوک مستقل را می دهد.
  • enqueue_block_assets. پس از صف بندی دارایی های بلوک برای ویرایشگر و فرانت اند، آتش می گیرد. این به ما امکان می دهد پس از اینکه وردپرس دارایی های خود را اضافه کرد، دارایی های خود را اضافه کنیم.
  • نحوه کار Props در React – راهنمای مبتدیان. Props برای ذخیره داده هایی استفاده می شود که توسط فرزندان یک جزء React قابل دسترسی باشد.
  • نحو را گسترش دهید. دستور Spread اجازه می دهد تا یک تکرار شونده، مانند یک آرایه یا رشته، در مکان هایی گسترش یابد که در آن آرگومان های صفر یا بیشتر (برای فراخوانی تابع) یا عناصر (برای کلمات آرایه) مورد انتظار است.
  • لوازم بسته بندی بلوک. این تضمین می کند که نام کلاس بلوک به درستی ارائه شود، علاوه بر هر ویژگی HTML تزریق شده توسط بلوک از API پشتیبانی می کند.


– تهیه و ترجمه توسط wordpress-templates.ir

سفارش طراحی سایت به وی تی!