بناء كتل Gutenberg المخصصة: البرنامج التعليمي النهائي لتطوير الكتلة

يشتكي العديد من الأشخاص من عقبات البدء في إنشاء كتل وتطبيقات Gutenberg. منحنى التعلم شديد الانحدار ، ويرجع ذلك أساسًا إلى صعوبة تثبيت بيئة التطوير وتكوينها. بالإضافة إلى ذلك ، فإن المعرفة القوية بجافا سكريبت و Node.js و React و Redux هي مكونات ضرورية لهذه الوصفة المعقدة إلى حد ما.

يوفر كتيب WordPress Block Editor الرسمي للمطورين قدرًا هائلاً من المعلومات ، ولكن قد تجد نفسك تائهًا في بحر التفاصيل هذا.

ومن الجدير بالذكر ما ذكره ماتياس فينتورا ، المهندس الرئيسي لمشروع جوتنبرج ، في مقابلته مع WP Tavern:

في حين أن هناك أشخاصًا يمكنهم تعلمها بسرعة ، إلا أنها لا تزال تشكل حاجزًا كبيرًا أمام الناس. أعتقد أن هناك عدة طبقات لهذا ؛ يمكن أن يكون التوثيق بترتيب من حيث الحجم أفضل في كل من التنظيم والعرض التقديمي. آمل أن نتمكن من فعل الكثير هناك.

مع وضع ذلك في الاعتبار ، قررنا تقديم برنامج تعليمي خطوة بخطوة يهدف إلى مساعدة القراء على البدء في تطوير كتلة Gutenberg.

يبدو مثيرا للاهتمام؟ دعنا نتعمق!

المتطلبات الأساسية لتطوير جوتنبرج بلوك

بالنسبة لهذا البرنامج التعليمي ، فإن المهارات الوحيدة المطلوبة هي معرفة جيدة بتطوير مكون WordPress الإضافي وفهم أساسي على الأقل لـ HTML و CSS و JavaScript و React.

هل سيكون هذا مشروعًا طموحًا؟ أنت تراهن أنه سيكون!

لم يكن من السهل العثور على الحل الوسط المناسب بين الاكتمال والبساطة أو تحديد الموضوعات التي يجب تضمينها وأيها يجب استبعاده.

نأمل أن يسامحنا القراء المتوسطون والمتقدمون لعدم الخوض بعمق في مفاهيم معينة مثل حالة React ، ومتجر Redux ، ومكونات الترتيب العالي ، وما إلى ذلك. تتطلب هذه الموضوعات مساحة إضافية واهتمامًا إضافيًا وربما تكون متقدمة جدًا لبدء تطوير الكتلة (إلا إذا كنت مطور React).

للسبب نفسه ، لن نغطي بعض الموضوعات الأكثر تقدمًا المتعلقة بتطوير كتلة Gutenberg ، مثل الكتل الديناميكية ومربعات التعريف.

مع المعرفة التي ستكتسبها بنهاية هذه المقالة ، ستتمكن من البدء في الاستمتاع والإنتاجية على الفور.

بمجرد أن تبدأ في بناء الكتل ، ستكون مستعدًا لتحسين مهاراتك بشكل أكبر وبناء المزيد من كتل Gutenberg المتقدمة بنفسك.

ما هي كتلة جوتنبرج؟

منذ أن تم إصداره لأول مرة في ديسمبر 2018 ، تم تحسين محرر الكتلة بشكل كبير في جميع الجوانب: واجهات برمجة تطبيقات أكثر قوة ، وواجهة مستخدم أكثر تقدمًا ، وقابلية استخدام محسنة ، والعديد من الكتل الجديدة ، والتطبيقات الأولى لتحرير الموقع الكامل ، وأكثر من ذلك بكثير .

باختصار ، حتى لو كان Gutenberg لا يزال قيد التطوير المكثف ، فقد قطع شوطًا طويلاً - واليوم ، يعد محرر الكتلة مرشحًا كاملاً كمنشئ صفحات وظيفي وموثوق.

من وجهة نظر المطور ، Gutenberg هو تطبيق صفحة واحدة قائم على React (SPA) يسمح لمستخدمي WordPress بإنشاء وتعديل وحذف المحتوى في WordPress. ومع ذلك ، هذا لا ينبغي أن يجعلك تفكر في نسخة محسنة من محرر المحتوى التقليدي.

نريد توضيح ذلك:

في Gutenberg ، يتم تقسيم المحتوى إلى كتل ، وهي "قوالب" يمكن للمستخدمين استخدامها لإنشاء منشورات وصفحات أو مواقع الويب الخاصة بهم بالكامل.

ولكن ما هي الكتلة من الناحية الفنية؟

نحن نحب تعريف WordPress:

"Block" هو المصطلح المجرد المستخدم لوصف وحدات الترميز التي تتكون معًا وتشكل محتوى أو تخطيط صفحة ويب. تجمع الفكرة بين مفاهيم ما نحققه في WordPress اليوم من خلال الرموز القصيرة و HTML المخصص وتضمين الاكتشاف في واجهة برمجة تطبيقات وتجربة مستخدم واحدة متسقة.

العناوين ، والفقرات ، والأعمدة ، والصور ، والمعارض ، وجميع العناصر التي تشكل واجهة المحرر ، من لوحات الشريط الجانبي إلى عناصر تحكم شريط الأدوات ، هي مكونات React.

إذن ، ما هي مكونات React؟ توفر W3Schools التعريف التالي:

المكونات مستقلة وقابلة لإعادة الاستخدام بتات من التعليمات البرمجية. إنها تخدم نفس الغرض مثل وظائف JavaScript ، ولكنها تعمل بمعزل عن ملفات HTML وتعيدها عبر وظيفة render() .

على الرغم من أن تجربة التحرير التي قدمها Gutenberg جديدة مقارنة بمحرر WordPress الكلاسيكي ، فإن الطريقة التي يخزن بها WordPress أجزاء المحتوى الخاصة بك في قاعدة البيانات لا تتغير على الإطلاق. هذا لأن Gutenberg هو تطبيق يعمل داخل WordPress ولكنه لا يغير طريقة عمل CMS في جوهره.

المنشورات (وهذا يشمل المنشورات والصفحات وأنواع المنشورات المخصصة) التي تم إنشاؤها باستخدام Gutenberg لا تزال مخزنة في جدول wp_posts ، تمامًا كما هو الحال مع المحرر الكلاسيكي.

ولكن في منشور تم إنشاؤه باستخدام Gutenberg ، ستجد أجزاء إضافية من المعلومات في الجدول تمثل اختلافًا جوهريًا بين المنشورات التي تم إنشاؤها عبر Classic Editor vs Gutenberg.

تبدو هذه المعلومات مثل تعليقات HTML ، ولها وظيفة محددة: تحديد الكتل:

تخبر محددات الكتلة WordPress بالكتلة التي سيتم عرضها على الشاشة. كما أنها توفر قيمًا لخصائص الكتلة في كائن JSON. تحدد هذه الدعائم الطريقة التي يجب أن يتم بها عرض الكتلة على الشاشة:

إعداد بيئة تطوير WordPress الخاصة بك

يتطلب إعداد بيئة تطوير JavaScript حديثة معرفة قوية بالتقنيات المتقدمة مثل Webpack و React و JSX و Babel و ESLint وما إلى ذلك.

خائف؟ لا تكن! لقد نجح مجتمع WordPress بالفعل في الإنقاذ من خلال توفير أدوات قوية تتيح لك تجنب عملية التكوين اليدوي الفوضوية.

لتبسيط الأمور ، لن نغطي التحويل في هذه المقالة (التي نوصي مع ذلك بالتعرف عليها بمجرد أن تتعلم أساسيات تطوير الكتلة). بدلاً من ذلك ، سنقدم أداتين بديلتين يمكنك استخدامهما لإعداد بيئة تطوير JavaScript حديثة بسرعة وسهولة في غضون دقائق قليلة. الأمر متروك لك لاختيار الشخص الذي تجده أكثر ملاءمة لمشروعك.

يعد إعداد بيئة تطوير JavaScript لإنشاء كتل Gutenberg عملية من ثلاث خطوات:

1. قم بتثبيت Node.js و npm
2. قم بإعداد بيئة التطوير
3. قم بإعداد المكوِّن الإضافي للكتلة

هيا بنا نبدأ.

1. قم بتثبيت Node.js و npm

قبل تثبيت بيئة التطوير الخاصة بك وتسجيل مجموعتك الأولى ، ستحتاج إلى تثبيت Node.js ومدير حزمة Node (npm).

يمكنك تثبيت Node.js و npm بعدة طرق مختلفة. لكن أولاً ، قد ترغب في التحقق مما إذا كان البرنامج مثبتًا بالفعل على جهازك.

