شروع با توسعه بلوک وردپرس

بیایید اذعان کنیم که توسعه برای وردپرس در حال حاضر عجیب است. چه در وردپرس تازه کار باشید و چه سال‌ها با آن کار کرده باشید، ویژگی‌های «ویرایش کامل سایت» (FSE) از جمله ویرایشگر مسدود کردن (وردپرس 5.0) و ویرایشگر سایت (WordPress 5.9)، روش سنتی ساخت تم ها و افزونه های وردپرس را تغییر داده اند.

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

مورد اصلی: در سال 2018، یک سری مقدماتی درباره ورود به توسعه گوتنبرگ در اینجا در ترفندهای CSS منتشر شد. زمانه از آن زمان تغییر کرده است، و در حالی که آن سبک توسعه هنوز کار می کند، اما همینطور است توصیه نمیشود دیگر (علاوه بر create-guten-block پروژه ای که بر اساس آن است نیز دیگر حفظ نمی شود).

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

بلوک های وردپرس دقیقا چیست؟

بیایید با بیان برخی سردرگمی‌ها در مورد معنایی که از اصطلاحاتی مانند آن داریم شروع کنیم بلوک. همه توسعه‌هایی که به این ویژگی‌ها منتهی به وردپرس 5.0 شد، با نام رمز «گوتنبرگ- می دانید، مخترع پرس چاپ.

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

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

جدا از این بلوک های اصلی، ما می توانیم بلوک های سفارشی نیز ایجاد کنیم. این همان چیزی است که توسعه بلوک وردپرس در مورد آن است (همچنین بلوک های اصلی فیلتر برای تغییر عملکرد آنها وجود دارد، اما احتمالاً هنوز به آن نیاز نخواهید داشت).

بلوک ها چه کاری انجام می دهند

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

روشی که من دوست دارم در مورد یک بلوک فکر کنم کاملاً انتزاعی است: به نظر من، یک بلوک یک موجودیت است، با برخی ویژگی ها (به نام ویژگی ها) که نشان دهنده محتوایی است. می دانم که این خیلی مبهم به نظر می رسد، اما با من همراه باشید. یک بلوک اساسا خود را به دو صورت نشان می دهد: به عنوان یک رابط گرافیکی در ویرایشگر بلوک یا به عنوان یک تکه داده در پایگاه داده.

وقتی ویرایشگر بلاک وردپرس را باز می‌کنید و یک بلوک، مثلاً بلوک Pullquote را وارد می‌کنید، یک رابط کاربری خوب دریافت می‌کنید. می توانید روی آن رابط کلیک کنید و متن نقل قول را ویرایش کنید. پانل تنظیمات در سمت راست رابط کاربری Block Editor گزینه هایی را برای تنظیم متن و تنظیم ظاهر بلوک ارائه می دهد.

هنگامی که ساختن نقل قول فانتزی خود را تمام کردید و بر روی Publish کلیک کردید، کل پست در پایگاه داده ذخیره می شود. wp_posts جدول. به خاطر گوتنبرگ این چیز جدیدی نیست. همیشه کارها به این صورت بوده است – وردپرس محتوای پست را در یک جدول مشخص در پایگاه داده ذخیره می کند. اما آنچه جدید است این است نمایشی از بلوک Pullquote بخشی از محتوایی است که در آن ذخیره می شود post_content زمینه از wp_posts جدول.

این نمایش چه شکلی است؟ نگاهی بیندازید:

  

    
It is not an exaggeration to say that peas can be described as nothing less than perfect spheres of joy.
    The Encyclopedia of world peas
  

شبیه HTML ساده به نظر می رسد، درست است؟! این، در زبان فنی، بلوک "سریالی" است. به داده های JSON در نظر HTML توجه کنید، "textAlign": "right". این یک صفت - یک ویژگی مرتبط با بلوک

فرض کنید Block Editor را ببندید و مدتی بعد دوباره آن را باز کنید. مطالب از مربوطه post_content فیلد توسط Block Editor بازیابی می شود. سپس ویرایشگر محتوای بازیابی شده را تجزیه می کند و هر کجا که با این مواجه شد:

...

... با صدای بلند با خودش می گوید:

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

به عنوان یک توسعه دهنده بلوک، وظیفه شما این است که:

