خطافات محرر المكوّنات

تُعدّ الخطافات إحدى الميزات الأساسية في ووردبريس. فهي تتيح لك «الربط» بنواة ووردبريس وتنفيذ التعليمات البرمجية الخاصة بك في نقاط محددة من دورة حياة ووردبريس.

يمتلك محرر المكوّنات مجموعة خاصة به من الخطافات التي تتيح لك التفاعل مع المحرر وتعديل سلوكه.

سيعرّفك هذا الدرس على بعض الخطافات المختلفة المتاحة في محرر المكوّنات، وكيفية استخدامها لتوسيع وظائف المحرر.

حزمة @wordpress/hooks

في حين كانت خطافات الإجراءات والمرشحات متاحة تاريخيًا في PHP فقط، وبما أن محرر المكوّنات مبني باستخدام JavaScript، فقد أصبحت هناك الآن أيضًا مجموعة جديدة من خطافات JavaScript.

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

يتم تسجيل خطافات JavaScript باستخدام الدالتين addAction وaddFilter من @wordpress/hooks الحزمة.

وكما هو الحال مع إصدارات PHP، تمرّر اسم الخطاف ودالة الاستدعاء إلى هاتين الدالتين.

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

لنلقِ نظرة على مثال يوضّح كيفية استخدام خطاف JavaScript.

مرشح blocks.registerBlockType

في جميع أمثلة المكوّنات التي رأيتها حتى الآن، استخدمت الدالة registerBlockType من حزمة @wordpress/blocks لتسجيل مكوّن باستخدام JavaScript.

يبدأ كل مكوّن بتسجيل تعريف نوع مكوّن جديد باستخدام هذه الدالة.

/**
 * Every block starts by registering a new block type definition.
 *
 * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/
 */
registerBlockType( metadata.name, {
    /**
     * @see ./edit.js
     */
    edit: Edit,

    /**
     * @see ./save.js
     */
    save,
} );

عند تشغيل التعليمات البرمجية التي تعالج جميع المكوّنات المسجّلة، يتم تشغيل أي دوال استدعاء مرتبطة بمرشح الخطاف blocks.registerBlockType، وينبغي أن تُرجع كائن إعدادات مكوّن معدّلًا.

    const settings = applyFilters(
        'blocks.registerBlockType',
        blockType,
        name,
        null
    );

يتيح لك مرشح الخطاف هذا تعديل كائن إعدادات المكوّن قبل تسجيل المكوّن.

لتسجيل دالة استدعاء لمرشح blocks.registerBlockType، تستخدم الدالة addFilter من حزمة @wordpress/hooks.

لننشئ إضافة لإدراج ملف JavaScript، من أجل تسجيل المرشح.

ابدأ بإنشاء مجلد داخل دليل wp-content/plugins لتخزين تعليمات خطافات المكوّنات البرمجية.

mkdir -p wp-content/plugins/wp-learn-block-hooks

أنشئ ملف PHP الرئيسي للإضافة، wp-learn-block-hooks.php، في المجلد الذي أنشأته حديثًا.

ثم أضف التعليمات البرمجية التالية لإعداد ترويسة الإضافة، والتأكد من تشغيل تعليمات الإضافة البرمجية داخل بيئة ووردبريس فقط:

<?php
/**
 * Plugin Name:       WP Learn Block Hooks
 * Description:       WP Learn Block Hooks
 * Requires at least: 6.6
 * Requires PHP:      7.0
 * Version:           1.0.0
 * Author:            The WordPress Contributors
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       wp-learn-block-hooks
 *
 */
if ( ! defined( 'ABSPATH' ) ) {
    exit; // Exit if accessed directly.
}

بعد ذلك، يمكنك ربط دالة استدعاء بإجراء enqueue_block_editor_assets لإدراج ملف JavaScript.

add_action( 'enqueue_block_editor_assets', 'wp_learn_block_hooks_editor_assets' );
function wp_learn_block_hooks_editor_assets() {
    wp_enqueue_script(
        'wp-learn-block-hooks-editor-script',
        plugin_dir_url( __FILE__ ) . 'block-hooks.js',
        array(
            'wp-hooks',
        ),
    );
}

لاحظ أنك تحتاج إلى تحديد تبعية wp-hooks للتأكد من تحميل تعليمات خطافات المكوّنات البرمجية مرة واحدة فقط بعد إتاحة حزمة @wordpress/hooks. ويرجع ذلك إلى أنك ستستخدم الدالة addFilter من حزمة @wordpress/hooks في ملف JavaScript.