للقيام بذلك ، قم بتشغيل Terminal وقم بتشغيل الأمر التالي:

 node -v

إذا كانت النتيجة غير command not found ، فهذا يعني أن Node.js غير مثبت على جهاز الكمبيوتر الخاص بك ، ويمكنك متابعة التثبيت.

بالنسبة لهذه المقالة ، اخترنا أسهل خيار تثبيت ، وهو Node Installer. كل ما عليك فعله هو تنزيل الإصدار المطابق لنظام التشغيل الخاص بك وتشغيل معالج التثبيت:

بمجرد تثبيت Node.js ، قم بتشغيل node -v في جهازك الطرفي مرة أخرى. يمكنك أيضًا تشغيل الأمر npm -v لتأكيد توفر حزمة npm.

أنت الآن مجهز بالأدوات التالية:

• عداء الحزمة npx Node.js (انظر المستندات). يتيح لك هذا تشغيل أمر npm دون تثبيته أولاً.
• مدير الحزم npm Node.js (انظر المستندات). يستخدم هذا لتثبيت التبعيات وتشغيل البرامج النصية.

الخطوة التالية هي تثبيت بيئة التطوير.

2. إعداد بيئة التطوير الخاصة بك

بمجرد حصولك على أحدث إصدارات Node.js و npm على جهازك المحلي ، ستحتاج إلى بيئة تطوير لـ WordPress.

يمكنك إما استخدام بيئة تطوير محلية مثل DevKinsta أو استخدام أداة WordPress الرسمية. دعنا نلقي نظرة خاطفة على كلا الخيارين.

الخيار 1: بيئة التنمية المحلية (DevKinsta)

بنقرات قليلة فقط ، يمكنك تثبيت WordPress محليًا باستخدام DevKinsta ، أداة تطوير WordPress المحلية الحديثة الخاصة بنا. أو يمكنك اختيار أداة تطوير محلية مختلفة ، مثل MAMP أو XAMPP:

الخيار 2: wp-env

يمكنك أيضًا اختيار أداة wp-env الرسمية ، والتي توفر بيئة تطوير WordPress محلية يمكنك تشغيلها مباشرة من سطر الأوامر. يعرّفها نوح ألين على النحو التالي:

أصبحت بيئات WordPress المحلية الآن بسيطة مثل تشغيل أمر واحد. wp-env هي أداة تكوين صفرية لبيئات WordPress المحلية غير المؤلمة. يوفر قرارات بشأن الخيارات حتى يتمكن المستخدمون من إنشاء WordPress بسرعة دون إضاعة الوقت. في الواقع ، الهدف هو جعل هذه البيئات في متناول الجميع - سواء كنت مطورًا أو مصممًا أو مديرًا أو أي شخص آخر.

إذا قررت تجربته ، فإن تثبيت wp-env يتطلب أقل جهد ممكن. ما عليك سوى اتباع هذه الخطوات:

الخطوة 1: تأكيد تثبيت Docker و Node.js

لتلبية المتطلبات الفنية ، ستحتاج أولاً إلى تثبيت كل من Docker و Node.js على جهاز الكمبيوتر الخاص بك. ذلك لأن wp-env يقوم بإنشاء مثيل Docker يقوم بتشغيل موقع WordPress على الويب. تنعكس أي تغييرات يتم إجراؤها على الكود على الفور في نسخة WordPress.

الخطوة 2: قم بتثبيت @wordpress/env من سطر الأوامر

مع تشغيل Docker و Node.js على جهاز الكمبيوتر الخاص بك ، يمكنك الانتقال إلى بيئة تطوير WordPress وتثبيتها.

يمكنك تثبيت wp-env إما عالميًا أو محليًا. للقيام بذلك بشكل عام ، ستحتاج إلى تشغيل الأمر التالي من داخل دليل المكونات الإضافية (المزيد حول هذا في مربع الإشعار "هام" أدناه):

 npm install -g @wordpress/env

دعنا نقسم ذلك:

• يقوم npm install بتثبيت الحزمة.
• -g إلحاق الأمر بتثبيت الحزمة المحددة عالميًا.
• @wordpress/env هي الحزمة التي ستقوم بتثبيتها.

لتأكيد wp-env بنجاح ، قم بتشغيل الأمر التالي:

 wp-env --version

يجب أن تشاهد إصدار wp-env الحالي ، مما يعني أنه يمكنك الآن تشغيل البيئة باستخدام الأمر التالي من مجلد المكون الإضافي الخاص بك:

 wp-env start

يمكنك الوصول إلى لوحة تحكم WordPress باستخدام العنوان التالي:

• http: // localhost: 8888 / wp-admin /

بيانات الاعتماد الافتراضية هي كما يلي:

• اسم المستخدم: admin
• كلمة المرور: password

قم بإعداد البرنامج المساعد بلوك الخاص بك

أنت الآن بحاجة إلى مكون إضافي لكتلة المبتدئين للبناء عليه. ولكن بدلاً من إنشاء مكون إضافي لكتلة التطوير يدويًا مع جميع الملفات والمجلدات الضرورية ، يمكنك ببساطة تشغيل أداة التطوير التي توفر جميع الملفات والتكوينات التي تحتاجها لبدء تطوير الكتلة.

مرة أخرى ، لديك خياران للاختيار من بينها. دعونا نلقي نظرة على كل منها.

الخيار 1: إعداد Block Plugin باستخدام @ wordpress / create-block

@ wordpress / create-block هي أداة التكوين الصفرية الرسمية لإنشاء كتل Gutenberg:

إنشاء كتلة هي طريقة مدعومة رسميًا لإنشاء كتل لتسجيل كتلة لمكوِّن إضافي لبرنامج WordPress. إنه يوفر إعداد بناء حديث بدون تكوين. يقوم بإنشاء كود PHP و JS و CSS وكل ما تحتاجه لبدء المشروع.

إنه مستوحى إلى حد كبير من تطبيق create-react-app. تنويه كبير إلىgaearon وفريق Facebook بأكمله ومجتمع React.

بمجرد تشغيل بيئتك المحلية ، يمكنك إعداد مجموعة بدء التشغيل ببساطة عن طريق تشغيل الأمر npx @wordpress/create-block ، وستوفر جميع الملفات والمجلدات التي تحتاجها لإنشاء سقالات البرنامج المساعد وتسجيل كتلة جديدة .

دعونا نجري اختبارًا لنرى كيف يعمل.

من أداة سطر الأوامر ، انتقل إلى الدليل / wp-content / plugins / وقم بتشغيل الأمر التالي:

 npx @wordpress/create-block my-first-block

عندما يُطلب منك التأكيد ، أدخل y للمتابعة:

تستغرق العملية لحظات قليلة. عند اكتماله ، يجب أن تحصل على الاستجابة التالية:

وهذا كل شيء!

الآن قم بتشغيل بيئة تطوير WordPress الخاصة بك وانتقل إلى شاشة المكونات الإضافية في لوحة معلومات WordPress. يجب إضافة مكون إضافي جديد يسمى "My First Block" إلى قائمة المكونات الإضافية الخاصة بك:

قم بتنشيط المكون الإضافي إذا لزم الأمر ، وأنشئ منشور مدونة جديد ، وقم بالتمرير لأسفل في أداة إدخال الكتلة إلى قسم الأدوات ، وحدد الكتلة الجديدة:

عد الآن إلى المحطة وقم بتغيير الدليل الحالي إلى my-first-block :

 cd my-first-block

ثم قم بتشغيل الأمر التالي:

 npm start

يمكّنك هذا من تشغيل المكون الإضافي في وضع التطوير. لإنشاء كود الإنتاج ، يجب عليك استخدام الأمر التالي:

 npm run build

الخيار 2: إعداد مكون إضافي بلوك باستخدام block-guten-block

create-guten-block هي أداة تطوير تابعة لجهة خارجية لبناء كتل Gutenberg:

create-guten-block هي مجموعة أدوات dev-config الصفرية (# 0CJS) لتطوير كتل WordPress Gutenberg في غضون دقائق دون تكوين React و webpack و ES6 / 7/8 / Next و ESLint و Babel وما إلى ذلك.

تمامًا مثل أداة create- create-block الرسمية ، يعتمد create-guten-block على إنشاء تطبيق تفاعل ويمكن أن يساعدك في إنشاء أول مكون إضافي للكتلة دون أي متاعب.

توفر مجموعة الأدوات كل ما تحتاجه لإنشاء مكون إضافي حديث لـ WordPress ، بما في ذلك ما يلي:

• دعم بناء جملة React و JSX و ES6.
• webpack dev / عملية بناء الإنتاج خلف الكواليس.
• إضافات اللغة خارج ES6 مثل عامل انتشار الكائن.
• CSS مسبوقة تلقائيًا ، لذلك لا تحتاج إلى -webkit أو بادئات أخرى.
• برنامج نصي لتجميع JS و CSS والصور للإنتاج مع خرائط المصدر.
• تحديثات خالية من المتاعب للأدوات المذكورة أعلاه مع تبعية واحدة cgb-scripts.

لاحظ التحذير التالي:

المفاضلة هي أن هذه الأدوات مهيأة مسبقًا للعمل بطريقة معينة. إذا كان مشروعك يحتاج إلى مزيد من التخصيص ، فيمكنك "إخراجه" وتخصيصه ، ولكن بعد ذلك ستحتاج إلى الحفاظ على هذا التكوين.

بمجرد أن يكون لديك موقع WordPress محلي في متناول اليد ، قم بتشغيل أداة Command Line الخاصة بك ، وانتقل إلى مجلد / wp-content / plugins الخاص بالتثبيت ، وقم بتشغيل الأمر التالي:

 npx create-guten-block my-first-block

سيتعين عليك الانتظار لمدة دقيقة أو دقيقتين أثناء إنشاء هيكل المشروع وتنزيل التبعيات:

عند اكتمال العملية ، سترى الشاشة التالية:

تُظهر هذه الصورة التالية هيكل المشروع مع تشغيل المحطة في Visual Studio Code:

عد الآن إلى لوحة تحكم WordPress الخاصة بك. يجب أن يتم إدراج عنصر جديد في شاشة الملحقات - إنه المكون الإضافي الخاص بي الأول :

قم بتنشيط المكون الإضافي والعودة إلى الجهاز. قم بتغيير الدليل الحالي إلى my-first-block ، ثم قم بتشغيل npm start :

 cd my-first-block npm start

يجب أن تحصل على الرد التالي:

مرة أخرى ، يمكّنك هذا من تشغيل المكون الإضافي في وضع التطوير. لإنشاء كود الإنتاج ، يجب عليك استخدام:

 npm run build

قم بتنشيط المكون الإضافي وأنشئ منشورًا أو صفحة جديدة ، ثم تصفح كتلك وحدد كتلة Gutenberg الجديدة تمامًا:

للحصول على نظرة عامة أكثر تفصيلاً أو في حالة وجود أخطاء ، راجع الوثائق التي قدمها أحمد عويس.

تجول لسقالات بلوك المبتدئين

أيًا كانت أداتي التطوير - create-block أو create-guten-block - التي تختارها ، لديك الآن سقالات كتلة يمكنك استخدامها كنقطة بداية لبناء مكون إضافي.

ولكن ما هي بالضبط كتلة السقالات؟

Block scaffolding هو مصطلح مختصر يصف بنية الدليل الداعمة التي تحتاجها لـ WordPress للتعرف على الكتلة. يشتمل هذا الدليل عادةً على ملفات مثل index.php و index.js و style.css وغيرها - والتي بدورها تؤدي إلى تعليق المكالمات مثل register_block_type .

اخترنا أداة Create Block dev-الرسمية ، كما هي مستخدمة في دليل Block Editor Handbook. ولكن حتى إذا قررت استخدام أداة خارجية مثل create-guten-block ، فلن تكون تجربتك مختلفة كثيرًا.

مع ذلك ، دعنا نتعمق أكثر في أداة create-block .

نظرة فاحصة على أداة إنشاء بلوك ديف

كما ذكرنا أعلاه ، فإن Create Block هي أداة سطر الأوامر الرسمية لإنشاء كتل Gutenberg. يؤدي تشغيل @wordpress/create-block في جهازك الطرفي إلى إنشاء ملفات PHP و JS و SCSS والأكواد اللازمة لتسجيل نوع كتلة جديد:

 npx @wordpress/create-block [options] [slug]

• [slug] (اختياري) - تُستخدم لتعيين سبيكة الكتلة وتثبيت البرنامج المساعد
• [options] (اختياري) - الخيارات المتاحة

بشكل افتراضي ، يتم تعيين قالب ESNext. هذا يعني أنك ستحصل على الإصدار التالي من JavaScript ، مع إضافة بناء جملة JSX.

إذا حذفت اسم الكتلة ، فسيتم تشغيل الأمر في الوضع التفاعلي ، مما يتيح لك تخصيص العديد من الخيارات قبل إنشاء الملفات:

 npx @wordpress/create-block

تُظهر الصورة أدناه بنية ملف مكون إضافي كتلة تم إنشاؤه باستخدام أداة Create Block الرسمية:

مع ذلك ، دعنا ننتقل إلى الملفات والمجلدات الرئيسية للمكوِّن الإضافي الجديد.

ملف البرنامج المساعد

باستخدام ملف البرنامج المساعد الرئيسي ، تقوم بتسجيل الكتلة على الخادم:

 /** * Plugin Name: My First Block * Description: Example block written with ESNext standard and JSX support – build step required. * Requires at least: 5.8 * 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: my-first-block * * @package create-block */ /** * Registers the block using the metadata loaded from the `block.json` file. * Behind the scenes, it registers also all assets so they can be enqueued * through the block editor in the corresponding context. * * @see https://developer.wordpress.org/block-editor/tutorials/block-tutorial/writing-your-first-block-type/ */ function create_block_my_first_block_block_init() { register_block_type( __DIR__ ); } add_action( 'init', 'create_block_my_first_block_block_init' );

register_block_type وظيفة register_block_type نوع كتلة على الخادم باستخدام البيانات الوصفية المخزنة في ملف block.json .

تأخذ الوظيفة معلمتين:

• اسم نوع الكتلة متضمنًا مساحة الاسم ، أو مسارًا للمجلد حيث يوجد ملف block.json ، أو كائن WP_Block_Type كامل
• مصفوفة من وسيطات نوع الكتلة

في الكود أعلاه ، يتم توفير وسيطة نوع الكتلة بواسطة الثابت السحري __DIR__ . هذا يعني أن ملف block.json موجود في نفس المجلد مثل ملف البرنامج المساعد.

ملف package.json

يعرّف ملف package.json خصائص JavaScript والبرامج النصية لمشروعك. هذا هو المكان الذي يمكنك فيه تثبيت تبعيات مشروعك.

لفهم الغرض من هذا الملف بشكل أفضل ، افتحه باستخدام محرر الكود المفضل لديك:

 { "name": "my-first-block", "version": "0.1.0", "description": "Example block written with ESNext standard and JSX support – build step required.", "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", "start": "wp-scripts start", "packages-update": "wp-scripts packages-update" }, "dependencies": { "@wordpress/block-editor": "^7.0.1", "@wordpress/blocks": "^11.0.1", "@wordpress/i18n": "^4.2.1" }, "devDependencies": { "@wordpress/scripts": "^18.0.0" } }

خاصية scripts عبارة عن قاموس يحتوي على أوامر يتم تشغيلها في أوقات مختلفة في دورة حياة الحزمة باستخدام npm run [cmd] .

في هذه المقالة ، سنستخدم الأوامر التالية:

• npm run build - إنشاء بناء إنتاج (مضغوط)
• npm run start - إنشاء بناء تطوير (غير مضغوط)

dependencies و devDependencies اسم حزمة إلى إصدار. dependencies مطلوبة في الإنتاج ، في حين أن devDependences مطلوبة فقط للتنمية المحلية (اقرأ المزيد).

تبعية dev الافتراضية الوحيدة هي حزمة @wordpress/scripts ، والتي يتم تعريفها على أنها "مجموعة من البرامج النصية القابلة لإعادة الاستخدام والمخصصة لتطوير WordPress."

ملف block.json

بدءًا من WordPress 5.8 ، يعد ملف البيانات الوصفية block.json هو الطريقة الأساسية لتسجيل أنواع الكتل.

يوفر وجود ملف block.json العديد من الفوائد ، بما في ذلك تحسين الأداء وإمكانية رؤية أفضل على دليل مكونات WordPress الإضافية:

من منظور الأداء ، عندما تدعم السمات أصول التحميل البطيئة ، فإن الكتل المسجلة في block.json سيتم تحسين قوائم الأصول الخاصة بها خارج الصندوق. سيتم وضع أصول CSS و JavaScript للواجهة الأمامية المدرجة في خصائص style أو script في قائمة الانتظار فقط عندما تكون الكتلة موجودة على الصفحة ، مما يؤدي إلى تقليل أحجام الصفحات.

يؤدي تشغيل الأمر @wordpress/create-block إلى إنشاء ملف block.json التالي:

 { "apiVersion": 2, "name": "create-block/my-first-block", "version": "0.1.0", "title": "My First Block", "category": "widgets", "icon": "smiley", "description": "Example block written with ESNext standard and JSX support – build step required.", "supports": { "html": false }, "textdomain": "my-first-block", "editorScript": "file:./build/index.js", "editorStyle": "file:./build/index.css", "style": "file:./build/style-index.css" }

فيما يلي القائمة الكاملة للخصائص الافتراضية:

• apiVersion - إصدار API المستخدم بواسطة الكتلة (الإصدار الحالي هو 2)
• name - معرف فريد للكتلة بما في ذلك مساحة الاسم
• version - الإصدار الحالي من الكتلة
• title - عنوان عرض للكتلة
• category - فئة كتلة
• icon - سبيكة Dashicon أو رمز SVG مخصص
• description - وصف موجز مرئي في مفتش الكتلة
• supports - مجموعة من الخيارات للتحكم في الميزات المستخدمة في المحرر
• textdomain - مجال نص البرنامج المساعد
• editorScript - تعريف المحرر النصي
• editorStyle - تعريف أسلوب المحرر
• style - يوفر أنماطًا بديلة للكتلة

بالإضافة إلى الخصائص المذكورة أعلاه ، يمكنك (وربما ستفعل) تحديد كائن attributes يوفر معلومات حول البيانات المخزنة بواسطة كتلتك. في block.json الخاص بك ، يمكنك تعيين أي عدد من السمات في أزواج المفتاح / القيمة ، حيث يكون المفتاح هو اسم السمة والقيمة هي تعريف السمة.

ألق نظرة على المثال التالي لتعريفات السمات:

 "attributes": { "content": { "type": "array", "source": "children", "selector": "p" }, "align": { "type": "string", "default": "none" }, "link": { "type": "string", "default": "https://kinsta.com" } },

سوف نتعمق أكثر في ملف block.json لاحقًا في المقالة ، ولكن قد ترغب أيضًا في التحقق من دليل Block Editor للحصول على معلومات أكثر تفصيلاً حول البيانات الوصفية والسمات block.json .

المجلد src

مجلد src هو المكان الذي يحدث فيه التطوير. ستجد في هذا المجلد الملفات التالية:

• index.js
• تحرير. js
• save.js
• editor.scss
• style.scss

index.js

ملف index.js هو نقطة البداية. هنا سوف تقوم باستيراد التبعيات وتسجيل نوع الكتلة على العميل:

 import { registerBlockType } from '@wordpress/blocks'; import './style.scss'; import Edit from './edit'; import save from './save'; registerBlockType('create-block/my-first-block', { edit: Edit, save, });

تستورد العبارة الأولى الدالة registerBlockType من الحزمة @wordpress/blocks . تستورد عبارات الاستيراد التالية ورقة الأنماط مع وظائف Edit save .

registerBlockType الدالة registerBlockType المكون على العميل. تأخذ الوظيفة معلمتين: namespace/block-name (نفس الاسم المسجل على الخادم) وكائن تكوين الكتلة.

توفر وظيفة Edit واجهة الكتلة كما تظهر في محرر الكتلة ، بينما save وظيفة الحفظ البنية التي سيتم تسلسلها وحفظها في قاعدة البيانات (اقرأ المزيد).

تحرير. js

Edit.js هو المكان الذي ستنشئ فيه واجهة مسؤول الكتلة:

 import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit() { return ( <p {...useBlockProps()}> {__('My First Block – hello from the editor!', 'my-first-block')} </p> ); }

أولاً ، تستورد الدالة __ من الحزمة @wordpress/i18n (تحتوي هذه الحزمة على نسخة JavaScript لوظائف الترجمة) ، و useBlockProps hook ، وملف editor.scss .

بعد ذلك ، يقوم بتصدير مكون React (اقرأ المزيد عن بيانات الاستيراد والتصدير).

save.js

ملف save.js هو المكان الذي نبني فيه بنية الكتلة ليتم حفظها في قاعدة البيانات:

 import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; export default function save() { return ( <p {...useBlockProps.save()}> {__( 'My First Block – hello from the saved content!', 'my-first-block' )} </p> ); }

editor.scss و style.scss

بصرف النظر عن البرامج النصية ، يوجد ملفان SASS في مجلدات src . يحتوي ملف editor.scss على الأنماط المطبقة على الكتلة في سياق المحرر ، بينما يحتوي ملف style.scss على أنماط الكتلة لعرضها في الواجهة الأمامية. سوف نتعمق أكثر في هذه الملفات في الجزء الثاني من هذا الدليل.

node_modules وبناء المجلدات

يحتوي المجلد node_modules على وحدات العقدة وتبعياتها. لن نتعمق أكثر في حزم العقد لأنه خارج نطاق هذه المقالة ، ولكن يمكنك قراءة المزيد في هذه المقالة حول مكان تثبيت npm للحزم.

يحتوي مجلد build على ملفات JS و CSS الناتجة عن عملية الإنشاء. يمكنك التعمق في عملية الإنشاء في بناء جملة ESNext وأدلة إعداد JavaScript Build.

المشروع: بناء أول بلوك في جوتنبرج

حان الوقت لتتسخ أيدينا. سيعلمك هذا القسم كيفية إنشاء مكون إضافي يوفر كتلة CTA باسم Affiliate Block.

ستتألف الكتلة من عمودين ، مع صورة على اليسار وفقرة نصية على اليمين. سيتم وضع زر مع ارتباط قابل للتخصيص أسفل النص:

هذا مجرد مثال بسيط ، لكنه يسمح لنا بتغطية أساسيات تطوير كتلة جوتنبرج. بمجرد حصولك على فهم واضح للأساسيات ، يمكنك المضي قدمًا وإنشاء المزيد والمزيد من كتل Gutenberg المعقدة بمساعدة دليل Block Editor وأي من الموارد الهائلة المتاحة هناك.

بافتراض أن لديك أحدث إصدار من WordPress يعمل على بيئة التطوير المحلية الخاصة بك ، فإليك ما ستتعلمه من الآن فصاعدًا:

• كيفية إعداد البرنامج المساعد Starter Block
• block.json في العمل
• استخدام المكونات المضمنة: مكون RichText
• إضافة عناصر تحكم إلى شريط أدوات الحظر
• تخصيص الشريط الجانبي لإعدادات الحظر
• إضافة رابط خارجي وتخصيصه
• إضافة أنماط كتل متعددة
• تداخل الكتل مع مكون InnerBlocks
• تحسينات إضافية

جاهز ... ضع ... انطلق!

كيفية إعداد البرنامج المساعد Starter Block

قم بتشغيل أداة سطر الأوامر الخاصة بك وانتقل إلى مجلد / wp-content / plugins :

الآن ، قم بتشغيل الأمر التالي:

 npx @wordpress/create-block

ينشئ هذا الأمر ملفات PHP و SCSS و JS لتسجيل كتلة في الوضع التفاعلي ، مما يسمح لك بإضافة البيانات الضرورية لحجبتك بسهولة. على سبيل المثال لدينا سوف نستخدم التفاصيل التالية:

• كتلة سبيكة : بلدي - التابعة كتلة
• مساحة الاسم الداخلية : my-affiliate-plugin
• عنوان عرض الحظر : كتلة تابعة
• وصف قصير للكتلة : مثال على كتلة لقراء Kinsta
• Dashicon : المال
• اسم التصنيف : التصميم
• مؤلف البرنامج المساعد : اسمك
• الترخيص : -
• رابط نص الترخيص : -
• إصدار البرنامج المساعد الحالي : 0.1.0

يستغرق تثبيت البرنامج المساعد وجميع التبعيات بضع دقائق. عند اكتمال العملية ، سترى الاستجابة التالية:

الآن ، قم بتشغيل الأمر التالي من مجلد / wp-content / plugins :

 cd my-affiliate-block

أخيرًا ، من داخل مجلد المكون الإضافي الخاص بك ( my-affiliate-block في مثالنا) ، يمكنك بدء التطوير باستخدام:

 npm start

افتح الآن شاشة الملحقات للعثور على المكون الإضافي Affiliate Block وتنشيطه:

قم بإنشاء منشور جديد ، وافتح أداة إدراج الكتلة ، وانتقل لأسفل إلى فئة التصميم . انقر لإضافة كتلة الانتساب:

block.json في العمل

كما ذكرنا سابقًا ، يتم تسجيل الكتلة من جانب الخادم في ملف .php الرئيسي. ومع ذلك ، فإننا لن نحدد الإعدادات في ملف .php . بدلاً من ذلك ، سنستخدم ملف block.json .

لذا ، افتح block.json مرة أخرى وألق نظرة فاحصة على الإعدادات الافتراضية:

 { "apiVersion": 2, "name": "my-affiliate-plugin/my-affiliate-block", "version": "0.1.0", "title": "Affiliate Block", "category": "design", "icon": "money", "description": "An example block for Kinsta readers", "supports": { "html": false }, "textdomain": "my-affiliate-block", "editorScript": "file:./build/index.js", "editorStyle": "file:./build/index.css", "style": "file:./build/style-index.css" }

البرامج النصية والأنماط

توفر خصائص editorScript و editorStyle و style المسارات النسبية لنصوص وأنماط الواجهة الأمامية والخلفية.

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