1. به وردپرس بگویید که می خواهید نوع خاصی از بلوک را با جزئیات فلان و فلان ثبت کنید.
2. فایل جاوا اسکریپت را در اختیار Block Editor قرار دهید که به آن کمک می کند تا بلوک را در ویرایشگر ارائه کند و در عین حال آن را به صورت سریالی در پایگاه داده ذخیره کند.
3. منابع اضافی را که بلوک برای عملکرد مناسب خود نیاز دارد، به عنوان مثال سبک ها و فونت ها فراهم کنید.

نکته ای که باید به آن توجه داشت این است که تمام این تبدیل از داده های سریالی به رابط گرافیکی - و بالعکس - فقط در Block Editor انجام می شود. در قسمت جلویی، محتوا دقیقاً همانطور که ذخیره شده است نمایش داده می شود. بنابراین، به یک معنا، بلوک‌ها روشی جذاب برای قرار دادن داده‌ها در پایگاه داده هستند.

امیدواریم، این به شما در مورد نحوه عملکرد یک بلوک شفافیت بدهد.

بلوک ها فقط پلاگین هستند

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

اما بیایید برای لحظه ای فرض کنیم که شما هرگز یک افزونه وردپرس راه اندازی نکرده اید، چه برسد به یک بلوک. اصلا از کجا شروع می کنی؟

راه اندازی یک بلوک

ما پوشش داده ایم که بلوک ها چیست. بیایید شروع به تنظیم چیزهایی کنیم که یکی بسازیم.

مطمئن شوید که Node را نصب کرده اید

این به شما امکان دسترسی به npm و npx دستورات، کجا npm وابستگی های بلوک شما را نصب می کند و به کامپایل موارد کمک می کند npx دستورات را بدون نصب بر روی بسته ها اجرا می کند. اگر از macOS استفاده می کنید، احتمالاً قبلاً Node دارید و می توانید از آن استفاده کنید nvm برای به روز رسانی نسخه ها اگر از ویندوز استفاده می کنید، باید این کار را انجام دهید Node را دانلود و نصب کنید.

یک پوشه پروژه ایجاد کنید

اکنون، ممکن است با آموزش های دیگری برخورد کنید که مستقیماً به خط فرمان می روند و به شما دستور می دهند بسته ای به نام نصب کنید @wordpress/create-block. این بسته عالی است زیرا یک پوشه پروژه کاملاً تشکیل شده با تمام وابستگی‌ها و ابزارهایی که برای شروع توسعه نیاز دارید را بیرون می‌دهد.

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

اینها فایل هایی هستند که من می خواهم به طور خاص فراخوانی کنم:

• readme.txt: این چیزی شبیه به قسمت جلوی فهرست پلاگین است که معمولاً برای توصیف افزونه و ارائه جزئیات بیشتر در مورد استفاده و نصب استفاده می‌شود. اگر بلوک خود را به دایرکتوری پلاگین وردپرس، این فایل به پر کردن صفحه افزونه کمک می کند. اگر قصد دارید یک مخزن GitHub برای پلاگین بلاک خود ایجاد کنید، ممکن است یک مورد را نیز در نظر بگیرید README.md فایل با همان اطلاعات، بنابراین به خوبی در آنجا نمایش داده می شود.
• package.json: این بسته‌های Node را که برای توسعه لازم هستند تعریف می‌کند. وقتی به نصب رسیدیم آن را کرک می کنیم. در توسعه پلاگین وردپرس کلاسیک، ممکن است به کار با Composer و a composer.json در عوض فایل کنید. این معادل آن است.
• plugin.php: این فایل اصلی افزونه است و بله، PHP کلاسیک است! سرصفحه و ابرداده افزونه خود را در اینجا قرار می دهیم و از آن برای ثبت افزونه استفاده می کنیم.

علاوه بر این فایل ها، این فایل ها نیز وجود دارد src دایرکتوری که قرار است حاوی کد منبع بلوک ما باشد.

داشتن این فایل ها و src دایرکتوری تنها چیزی است که برای شروع نیاز دارید. از آن گروه، به آن توجه کنید ما از نظر فنی فقط به یک فایل نیاز داریم (plugin.php) برای ساخت افزونه. بقیه یا اطلاعات ارائه می دهند یا برای مدیریت محیط توسعه استفاده می شوند.