أنشئ الآن ملف block-hooks.js في مجلد الإضافة وابدأ بتعبير دالة يتم استدعاؤها فورًا (IIFE) لمنع تسرّب أي متغيرات من هذه التعليمات البرمجية إلى النطاق العام:

( function(){

} )()

بعد ذلك، استخدم الدالة addFilter لتسجيل دالة استدعاء على مرشح الخطاف blocks.registerBlockType:

( function(){
    wp.hooks.addFilter(
        'blocks.registerBlockType',
        'wp-learn-block-hooks/list-block-description',
        addListBlockDescription
    );
} )()

لاحظ كيفية تحديد مساحة أسماء فريدة قبل دالة الاستدعاء addListBlockDescription. يحدد المطوّر مساحة الأسماء، وينبغي أن تكون فريدة لإضافتك.

لننشئ الآن دالة الاستدعاء addListBlockDescription لتنفيذ إجراء ما:

    function addListBlockDescription( settings, name ) {
        if ( name === 'core/list' ) {
            settings.description = 'This is a list block';
        }
        return settings;
    }

هنا، تتلقى دالة الاستدعاء addListBlockDescription كائن إعدادات المكوّن واسم المكوّن كمعلمتين.

ثم تتحقق مما إذا كان المكوّن الذي يجري تسجيله هو مكوّن قائمة، وإذا كان كذلك، تغيّر خاصية الوصف في كائن إعدادات المكوّن.

وأخيرًا، بما أن هذا مرشح، فيجب أن يُرجع شيئًا؛ وفي هذه الحالة، يجب أن يُرجع كائن الإعدادات المعدّل.

لاختبار ذلك، لا تفعّل الإضافة بعد، بل حرّر منشورًا أو صفحة، وابحث عن مكوّن القائمة من أداة إدراج المكوّنات.

إذا مرّرت مؤشر الفأرة فوق مكوّن القائمة، فمن المفترض أن ترى الوصف «إنشاء قائمة نقطية أو مرقمة».

فعّل الإضافة الآن.

بعد تفعيل الإضافة، من المفترض أن يتغير وصف مكوّن القائمة إلى «هذا مكوّن قائمة».

وثائق خطافات محرر المكوّنات

يحتوي دليل محرر المكوّنات على قسم مخصص لـ خطافات محرر المكوّنات، ويتضمن صفحات مختلفة للأنواع المختلفة من الخطافات المتاحة.

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

توثّق خطافات المحرر جميع الخطافات التي تتيح لك تعديل تجربة المحرر، بما في ذلك تعديل إعدادات المحرر، وتعطيل ميزتي دليل المكوّنات ودليل الأنماط، وتوسيع ميزات المحرر، والتحكم في بيانات REST API الخاصة بالمحرر، وتسجيل أخطاء المحرر.

تحتوي صفحة مرشحات التدويل على قائمة بالمرشحات التي تتيح لك تعديل وظائف التدويل المستخدمة في المحرر.

توثّق مرشحات المحلّل جميع المرشحات التي تتيح لك تعديل محلّل المكوّنات، المستخدم لتحويل بيانات المكوّنات المخزنة في الذاكرة إلى ترميز المكوّنات المخزن في محتوى المنشور بقاعدة البيانات.

يُعد الإكمال التلقائي مكوّنًا في حزمة @wordpress/block-editor يوفّر طريقة لإضافة أدوات إكمال تلقائي إلى المحرر.

إذا سبق لك استخدام وظيفة @username في محرر المكوّنات، فهذه الوظيفة مدعومة بمكوّن الإكمال التلقائي.

توثّق صفحة مرشحات الإكمال التلقائي كيفية إضافة أدوات الإكمال التلقائي الخاصة بك إلى المحرر.

وأخيرًا، توثّق صفحة مرشحات الأنماط العامة المرشحات التي أُضيفت إلى ووردبريس في الإصدار 6.1، والتي تتيح للمطوّرين تعديل الإعدادات العامة والأنماط العامة لقالب مكوّنات كما يحددها ملف theme.json.

تتضمن كل هذه الصفحات أمثلة مفصّلة حول كيفية استخدام هذه الخطافات، وكيف يمكن استخدامها لتوسيع وظائف محرر المكوّنات.