كما ترى من الصورة أعلاه ، تمت إضافة نص index.js الخاص بنا الموجود في مجلد الإنشاء إلى قائمة الانتظار بانتظام دون الحاجة إلى إضافة أي كود PHP .

تسميات واجهة المستخدم

توفر خصائص title description التسميات اللازمة لتحديد الكتلة في المحرر:

الكلمات الدالة

كما ذكرنا سابقًا ، يمكنك تكوين إعدادات الحظر بدقة باستخدام الخصائص والسمات. على سبيل المثال ، يمكنك إضافة keywords واحدة أو أكثر لمساعدة المستخدمين في كتل البحث:

 { "keywords": [ "kinsta", "affiliate", "money" ] }

If you now input “kinsta”, “affiliate” or “money” in the quick inserter, the editor will suggest you the Affiliate block:

الموقع

If you are wondering how the localization of the strings in the JSON file happens, here is the answer:

In JavaScript, you can use now registerBlockTypeFromMetadata method from @wordpress/blocks package to register a block type using the metadata loaded from block.json file. All localized properties get automatically wrapped in _x (from @wordpress/i18n package) function calls similar to how it works in PHP with register_block_type_from_metadata . The only requirement is to set the textdomain property in the block.json file.

Here we are using the registerBlockType function instead of registerBlockTypeFromMetadata , as the latter has been deprecated since Gutenberg 10.7, but the mechanism is the same.

Using Built-In Components: The RichText Component

The elements that make up a Gutenberg block are React components, and you can access these components via the wp global variable. For example, try to type wp.editor into your browser's console. This will give you the full list of the components included in the wp.editor module.

Scroll through the list and guess what components are meant for by their names.

Similarly, you can check the list of components included in the wp.components module:

Now go back to the edit.js file and take a closer look at the script:

import { __ } from '@wordpress/i18n'; import { useBlockProps } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit() { return ( <p {...useBlockProps()}> {__('My First Block – hello from the editor!', 'my-first-block')} </p> ); }

ينشئ هذا الرمز كتلة ثابتة بنص بسيط غير قابل للتحرير. لكن يمكننا تغيير الأشياء بسهولة:

لجعل النص قابلاً للتحرير ، سيتعين عليك استبدال علامة <p> الحالية بمكون يجعل محتوى الإدخال قابلاً للتحرير. لذلك ، يوفر Gutenberg مكون RichText المدمج.

إضافة مكون مدمج إلى كتلتك هي عملية من 5 خطوات:

1. استيراد المكونات المطلوبة من حزمة WordPress
2. قم بتضمين العناصر المقابلة في كود JSX الخاص بك
3. حدد السمات الضرورية في ملف block.json
4. تحديد معالجات الحدث
5. حفظ البيانات

الخطوة 1: استيراد المكونات المطلوبة من حزمة WordPress

افتح الآن ملف edit.js وقم بتغيير بيان import التالي:

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

…ل:

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

بهذه الطريقة ، تقوم باستيراد وظيفة useBlockProps RichText من حزمة @wordpress/block-editor .

useBlockProps

يشير الخطاف useBlockProps إلى عنصر غلاف الكتلة:

عند استخدام الإصدار 2 من API ، يجب عليك استخدام الخطاف useBlockProps الجديد في وظيفة edit الكتلة لتمييز عنصر غلاف الكتلة. سيقوم الخطاف بإدراج السمات ومعالجات الأحداث اللازمة لتمكين سلوك الكتلة. أي سمات ترغب في تمريرها إلى عنصر الكتلة يجب أن تمر عبر useBlockProps القيمة المُعادة في العنصر.

لوضع الأمور ببساطة ، useBlockProps تلقائيًا بتعيين سمات وفئات لعنصر الغلاف (العنصر p في مثالنا):

إذا قمت بإزالة useBlockProps من عنصر التضمين ، فسيكون لديك سلسلة نصية بسيطة بدون وصول إلى وظيفة وأسلوب الحظر:

كما سنشرح لاحقًا ، يمكنك أيضًا أن تمرر إلى useBlockProps كائنًا من الخصائص لتخصيص المخرجات.

النص الغني

يوفر مكون RichText مدخلات قابلة للتحرير للمحتوى ، مما يسمح للمستخدمين بتحرير المحتوى وتنسيقه.

ستجد المكون موثقًا على GitHub في gutenberg /pack / block-editor / src / component / rich-text / README.md.

الخطوة 2: قم بتضمين العناصر المقابلة في كود JSX الخاص بك

 ... const blockProps = useBlockProps(); return ( <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } /> );

دعنا نعلق على الكود سطرًا بسطر:

• tagName - اسم العلامة لعنصر HTML القابل للتحرير
• onChange - تسمى الوظيفة عندما يتغير محتوى العنصر
• allowedFormats - مجموعة من التنسيقات المسموح بها. بشكل افتراضي ، يتم السماح بجميع التنسيقات
• value - سلسلة HTML المراد تعديلها
• placeholder - نص عنصر نائب يظهر عندما يكون العنصر فارغًا

الخطوة 3: حدد السمات الضرورية في ملف block.json

توفر السمات معلومات حول البيانات المخزنة بواسطة كتلة ، مثل المحتوى الغني ولون الخلفية وعناوين URL وما إلى ذلك.

يمكنك تعيين عدد عشوائي من السمات داخل كائن attributes في أزواج مفتاح / قيمة ، حيث يكون المفتاح هو اسم السمة والقيمة هي تعريف السمة.

افتح الآن ملف block.json وأضف خاصية attributes التالية:

 "attributes": { "content": { "type": "string", "source": "html", "selector": "p" } },

تسمح سمة content بتخزين النص الذي كتبه المستخدم في الحقل القابل للتعديل:

• type يشير إلى نوع البيانات المخزنة بواسطة السمة. النوع مطلوب ما لم تحدد خاصية enum .
• source يحدد كيفية استخراج قيمة السمة من محتوى المنشور. في مثالنا ، إنه محتوى HTML. لاحظ أنه إذا لم تقدم خاصية مصدر ، فسيتم تخزين البيانات في محدد الكتلة (اقرأ المزيد).
• selector هو علامة HTML أو أي محدد آخر ، مثل اسم فئة أو سمة معرف.

سنقوم بتمرير وظيفة Edit كائن من الخصائص. لذا ، ارجع إلى ملف edit.js وقم بإجراء التغيير التالي:

 export default function Edit( { attributes, setAttributes } ) { ... }

الخطوة 4: تحديد معالجات الأحداث

يحتوي RichText على سمة onChange ، مما يوفر وظيفة يتم الاتصال بها عندما يتغير محتوى العنصر.

دعنا نحدد هذه الوظيفة ونرى النص البرمجي edit.js بالكامل:

 import { __ } from '@wordpress/i18n'; import { useBlockProps, RichText } from '@wordpress/block-editor'; import './editor.scss'; export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } return ( <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } /> ); }

الآن احفظ الملف وقم بتشغيل npm run start في نافذة المحطة الطرفية. بعد ذلك ، ارجع إلى لوحة تحكم WordPress الخاصة بك ، وأنشئ منشورًا أو صفحة جديدة وأضف كتلة الإحالة الخاصة بك:

أضف بعض النص وانتقل إلى طريقة العرض Code. هذا هو الشكل الذي يجب أن تبدو عليه التعليمات البرمجية الخاصة بك:

 <!-- wp:my-affiliate-plugin/my-affiliate-block --> <p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable Gutenberg block </p> <!-- /wp:my-affiliate-plugin/my-affiliate-block -->

إذا قمت الآن بحفظ الصفحة والتحقق من نتيجة الواجهة الأمامية ، فقد تشعر بخيبة أمل بعض الشيء لأن تغييراتك لا تؤثر على الموقع. هذا لأنه يجب عليك تعديل ملف save.js لتخزين مدخلات المستخدم في قاعدة البيانات عند حفظ المنشور.

الخطوة 5: حفظ البيانات

افتح الآن ملف save.js وقم بتغيير البرنامج النصي على النحو التالي:

 import { __ } from '@wordpress/i18n'; import { useBlockProps, RichText } from '@wordpress/block-editor'; export default function save( { attributes } ) { const blockProps = useBlockProps.save(); return ( <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } /> ); }

هذا ما نفعله هنا:

• استيراد مكون RichText من حزمة block-editor .
• قم بتمرير عدة خصائص من خلال وسيطة كائن إلى وظيفة save (في هذا المثال ، نقوم فقط بتمرير خاصية attributes )
• قم بإعادة محتوى مكون RichText

يمكنك قراءة المزيد حول مكون RichText في دليل Block Editor والعثور على القائمة الكاملة للدعائم على Github.

الآن دعنا نأخذ خطوة إلى الأمام. في القسم التالي ، ستتعلم كيفية إضافة عناصر تحكم إلى شريط أدوات الحظر.