ذکر شده @wordpress/create-block بسته بندی این فایل ها (و بیشتر) را برای ما فراهم می کند. شما می توانید آن را به عنوان یک ابزار اتوماسیون به جای یک ضرورت در نظر بگیرید. صرف نظر از این، کار را آسان‌تر می‌کند، بنابراین می‌توانید با اجرای زیر یک بلوک را با آن داربست کنید:

npx @wordpress/create-block

وابستگی های بلوکی را نصب کنید

با فرض اینکه سه فایل ذکر شده در قسمت قبل را آماده دارید، نوبت به نصب وابستگی ها می رسد. ابتدا باید وابستگی های مورد نیاز خود را مشخص کنیم. ما این کار را با ویرایش انجام می دهیم package.json. در حالی که از @wordpress/create-block ابزار، موارد زیر برای ما ایجاد شده است (نظرات اضافه شده است؛ JSON از نظرات پشتیبانی نمی کند، بنابراین اگر کد را کپی می کنید، نظرات را حذف کنید):

{
  // Defines the name of the project
  "name": "block-example",
  // Sets the project version number using semantic versioning
  "version": "0.1.0",
  // A brief description of the project
  "description": "Example block scaffolded with Create Block tool.",
  // You could replace this with yourself
  "author": "The WordPress Contributors",
  // Standard licensing information
  "license": "GPL-2.0-or-later",
  // Defines the main JavaScript file
  "main": "build/index.js",
  // Everything we need for building and compiling the plugin during development
  "scripts": {
    "build": "wp-scripts build",
    "format": "wp-scripts format",
    "lint:css": "wp-scripts lint-style",
    "lint:js": "wp-scripts lint-js",
    "packages-update": "wp-scripts packages-update",
    "plugin-zip": "wp-scripts plugin-zip",
    "start": "wp-scripts start"
  },
  // Defines which version of the scripts packages are used (24.1.0 at time of writing)
  // https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/
  "devDependencies": {
    "@wordpress/scripts": "^24.1.0"
  }
}

{
  "name": "block-example",
  "version": "0.1.0",
  "description": "Example block scaffolded with Create Block tool.",
  "author": "The WordPress Contributors",
  "license": "GPL-2.0-or-later",
  "main": "build/index.js",
  "scripts": {
    "build": "wp-scripts build",
    "format": "wp-scripts format",
    "lint:css": "wp-scripts lint-style",
    "lint:js": "wp-scripts lint-js",
    "packages-update": "wp-scripts packages-update",
    "plugin-zip": "wp-scripts plugin-zip",
    "start": "wp-scripts start"
  },
  "devDependencies": {
    "@wordpress/scripts": "^24.1.0"
  }
}

La @wordpress/scripts بسته در اینجا وابستگی اصلی است. همانطور که می بینید، این یک است devDependency به این معنی که به توسعه کمک می کند. چطور؟ را افشا می کند wp-scripts باینری که می‌توانیم از آن برای کامپایل کد خود استفاده کنیم src دایرکتوری به build دایرکتوری، در میان چیزهای دیگر.

تعدادی بسته دیگر وجود دارد که وردپرس برای اهداف مختلف نگهداری می کند. به عنوان مثال @wordpress/components بسته فراهم می کند چندین پیش فاب UI اجزاء برای ویرایشگر بلاک وردپرس که می تواند برای ایجاد تجربیات کاربری ثابت برای بلوک شما که با استانداردهای طراحی وردپرس همسو باشد استفاده شود.

شما در واقع نیست نیاز برای نصب این بسته ها، حتی اگر بخواهید از آنها استفاده کنید. دلیلش این است که اینها @wordpress وابستگی ها با کد بلوک شما همراه نیستند. در عوض، هر import عبارات ارجاع کد از بسته های ابزار - مانند @wordpress/components - برای ساختن یک فایل "دارایی" در حین کامپایل استفاده می شود. علاوه بر این، این عبارات واردات به عباراتی تبدیل می‌شوند که واردات را به ویژگی‌های یک شی سراسری نگاشت می‌کنند. مثلا، import { __ } from "@wordpress/i18n" به نسخه کوچک شده تبدیل می شود const __ = window.wp.i18n.__است. (window.wp.i18n یک شی است که تضمین می شود در محدوده جهانی در دسترس باشد، یک بار مربوطه i18n فایل بسته در صف قرار می گیرد).