إضافة عناصر تحكم إلى شريط أدوات الحظر

يحتوي شريط أدوات الحظر على مجموعة من عناصر التحكم التي تسمح للمستخدمين بمعالجة أجزاء من محتوى الكتلة. لكل عنصر تحكم في شريط الأدوات ، ستجد مكونًا:

على سبيل المثال ، يمكنك إضافة عنصر تحكم محاذاة النص لكتلتك. كل ما عليك فعله هو استيراد مكونين من حزمة @wordpress/block-editor .

سوف نمر بنفس الخطوات مثل المثال السابق:

1. استيراد المكونات المطلوبة من حزم WordPress
2. قم بتضمين العناصر المقابلة في كود JSX الخاص بك
3. حدد السمات الضرورية في ملف block.json
4. تحديد معالجات الأحداث
5. حفظ البيانات

الخطوة 1: استيراد مكونات BlockControls و AlignmentControl من @ wordpress / block-editor

لإضافة عنصر تحكم محاذاة إلى شريط أدوات الحظر ، تحتاج إلى مكونين:

• BlockControls شريط أدوات ديناميكي لعناصر التحكم (غير موثقة).
• يعرض AlignmentControl قائمة منسدلة تعرض خيارات المحاذاة للكتلة المحددة (اقرأ المزيد)

افتح ملف edit.js وقم بتحرير بيان import كما هو موضح أدناه:

 import { useBlockProps, RichText, AlignmentControl, BlockControls } from '@wordpress/block-editor';

الخطوة 2: إضافة BlockControls و AlignmentControl Elements

انتقل إلى وظيفة Edit وأدخل عنصر <BlockControls /> في نفس المستوى مثل <RichText /> . ثم أضف و <AlignmentControl /> داخل <BlockControls /> :

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); return ( <> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } style={ { textAlign: attributes.align } } /> </> ); }

في الكود أعلاه ، <> و </> هي الصيغة القصيرة لتصريح أجزاء React ، وهي الطريقة التي نعيد بها عناصر متعددة في React.

في هذا المثال ، يحتوي AlignmentControl على سمتين:

• توفر value القيمة الحالية للعنصر
• يوفر onChange معالج حدث ليتم تشغيله عند تغير القيمة

لقد حددنا أيضًا سمات إضافية لعنصر RichText (راجع القائمة الكاملة للسمات مع أمثلة)

الخطوة 3: حدد سمة المحاذاة في block.json

انتقل الآن إلى ملف block.json وأضف سمة align :

 "align": { "type": "string", "default": "none" }

ارجع إلى المحطة ، وأوقف العملية الحالية باستخدام ^C وابدأ البرنامج النصي مرة أخرى مع npm run start . ثم ارجع إلى محرر الكتلة ، وقم بتحديث الصفحة وحدد الكتلة. يجب أن ترى شريط أدوات الحظر مع عنصر تحكم محاذاة:

الآن ، إذا حاولت تنسيق محتوى الكتلة باستخدام عناصر تحكم المحاذاة الجديدة ، فسترى أنه لا شيء يحدث. هذا لأننا لم نحدد معالج الحدث حتى الآن.

الخطوة 4: تحديد معالجات الأحداث

الآن حدد onChangeAlign :

 const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) }

إذا كانت newAlign غير undefined ، فسنقوم بتعيين newAlign على none . وإلا فإننا نستخدم newAlign .

يجب أن يكون النص البرمجي لـ edit.js كاملاً (في الوقت الحالي):

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) } return ( <> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...' ) } style={ { textAlign: attributes.align } } /> </> ); }

يمكنك الآن الرجوع إلى المحرر ومحاذاة محتوى الكتلة.

نحتاج إلى تعديل وظيفة الحفظ لتخزين سمات ومحتوى الكتلة في قاعدة البيانات.

الخطوة 5: حفظ البيانات

افتح save.js وقم بتغيير وظيفة save على النحو التالي:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); return ( <RichText.Content { ...blockProps } tagName="p" value={ attributes.content } style={ { textAlign: attributes.align } } /> ); }

أخيرًا ، لجعل الكود أكثر قابلية للقراءة ، يمكنك استخراج الخصائص الفردية من كائن attribute باستخدام بناء جملة مهمة التدمير:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); const { content, align } = attributes; return ( <RichText.Content { ...blockProps } tagName="p" value={ content } style={ { textAlign: align } } /> ); }

احفظ الملف وأعد العملية وعد إلى المحرر في وضع محرر الكود. يجب أن يبدو الرمز كما يلي:

 <!-- wp:my-affiliate-plugin/my-affiliate-block {"align":"right"} --> <p class="wp-block-my-affiliate-plugin-my-affiliate-block">This is my first editable <strong><em>Gutenberg</em></strong> <em>block</em> </p> <!-- /wp:my-affiliate-plugin/my-affiliate-block -->

وهذا كل شيء! لقد أضفت للتو عنصر تحكم محاذاة إلى شريط أدوات الحظر

يمكنك قراءة المزيد حول عناصر التحكم في شريط أدوات الحظر في دليل Block Editor Handbook.

تخصيص الشريط الجانبي لإعدادات الحظر

يمكنك أيضًا إضافة عناصر تحكم إلى الشريط الجانبي للإعدادات (أو حتى إنشاء شريط جانبي جديد لتطبيقك).

يوفر API مكون InspectorControls لذلك.

يشرح دليل Block Editor كيفية استخدام الشريط الجانبي للإعدادات:

يستخدم الشريط الجانبي للإعدادات لعرض الإعدادات الأقل استخدامًا أو الإعدادات التي تتطلب مساحة شاشة أكبر. يجب استخدام الشريط الجانبي للإعدادات لإعدادات مستوى الحظر فقط .

إذا كانت لديك إعدادات تؤثر فقط على المحتوى المحدد داخل كتلة (على سبيل المثال: الإعداد "غامق" للنص المحدد داخل فقرة): لا تضعه داخل الشريط الجانبي للإعدادات. يتم عرض الشريط الجانبي للإعدادات حتى عند تحرير كتلة في وضع HTML ، لذلك يجب أن تحتوي فقط على إعدادات مستوى الكتلة.

تكرارا:

1. استيراد المكونات المطلوبة من حزم WordPress
2. قم بتضمين العناصر المقابلة في كود JSX الخاص بك
3. حدد السمات الضرورية في ملف block.json
4. تحديد معالجات الأحداث
5. حفظ البيانات

الخطوة 1. استيراد مكونات InspectorControls و PanelColorSettings من @ wordpress / block-editor

يمكنك إضافة العديد من عناصر التحكم للسماح للمستخدمين بتخصيص جوانب معينة من الكتلة. على سبيل المثال ، يمكنك توفير لوحة تحكم بالألوان. للقيام بذلك ، ستحتاج إلى استيراد مكونات InspectorControls و PanelColorSettings من وحدة block-editor :

 import { useBlockProps, RichText, AlignmentControl, BlockControls, InspectorControls, PanelColorSettings } from '@wordpress/block-editor';

الخطوة 2: قم بتضمين العناصر المقابلة في كود JSX الخاص بك

يمكنك الآن إضافة العناصر المقابلة إلى JSX التي تم إرجاعها بواسطة وظيفة Edit :

 export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); const onChangeContent = ( newContent ) => { setAttributes( { content: newContent } ) } const onChangeAlign = ( newAlign ) => { setAttributes( { align: newAlign === undefined ? 'none' : newAlign, } ) } return ( <> <InspectorControls> <PanelColorSettings title={ __( 'Color settings', 'my-affiliate-block' ) } initialOpen={ false } colorSettings={ [ { value: textColor, onChange: onChangeTextColor, label: __( 'Text color', 'my-affiliate-block' ), }, { value: backgroundColor, onChange: onChangeBackgroundColor, label: __( 'Background color', 'my-affiliate-block' ), } ] } /> </InspectorControls> <BlockControls> <AlignmentControl value={ attributes.align } onChange={ onChangeAlign } /> </BlockControls> <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ attributes.content } placeholder={ __( 'Write your text...', 'my-affiliate-block' ) } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } /> </> ); }

لاحظ أننا قمنا أيضًا بتحديث سمة style لعنصر RichText :

 <RichText { ...blockProps } tagName="p" onChange={ onChangeContent } allowedFormats={ [ 'core/bold', 'core/italic' ] } value={ content } placeholder={ __( 'Write your text...', 'my-affiliate-block' ) } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } />

الخطوة 3: تحديد السمات الضرورية في block.json

حدد الآن سمات backgroundColor و textColor في ملف block.json :

 "attributes": { "content": { "type": "string", "source": "html", "selector": "p" }, "align": { "type": "string", "default": "none" }, "backgroundColor": { "type": "string" }, "textColor": { "type": "string" } },

الخطوة 4: تحديد معالجات الأحداث

أنت الآن بحاجة إلى تحديد وظيفتين لتحديث backgroundColor و textColor عند إدخال المستخدم:

 const onChangeBackgroundColor = ( newBackgroundColor ) => { setAttributes( { backgroundColor: newBackgroundColor } ) } const onChangeTextColor = ( newTextColor ) => { setAttributes( { textColor: newTextColor } ) }

الخطوة 5: حفظ البيانات

خطوة أخيرة: افتح ملف save.js وقم بتغيير البرنامج النصي على النحو التالي:

 export default function save( { attributes } ) { const blockProps = useBlockProps.save(); const { content, align, backgroundColor, textColor } = attributes; return ( <RichText.Content { ...blockProps } tagName="p" value={ content } style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } } /> ); }

الآن أوقف العملية (^ C) وقم بتشغيل npm run start مرة أخرى. قم بتحديث الصفحة ، واحذف أي مثيل لحظرك وأضفه مرة أخرى إلى منشورك:

قم بإجراء التغييرات ، وحفظ المنشور ، وعرضه في الواجهة الأمامية. يجب أن تنعكس التغييرات التي أجريتها في محرر الكتلة على الموقع الأمامي.

إضافة رابط خارجي وتخصيصه

في هذا القسم ، ستضيف مكونات جديدة إلى نوع الكتلة الخاصة بك:

• مكون ExternalLink يسمح للمستخدمين بإضافة ارتباط قابل للتخصيص إلى كتلة الشركة التابعة
• العديد من عناصر التحكم في الشريط الجانبي تسمح للمستخدمين بتخصيص إعدادات الارتباط

الخطوة 1. استيراد مكونات من @ wordpress / المكونات

أنت الآن بحاجة إلى استيراد العديد من المكونات من @wordpress/components . افتح ملف edit.js وأضف بيان import التالي:

 import { TextControl, PanelBody, PanelRow, ToggleControl, ExternalLink } from '@wordpress/components';

• يضيف PanelBody حاوية قابلة للطي إلى الشريط الجانبي للإعدادات.
• ينتج PaneRow حاوية عامة لعناصر تحكم الشريط الجانبي.
• يوفر TextControl عنصر تحكم إدخال النص.
• يوفر ToggleControl مفتاح تبديل يتيح للمستخدمين تمكين / تعطيل خيار معين
• ExternalLink هو مكون بسيط لإضافة ارتباط خارجي.

الخطوة 2. قم بتضمين العناصر المقابلة في كود JSX الخاص بك

ستضيف أولاً عنصر ExternalLink بنفس مستوى RichText في حاوية div :

 <div { ...blockProps }> <RichText ... /> <ExternalLink href={ affiliateLink } className="affiliate-button" rel={ hasLinkNofollow ? "nofollow" : "" } > { linkLabel } </ExternalLink> </div>

لم يتم توثيق مكون ExternalLink ، لذلك أشرنا إلى المكون نفسه للحصول على قائمة السمات المتاحة. نحن هنا نستخدم سمات href و className و rel .

بشكل افتراضي ، يتم تعيين قيمة السمة rel على noopener noreferrer . سيضيف الكود الخاص بنا الكلمة الأساسية nofollow إلى السمة rel الخاصة بالعلامة الناتجة عندما a عنصر التحكم في التبديل قيد التشغيل .

يمكنك الآن إضافة إعدادات الارتباط إلى الشريط الجانبي للحظر.

أولاً ، ستضيف عنصر PanelBody داخل InspectorControls بنفس مستوى PanelColorSettings :

 <InspectorControls> <PanelColorSettings ... /> <PanelBody title={ __( 'Link Settings', 'my-affiliate-block' )} initialOpen={true} > ... </PanelBody> </InspectorControls>

إليك ما نفعله بهذا:

1. توفر سمة title عنوان اللوحة.
2. يعيّن initialOpen ما إذا كانت اللوحة مفتوحة أم لا.

بعد ذلك ، سنضيف عنصرين PanelRow داخل PanelBody ، وعنصر TextControl داخل كل PanelRow :

 <PanelBody title={ __( 'Link Settings', 'my-affiliate-block' )} initialOpen={true} > <PanelRow> <fieldset> <TextControl label={__( 'Affiliate link', 'my-affiliate-block' )} value={ affiliateLink } onChange={ onChangeAffiliateLink } help={ __( 'Add your affiliate link', 'my-affiliate-block' )} /> </fieldset> </PanelRow> <PanelRow> <fieldset> <TextControl label={__( 'Link label', 'my-affiliate-block' )} value={ linkLabel } onChange={ onChangeLinkLabel } help={ __( 'Add link label', 'my-affiliate-block' )} /> </fieldset> </PanelRow> </PanelBody>

يجب أن يبدو الرمز أعلاه واضحًا جدًا الآن. يسمح عنصرا التحكم في النص للمستخدمين بتعيين تسمية الارتباط وعنوان URL.

سنضيف أيضًا PanelRow إضافية مع ToggleControl لتشغيل / إيقاف تشغيل خيار معين ، مثل تضمين سمة أم لا:

 <PanelRow> <fieldset> <ToggleControl label="Add rel = nofollow" help={ hasLinkNofollow ? 'Has rel nofollow.' : 'No rel nofollow.' } checked={ hasLinkNofollow } onChange={ toggleNofollow } /> </fieldset> </PanelRow>

الخطوة 3: تحديد السمات الضرورية في block.json

حدد الآن سمات affiliateLink و linkLabel و hasLinkNofollow في ملف block.json :

 "affiliateLink": { "type": "string", "default": "" }, "linkLabel": { "type": "string", "default": "Check it out!" }, "hasLinkNofollow": { "type": "boolean", "default": false }

لا شيء أكثر لإضافة هنا! دعنا ننتقل إلى تحديد وظائف معالجة الحدث.

الخطوة 4: تحديد معالجات الأحداث

ارجع إلى ملف edit.js وأضف الوظائف التالية:

 const onChangeAffiliateLink = ( newAffiliateLink ) => { setAttributes( { affiliateLink: newAffiliateLink === undefined ? '' : newAffiliateLink } ) } const onChangeLinkLabel = ( newLinkLabel ) => { setAttributes( { linkLabel: newLinkLabel === undefined ? '' : newLinkLabel } ) } const toggleNofollow = () => { setAttributes( { hasLinkNofollow: ! hasLinkNofollow } ) }

تعمل هذه الوظائف على تحديث قيم السمات المقابلة في مدخلات المستخدم.

الخطوة 5: حفظ البيانات

أخيرًا ، يتعين علينا تحديث وظيفة save في save.js :

 export default function save( { attributes } ) { const { align, content, backgroundColor, textColor, affiliateLink, linkLabel, hasLinkNofollow } = attributes; const blockProps = useBlockProps.save(); return ( <div { ...blockProps }> <RichText.Content tagName="p" value={ content } style={ { backgroundColor: backgroundColor, color: textColor } } /> <p> <a href={ affiliateLink } className="affiliate-button" rel={ hasLinkNofollow ? "nofollow" : "noopener noreferrer" } > { linkLabel } </a> </p> </div> ); }

لاحظ أننا استخدمنا هنا a عاديًا بدلاً من ExternalLink :

الآن احفظ البيانات وأعد تشغيل بيئتك.

إضافة أنماط كتل متعددة

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

لهذا الغرض ، سنستخدم ميزة مفيدة في Block API: Block Styles.

كل ما عليك فعله هو تحديد خاصية block.json styles وإعلان الأنماط المقابلة في أوراق الأنماط الخاصة بك.

على سبيل المثال ، يمكنك إضافة مجموعة الأنماط التالية:

 "styles": [ { "name": "default", "label": "Default", "isDefault": true }, { "name": "border", "label": "Border" } ],

بهذا ، تكون قد أضفت للتو نمطًا افتراضيًا ونمطًا إضافيًا يسمى border . عد الآن إلى محرر الكتلة:

ستتوفر الأنماط للمستخدم من خلال النقر على مبدل الكتلة ثم البحث عن لوحة الأنماط في الشريط الجانبي لإعدادات الحظر .

حدد نمطًا وتحقق من الفئات المطبقة على العنصر p . انقر بزر الماوس الأيمن فوق الكتلة وفحص . تمت إضافة فئة جديدة باسم منظم على النحو التالي:

 is-style-{style-name}

إذا قمت بتحديد نمط "Border" ، فستتم إضافة فئة is-style-border إلى العنصر p . إذا حددت النمط "الافتراضي" ، فستتم إضافة فئة is-style-default بدلاً من ذلك.