در طول ثبت بلوک در فایل افزونه، فایل "دارایی" به طور ضمنی برای اعلام وابستگی بسته به وردپرس برای بلوک استفاده می شود. این وابستگی ها به طور خودکار در صف قرار می گیرند. همه اینها در پشت صحنه مراقبت می شود، به شرطی که از آن استفاده می کنید scripts بسته بندی همانطور که گفته شد، همچنان می‌توانید وابستگی‌ها را برای تکمیل کد و اطلاعات پارامتر در خود نصب کنید. package.json فایل:

// etc.
"devDependencies": {
  "@wordpress/scripts": "^24.1.0"
},
"dependencies": {
  "@wordpress/components": "^19.17.0"
}

حالا که package.json راه اندازی شده است، ما باید بتوانیم تمام آن وابستگی ها را با پیمایش به پوشه پروژه در خط فرمان و اجرا نصب کنیم. npm install.

هدر افزونه را اضافه کنید

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

در اینجا چیزی است @wordpress/create-block برای من برای افزونه ای به نام "Hello World" ایجاد شده است:

<?php
/**
 * Plugin Name:       Block Example
 * Description:       Example block scaffolded with Create Block tool.
 * Requires at least: 5.9
 * Requires PHP:      7.0
 * Version:           0.1.0
 * Author:            The WordPress Contributors
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       css-tricks
 *
 * @package           create-block
 */

این در فایل اصلی افزونه است که می‌توانید آن را هرچه دوست دارید صدا بزنید. شما ممکن است آن را چیزی مانند عمومی بنامید index.php or plugin.php. create-block بسته به طور خودکار آن را هنگام نصب هر چیزی که به عنوان نام پروژه ارائه می دهید، صدا می کند. از آنجایی که من این مثال را "Block Example" نامیدم، بسته به ما یک پاسخ داد block-example.php فایل با این همه چیز

شما می خواهید برخی از جزئیات را تغییر دهید، مانند اینکه خود را نویسنده کنید و غیره. و همه اینها ضروری نیست. اگر من این را از ابتدا می‌گذاشتم، ممکن است چیزی نزدیک‌تر به این به نظر برسد:

<?php
/**
 * Plugin Name:       Block Example
 * Plugin URI:        https://css-tricks.com
 * Description:       An example plugin for learning WordPress block development.
 * Version:           1.0.0
 * Author:            Arjun Singh
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       css-tricks
 */

من به هدف دقیق هر خط وارد نمی شوم زیرا قبلاً یک خط است الگوی به خوبی تثبیت شده در کتابچه راهنمای افزونه وردپرس.

ساختار فایل

ما قبلاً فایل های مورد نیاز بلوک خود را بررسی کرده ایم. اما اگر استفاده می کنید @wordpress/create-block، تعداد زیادی فایل دیگر را در پوشه پروژه خواهید دید.

این چیزی است که در حال حاضر در آنجا وجود دارد:

block-example/
├── build
├── node_modules
├── src/
│   ├── block.json
│   ├── edit.js
│   ├── editor.scss
│   ├── index.js
│   ├── save.js
│   └── style.scss
├── .editorconfig
├── .gitignore
├── block-example.php
├── package-lock.json
├── package.json
└── readme.txt

فوو، این خیلی است! بیایید مطالب جدید را صدا کنیم:

• build/: این پوشه دارایی های کامپایل شده را هنگام پردازش فایل ها برای استفاده تولید دریافت می کند.
• node_modules: این همه وابستگی‌های توسعه‌ای را که هنگام اجرا نصب کرده‌ایم نگه می‌دارد npm install.
• src/: این پوشه کد منبع افزونه را نگه می دارد که کامپایل شده و به آن ارسال می شود build فهرست راهنما. ما هر یک از فایل ها را در اینجا فقط در یک بیت بررسی می کنیم.
• .editorconfig: این شامل تنظیماتی برای تطبیق ویرایشگر کد شما برای سازگاری کد است.
• .gitignore: این یک فایل مخزن استاندارد است که فایل های محلی را که باید از ردیابی کنترل نسخه حذف شوند را شناسایی می کند. شما node_modules قطعا باید در اینجا گنجانده شود.
• package-lock.json: این فایلی است که به صورت خودکار تولید می‌شود و حاوی برای ردیابی به‌روزرسانی‌های بسته‌های موردنیاز است که با آن نصب کرده‌ایم npm install.

مسدود کردن متادیتا

من می خواهم در آن حفاری کنم src دایرکتوری با شما اما ابتدا فقط روی یک فایل در آن تمرکز می کند: block.json. اگر استفاده کرده اید create-block در حال حاضر برای شما وجود دارد. اگر نه، ادامه دهید و آن را ایجاد کنید. وردپرس به سختی متمایل است تا با ارائه ابرداده ای که زمینه وردپرس را برای شناسایی بلوک و ارائه آن در ویرایشگر بلاک فراهم می کند، این روش استاندارد و متعارف برای ثبت یک بلوک باشد.

در اینجا چیزی است @wordpress/create-block برای من ایجاد شد:

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 2,
  "name": "create-block/block example",
  "version": "0.1.0",
  "title": "Block Example",
  "category": "widgets",
  "icon": "smiley",
  "description": "Example block scaffolded with Create Block tool.",
  "supports": {
    "html": false
  },
  "textdomain": "css-tricks",
  "editorScript": "file:./index.js",
  "editorStyle": "file:./index.css",
  "style": "file:./style-index.css"
}

در واقع یک وجود دارد دسته ای از اطلاعات مختلف ما می توانیم در اینجا قرار دهیم، اما تنها چیزی که در واقع مورد نیاز است این است name و title. یک نسخه فوق العاده مینیمال ممکن است به شکل زیر باشد:

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 2,
  "name": "css-tricks/block-example",
  "version": "1.0.0",
  "title": "Block Example",
  "category": "text",
  "icon": "format-quote",
  "editorScript": "file:./index.js",
}