الآن عليك فقط إعلان خصائص CSS. افتح ملف editor.scss واستبدل الأنماط الحالية بما يلي:

 .wp-block-my-affiliate-plugin-my-affiliate-block { padding: 2px; &.is-style-default{ border: 0; } &.is-style-border{ border: 1px solid #000; } }

يمكنك الآن فعل الشيء نفسه مع style.scss :

 .wp-block-my-affiliate-plugin-my-affiliate-block { &.is-style-default{ border: 0; } &.is-style-border{ border: 1px solid #000; } }

أوقف العملية (^ C) وقم بتشغيل npm run start مرة أخرى.

وهذا كل شيء! قم بتحديث الصفحة واستمتع باستخدام أنماط الكتلة الجديدة:

تداخل كتل جوتنبرج مع مكون InnerBlocks

على الرغم من أنه يعمل بكامل طاقته ، إلا أن مجموعة الإحالة الخاصة بنا لا تزال غير جذابة للغاية. لجعلها أكثر جاذبية للجمهور ، يمكننا إضافة صورة.

قد يضيف هذا طبقة من التعقيد إلى الكتلة الخاصة بنا ، لكن لحسن الحظ ، لا تحتاج إلى إعادة اختراع العجلة لأن Gutenberg يوفر مكونًا محددًا يمكنك استخدامه لإنشاء بنية من الكتل المتداخلة.

يتم تعريف مكون InnerBlocks على النحو التالي:

InnerBlocks بتصدير زوج من المكونات التي يمكن استخدامها في تطبيقات الكتلة لتمكين محتوى الكتلة المتداخلة.

أولاً ، ستحتاج إلى إنشاء ملف .js جديد في مجلد src . في مثالنا ، سنسمي هذا الملف container.js .

الآن ستحتاج إلى استيراد المورد الجديد إلى ملف index.js :

 import './container';

ارجع إلى container.js واستورد المكونات الضرورية:

 import { registerBlockType } from "@wordpress/blocks"; import { __ } from "@wordpress/i18n"; import { useBlockProps, InnerBlocks } from "@wordpress/block-editor";

الخطوة التالية هي تحديد قالب يوفر الهيكل الذي سيتم وضع الكتل بداخله. في المثال التالي ، نحدد نموذجًا يتكون من عمودين يحتويان على كتلة صورة أساسية وكتلة الإحالة المخصصة الخاصة بنا:

 const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [ [ 'core/column', { templateLock: 'all' }, [ [ 'core/image' ], ] ], [ 'core/column', { templateLock: 'all' }, [ [ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ], ] ], ] ] ];

تم بناء القالب كمصفوفة من blockTypes (اسم الكتلة والسمات الاختيارية).

في الكود أعلاه ، استخدمنا العديد من السمات لتكوين كتل الأعمدة والأعمدة. على وجه التحديد ، templateLock: 'all' بتأمين كتل الأعمدة بحيث لا يقوم المستخدم بإضافة أو إعادة ترتيب أو حذف الكتل الموجودة. يمكن لـ templateLock أن تأخذ إحدى القيم التالية:

• all - تم قفل InnerBlocks ، ولا يمكن إضافة كتل أو إعادة ترتيبها أو إزالتها.
• insert - يمكن إعادة ترتيب الكتل أو إزالتها فقط.
• false - القالب غير مؤمن.

ثم يتم تعيين القالب إلى عنصر InnerBlocks :

 <InnerBlocks template={ TEMPLATE } templateLock="all" />

لمنع أي مشكلة في التوافق ، أضفنا أيضًا سمة templateLock إلى مكون InnerBlocks (راجع أيضًا المشكلة رقم 17262 واسحب # 26128).

هذا هو ملف Container.js النهائي الخاص بنا:

 import { registerBlockType } from "@wordpress/blocks"; import { __ } from "@wordpress/i18n"; import { useBlockProps, InnerBlocks } from "@wordpress/block-editor"; const TEMPLATE = [ [ 'core/columns', { backgroundColor: 'yellow', verticalAlignment: 'center' }, [ [ 'core/column', { templateLock: 'all' }, [ [ 'core/image' ], ] ], [ 'core/column', { templateLock: 'all' }, [ [ 'my-affiliate-plugin/my-affiliate-block', { placeholder: 'Enter side content...' } ], ] ], ] ] ]; registerBlockType('my-affiliate-plugin/my-affiliate-container-block', { title: __( 'Container', 'my-affiliate-block' ), category: 'design', edit( { className } ) { return( <div className={ className }> <InnerBlocks template={ TEMPLATE } templateLock="all" /> </div> ) }, save() { const blockProps = useBlockProps.save(); return( <div { ...blockProps }> <InnerBlocks.Content /> </div> ) }, });

تحسينات إضافية

تعمل الكتلة الخاصة بنا بكامل طاقتها ، ولكن يمكننا تحسينها قليلاً ببعض التغييرات الصغيرة.

قمنا بتعيين سمة backgroundColor للفقرة التي تم إنشاؤها بواسطة مكون RichText . ومع ذلك ، قد نفضل تعيين لون الخلفية div الحاوية:

لذلك ، قم بتغيير ملف edit.js و save.js div s على النحو التالي:

 <div { ...blockProps } style={ { backgroundColor: backgroundColor } } > ... </div>

سيسمح هذا للمستخدم بتغيير خلفية الكتلة بأكملها.

من ناحية أخرى ، يتضمن التغيير الأكثر صلة طريقة useBlockProps . في الكود الأصلي ، حددنا blockProps الثابت على النحو التالي:

 const blockProps = useBlockProps();

لكن يمكننا استخدام useBlockProps بشكل أكثر فاعلية في تمرير مجموعة من الخصائص. على سبيل المثال ، يمكننا استيراد classnames من الوحدة النمطية classnames وتعيين اسم فئة المجمع وفقًا لذلك.

في المثال التالي ، قمنا بتعيين اسم فئة بناءً على قيمة سمة المحاذاة (edit.js align :

 import classnames from 'classnames'; ... export default function Edit( { attributes, setAttributes } ) { ... const blockProps = useBlockProps( { className: classnames( { [ `has-text-align-${ align }` ]: align, } ) } ); ... }

سنفعل نفس التغيير في ملف save.js :

 import classnames from 'classnames'; ... export default function save( { attributes } ) { ... const blockProps = useBlockProps.save({ className: classnames( { [ `has-text-align-${ align }` ]: align, } ) }); ... }

و هذا ملف! يمكنك الآن تشغيل الإنشاء للإنتاج.

ملخص

وها نحن هنا في نهاية هذه الرحلة الرائعة! بدأنا بتكوين بيئة التطوير وانتهى بنا المطاف بإنشاء نوع كتلة كامل.

كما ذكرنا في المقدمة ، فإن المعرفة القوية بـ Node.js و Webpack و Babel و React ضرورية لإنشاء كتل Gutenberg المتقدمة ووضع نفسك في السوق كمطور محترف لـ Gutenberg.

لكنك لست بحاجة إلى إنشاء تجربة React لبدء الاستمتاع بتطوير الكتلة ، على الرغم من ذلك. قد يمنحك تطوير الكتل الدافع والأهداف لاكتساب مهارات واسعة النطاق بشكل متزايد في التقنيات وراء كتل Gutenberg.

لذلك ، فإن هذا الدليل بعيد عن الاكتمال. إنها مجرد مقدمة لمجموعة متنوعة من الموضوعات التي ستساعدك على البدء في بناء كتل Gutenberg الأولى الخاصة بك.

لهذا السبب ، نوصيك بتعميق معرفتك من خلال قراءة الوثائق والأدلة عبر الإنترنت بعناية. من بين العديد من الموارد المتاحة هناك ، نوصي بما يلي:

• إنشاء برنامج تعليمي رسمي للمبتدئين
• البرنامج التعليمي الرسمي للكتلة للمطورين المتوسطين
• الكتل الديناميكية
• مربعات ميتا
• إنشاء شريط جانبي لبرنامجك الإضافي

إذا كنت قد بدأت للتو في تطوير WordPress ، فقد ترغب في فهم المفاهيم الأساسية لتطوير الواجهة الأمامية. فيما يلي قائمة سريعة بالموارد التي قد تساعدك على البدء:

• كيفية تثبيت WordPress محليًا (كتاب إلكتروني مجاني)
• القيمة الحقيقية لاستضافة WordPress المُدارة (كتاب إلكتروني مجاني)
• ما هو جافا سكريبت؟
• HTML مقابل HTML5
• كيفية تحرير CSS في WordPress
• ما هي لغة PHP؟
• معسكر تدريب WordPress Hooks: كيفية استخدام الإجراءات والفلاتر والخطافات المخصصة

وتذكر أن الكود الكامل لأمثلة هذا الدليل متاح على Gist.

حان دورك الآن: هل طورت أي كتل من كتل جوتنبرج؟ ما هي الصعوبات الرئيسية التي واجهتها حتى الآن؟ أخبرنا عن تجربتك في التعليقات!