• $schema قالب بندی طرحواره مورد استفاده برای اعتبارسنجی محتوای فایل را تعریف می کند. به نظر یک چیز ضروری است، اما کاملاً اختیاری است زیرا به ویرایشگرهای کد پشتیبانی می‌کند تا نحو را تأیید کنند و سایر امکانات اضافی مانند نکات راهنمای ابزار و تکمیل خودکار را ارائه دهند.
• apiVersion به کدام نسخه از Block API افزونه استفاده می کند. امروز، نسخه 2 جدیدترین است.
• name یک رشته منحصر به فرد مورد نیاز است که به شناسایی افزونه کمک می کند. توجه داشته باشید که من این را با پیشوند گذاشته ام css-tricks/ که من از آن به عنوان فضای نام برای کمک به جلوگیری از درگیری با افزونه های دیگری که ممکن است به همین نام باشند استفاده می کنم. ممکن است به جای آن از چیزی مانند حروف اول خود استفاده کنید (مثلاً as/block-example).
• version چیزی است وردپرس استفاده از آن را پیشنهاد می کند به عنوان یک مکانیسم از بین بردن حافظه پنهان هنگام انتشار نسخه های جدید.
• title فیلد مورد نیاز دیگر است و نامی را تعیین می کند که در هر جایی که افزونه نمایش داده می شود استفاده می شود.
• category بلوک را با بلوک های دیگر گروه بندی می کند و آنها را با هم در ویرایشگر بلاک نمایش می دهد. دسته بندی های موجود فعلی شامل text, media, design, widgets, themeو embed، و حتی می توانید ایجاد کنید دسته های سفارشی.
• icon به شما امکان می دهد چیزی را از بین انتخاب کنید کتابخانه Dashicons برای نمایش بصری بلوک خود در ویرایشگر بلوک. من از format-quote icon](https://developer.wordpress.org/resource/dashicons/#format-quote) از آنجایی که ما در این مثال در حال ساختن نوع pullquote خودمان هستیم. خیلی خوب است که می‌توانیم از آیکون‌های موجود استفاده کنیم، به‌جای اینکه مجبور باشیم آیکون‌های خودمان را بسازیم، اگرچه این مطمئناً امکان‌پذیر است.
• editorScript جایی است که فایل اصلی جاوا اسکریپت، index.js، زندگی می کند.

بلوک را ثبت کنید

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

ثبت بلوک یک فرآیند دوگانه است. ما باید آن را هم در PHP و هم در جاوا اسکریپت ثبت کنیم. برای سمت PHP، فایل اصلی افزونه را باز کنید (block-example.php در این مورد) و موارد زیر را درست بعد از هدر افزونه اضافه کنید:

function create_block_block_example_block_init() {
  register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'create_block_block_example_block_init' );

این همان چیزی است که create-block ابزار برای من ایجاد شده است، بنابراین به همین دلیل است که تابع به این صورت نامگذاری شده است. می توانیم از نام دیگری استفاده کنیم. کلید، دوباره، اجتناب از درگیری با سایر افزونه ها است، بنابراین ایده خوبی است که از فضای نام خود در اینجا استفاده کنید تا آن را تا حد امکان منحصر به فرد کنید:

function css_tricks_block_example_block_init() {
  register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'css_tricks_block_example_block_init' );

چرا ما به آن اشاره می کنیم build دایرکتوری اگر block.json با تمام ابرداده های بلوک موجود است src? دلیلش این است که کد ما هنوز باید کامپایل شود. این scripts بسته کد را از فایل‌های موجود پردازش می‌کند src دایرکتوری و فایل های کامپایل شده مورد استفاده در تولید را در build دایرکتوری، در حالی که همچنین کپی کردن block.json پرونده در این فرآیند است.

خوب، اجازه دهید به سمت جاوا اسکریپت ثبت بلوک برویم. باز کن src/index.js و مطمئن شوید که به شکل زیر است:

import { registerBlockType } from "@wordpress/blocks";

import metadata from "./block.json";
import Edit from "./edit.js";
import Save from "./save.js";

const { name } = metadata;

registerBlockType(name, {
  edit: Edit,
  save: Save,
});

داریم وارد React و JSX land می شویم! این به وردپرس می گوید:

• وارد کنید registerBlockType ماژول از @wordpress/blocks بسته.
• وارد کردن متادیتا از block.json.
• وارد کنید Edit و Save اجزای فایل های مربوطه خود بعداً کد را در آن فایل‌ها قرار می‌دهیم.
• بلوک را ثبت کنید و از آن استفاده کنید Edit و Save مؤلفه هایی برای رندر کردن بلوک و ذخیره محتوای آن در پایگاه داده.

چه خبر از edit و save کارکرد؟ یکی از تفاوت های ظریف توسعه بلوک وردپرس، متمایز کردن "انتهای پشتی" از "انتخاب جلو" است و این توابع برای ارائه محتوای بلوک در آن زمینه ها استفاده می شود، جایی که edit دسته رندر بک اند و save محتوا را از Block Editor به پایگاه داده برای رندر کردن محتوا در قسمت جلویی سایت می نویسد.

یک تست سریع

ما می‌توانیم کارهای سریعی انجام دهیم تا بلاک خود را در ویرایشگر Block کار کرده و در قسمت جلویی رندر شده ببینیم. بیا باز کنیم index.js دوباره و استفاده کنید edit و save توابع برای برگرداندن برخی از محتوای اساسی که نحوه عملکرد آنها را نشان می دهد:

import { registerBlockType } from "@wordpress/blocks";
import metadata from "./block.json";

const { name } = metadata;

registerBlockType(name, {
  edit: () => {
    return (
      "Hello from the Block Editor"
    );
  },
  save: () => {
    return (
      "Hello from the front end"
    );
  }
});

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

ما می توانیم این را با اجرا کامپایل کنیم npm run build در خط فرمان پس از آن، ما به بلوکی به نام "Block Example" در ویرایشگر Block دسترسی داریم:

اگر بلوک را در قسمت محتوا رها کنیم، پیامی را دریافت می کنیم که از آن برمی گردیم edit عملکرد:

اگر پست را ذخیره و منتشر کنیم، باید پیامی را که از آن برمی‌گردانیم دریافت کنیم save عملکرد هنگام مشاهده آن در قسمت جلویی:

ایجاد یک بلوک

به نظر می رسد همه چیز به هم وصل شده است! ما می توانیم به آنچه در آن بودیم برگردیم index.js قبل از آزمایش، اکنون که تأیید کرده ایم کارها کار می کنند:

import { registerBlockType } from "@wordpress/blocks";

import metadata from "./block.json";
import Edit from "./edit.js";
import Save from "./save.js";

const { name } = metadata;

registerBlockType(name, {
  edit: Edit,
  save: Save,
});

توجه کنید که edit و save توابع به دو فایل موجود در گره خورده اند src دایرکتوری که @wordpress/create-block برای ما ایجاد شده است و شامل تمام واردات اضافی مورد نیاز ما در هر فایل است. با این حال، مهمتر از آن، آن فایل ها ایجاد می کنند Edit و Save اجزایی که حاوی نشانه گذاری بلوک هستند.

نشانه گذاری انتهای پشت (src/edit.js)

import { useBlockProps } from "@wordpress/block-editor";
import { __ } from "@wordpress/i18n";

export default function Edit() {
  return (
    

      {__("Hello from the Block Editor", "block-example")}
    
  );
}

ببینید ما آنجا چه کردیم؟ ما در حال واردات لوازم جانبی از @wordpress/block-editor بسته ای که به ما امکان می دهد کلاس هایی تولید کنیم که بعداً می توانیم از آنها برای استایل استفاده کنیم. ما همچنین در حال واردات هستیم __ تابع بین المللی سازی، برای برخورد با ترجمه ها.

نشانه گذاری جلویی (src/save.js)

این یک ایجاد می کند Save کامپوننت و ما تقریباً از همان چیزی استفاده خواهیم کرد src/edit.js با متن کمی متفاوت:

import { useBlockProps } from "@wordpress/block-editor";
import { __ } from "@wordpress/i18n";

export default function Save() {
  return (
    

      {__("Hello from the front end", "block-example")}
    
  );
}

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

بلوک های یک ظاهر طراحی شده

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

متمایز کردن سبک های جلو و عقب

اگر نگاهی به block.json در src دایرکتوری شما دو فیلد مربوط به سبک ها را پیدا خواهید کرد:

• editorStyle مسیر استایل های اعمال شده در انتهای پشتی را فراهم می کند.
• style مسیری برای سبک های مشترک است که هم در قسمت جلویی و هم در قسمت پشتی اعمال می شود.

Kev Quirk مقاله مفصلی دارد که رویکرد او را برای شبیه‌سازی ویرایشگر بک‌اند شبیه رابط کاربری جلویی نشان می‌دهد.

به یاد بیاورید که @wordpress/scripts بسته را کپی می کند block.json زمانی که کد را در فایل پردازش می کند /src دایرکتوری و دارایی های کامپایل شده را در /build فهرست راهنما. آن است build/block.json فایلی که برای ثبت بلوک استفاده می شود. این به معنای هر مسیری است که ما ارائه می دهیم src/block.json باید نسبت به نوشته شود build/block.json.

با استفاده از Sass

می‌توانیم چند فایل CSS را در آن رها کنیم build دایرکتوری، به مسیرهای موجود اشاره کنید src/block.json، بیلد را اجرا کنید و آن را یک روز بنامید. اما این قدرت کامل را به کار نمی گیرد @wordpress/scripts فرآیند کامپایل، که قادر به کامپایل Sass در CSS است. در عوض، فایل های سبک خود را در قسمت قرار می دهیم src دایرکتوری و آنها را در جاوا اسکریپت وارد کنید.

در حین انجام این کار، باید به نحوه انجام آن توجه داشته باشیم @wordpress/scripts سبک های پردازش:

• فایلی به نام style.css or style.scss or style.sass، وارد شده به کد جاوا اسکریپت، به کامپایل می شود style-index.css.
• همه فایل‌های سبک دیگر کامپایل و همراه می‌شوند index.css.

La @wordpress/scripts استفاده های بسته بسته وب برای بسته بندی و @wordpress/scripts با استفاده از پلاگین PostCSS برای کار برای سبک های پردازش PostCSS را می توان با افزونه های اضافی گسترش داد. این scripts بسته از مواردی برای Sass، SCSS و Autoprefixer استفاده می کند که همگی برای استفاده بدون نصب بسته های اضافی در دسترس هستند.

در واقع، زمانی که بلوک اولیه خود را با @wordpress/create-block، با فایل‌های SCSS که می‌توانید از آنها برای ضربه زدن به زمین استفاده کنید، شروع خوبی خواهید داشت:

• editor.scss شامل تمام سبک هایی است که برای ویرایشگر Back-end اعمال می شود.
• style.scss شامل تمام سبک های به اشتراک گذاشته شده توسط هر دو قسمت جلو و عقب است.

حالا بیایید با نوشتن یک Sass که در CSS برای بلوک خود کامپایل می کنیم، این رویکرد را در عمل ببینیم. حتی اگر مثال‌ها خیلی ساده نباشند، من همچنان آنها را در فایل‌های SCSS می‌نویسم تا فرآیند کامپایل را نشان دهم.

جلو و سبک های بک اند

خوب، بیایید با سبک هایی شروع کنیم که هم در قسمت جلویی و هم در قسمت پشتی اعمال می شوند. ابتدا باید ایجاد کنیم src/style.scss (اگر از آن استفاده می کنید قبلاً وجود دارد @wordpress/create-block) و مطمئن شوید که آن را وارد می کنیم، که می توانیم انجام دهیم index.js:

import "./style.scss";

باز کن src/style.scss و چند استایل اصلی را با استفاده از کلاسی که برای ما از ابزارهای بلوک ایجاد شده است، در آنجا رها کنید:

.wp-block-css-tricks-block-example {
  background-color: rebeccapurple;
  border-radius: 4px;
  color: white;
  font-size: 24px;
}

فعلا همین! وقتی بیلد را اجرا می کنیم، این در کامپایل می شود build/style.css و توسط Block Editor و front end ارجاع داده می شود.

سبک های پشتیبان

ممکن است لازم باشد سبک هایی بنویسید که مخصوص ویرایشگر بلاک هستند. برای آن، ایجاد کنید src/editor.scss (از نو، @wordpress/create-block این کار را برای شما انجام می دهد) و چند سبک را در آنجا رها کنید:

.wp-block-css-tricks-block-example {
  background-color: tomato;
  color: black;
}

سپس آن را وارد کنید edit.js، که فایلی است که حاوی ماست Edit کامپوننت (ما می توانیم آن را در هر جایی که بخواهیم وارد کنیم، اما از آنجایی که این سبک ها برای ویرایشگر هستند، منطقی تر است که کامپوننت را در اینجا وارد کنیم):

import "./editor.scss";

حالا وقتی می دویم npm run build، سبک ها در هر دو زمینه به بلوک اعمال می شوند:

سبک های ارجاع در block.json

ما فایل های یک ظاهر طراحی شده را وارد کردیم edit.js و index.js، اما به یاد داشته باشید که مرحله کامپایل دو فایل CSS را برای ما تولید می کند build دایرکتوری: index.css و style-index.css به ترتیب. ما باید به این فایل های تولید شده در ابرداده بلوک ارجاع دهیم.

بیایید چند جمله را به آن اضافه کنیم block.json ابرداده:

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 2,
  "name": "css-tricks/block-example",
  "version": "1.0.0",
  "title": "Block Example",
  "category": "text",
  "icon": "format-quote",
  "editorScript": "file:./index.js",
  "editorStyle": "file:./index.css",
  "style": "file:./style-index.css"
}

دویدن npm run build یک بار دیگر افزونه را در سایت وردپرس خود نصب و فعال کنید و آماده استفاده از آن هستید!

شما می توانید npm run start برای اجرای ساخت خود در حالت تماشا، هر بار که تغییری در کد خود ایجاد می‌کنید و ذخیره می‌کنید، به‌طور خودکار کد خود را کامپایل می‌کند.

ما سطح را می خراشیم

بلوک‌های واقعی از نوار کناری تنظیمات ویرایشگر بلاک و سایر ویژگی‌هایی که وردپرس ارائه می‌کند برای ایجاد تجربیات کاربری غنی استفاده می‌کنند. علاوه بر این، این واقعیت که اساساً دو نسخه از بلوک ما وجود دارد - edit و save - همچنین باید به نحوه سازماندهی کد خود فکر کنید تا از تکرار کد جلوگیری کنید.

اما امیدواریم که این به رفع رمز و راز فرآیند کلی ایجاد بلوک های وردپرس کمک کند. این واقعاً یک دوره جدید در توسعه وردپرس است. یادگیری روش های جدید برای انجام کارها سخت است، اما من مشتاقانه منتظرم تا ببینم چگونه تکامل می یابد. ابزارهایی مانند @wordpress/create-block کمک کند، اما حتی در این صورت هم خوب است که بدانید دقیقاً چه کاری انجام می دهد و چرا.

آیا چیزهایی که در اینجا تحت پوشش قرار داده ایم تغییر خواهند کرد؟ به احتمال زیاد! اما حداقل شما یک خط پایه برای کار دارید زیرا ما به بلوک‌های وردپرس می‌بینیم که شامل بهترین روش‌ها برای ساختن آنها می‌شود.

منابع

مجدداً، هدف من در اینجا ترسیم یک مسیر کارآمد برای ورود به توسعه بلوک در این فصل است که همه چیز به سرعت در حال پیشرفت است و اسناد وردپرس کمی مشکل دارند. در اینجا منابعی وجود دارد که برای جمع آوری این موارد استفاده کردم: