آنچه توسعه دهندگان وردپرس باید در مورد ویژگی blocks در theme.json بدانند

معرفی ویرایشگر کامل سایت (FSE) در وردپرس، اهمیت فایل theme.json را بیش از پیش برجسته کرده است. اکنون با سلسله مراتب و ساختار جدیدی روبرو هستیم که باید درک کنیم، همراه با ویژگی‌های مختلفی برای کمک به ایجاد طرح‌های خود. به طور خاص، ویژگی blocks در theme.json برای ایجاد تم‌های وردپرس مدرن، انعطاف‌پذیر و با بلوک‌های منحصر به فرد ضروری است.

در این راهنما، به بررسی جزئیات ویژگی blocks در theme.json می‌پردازیم تا بتوانید با بلوک‌ها کار کنید، آن‌ها را طراحی و استایل‌دهی کنید تا تجربیات وردپرس پویاتر و قابل سفارشی‌سازی بیشتری ایجاد کنید.

درک ویژگی blocks در theme.json

قبل از اینکه به پیچیدگی‌های ویژگی blocks بپردازیم، ابتدا باید نقش آن را در theme.json و توسعه تم‌های وردپرس درک کنیم.

{
"version": 3,
  "settings": {
    "blocks": {
      "core/paragraph": {
        "typography": {
          "fontSizes": [
            {
              "name": "Small",
              "slug": "small",
              "size": "13px"
            },
            {
              "name": "Medium",
              "slug": "medium",
              "size": "20px"
             }
           ]
…

مثال بالا اندازه‌های فونت سفارشی برای بلاک پاراگراف تعریف می‌کند. تجزیه و تحلیل اجزای کلیدی ساده است:

• ویژگی blocks را درون شیء settings قرار می‌دهید.
• هر نوع بلاک یک namespace و نام خاص دارد (در اینجا core/paragraph).
• سپس تنظیمات بلاک را درون شیء تعریف می‌کنید.

این تنظیمات شامل بیشتر مواردی است که برای سبک‌های جهانی در دسترس هستند؛ برای مثال، می‌توانند شامل تایپوگرافی، رنگ، فاصله‌گذاری و بسیاری از موارد دیگر باشند.

پیکربندی تنظیمات بلاک‌های جهانی

بیایید ببینیم چگونه تنظیمات جهانی را تعریف کنیم و سپس نگاهی به تأثیر آن بر ویژگی blocks بیندازیم. این روش به شما کمک می‌کند تا یک پایه طراحی هماهنگ و یکپارچه برای قالب خود ایجاد کنید.

{
"version": 3,
  "settings": {
    "typography": {
      "fontSizes": [
        {
          "name": "Small",
          "slug": "small",
          "size": "13px"
        },
        {
          "name": "Medium",
          "slug": "medium",
          "size": "20px"
        }
…

{
"version": 3,
  "settings": {
    "blocks": {
      "core/heading": {
        "typography": {
          "fontSizes": [
            {
              "name": "Small",
              "slug": "small",
              "size": "20px"
            },
            {
              "name": "Medium",
              "slug": "medium",
              "size": "30px"
            },
            {
              "name": "Large",
              "slug": "large",
              "size": "40px"
            }
            ],
            "fontWeight": "bold"
            },
            "color": {
              "palette": [
                {
                  "name": "Heading Primary",
                  "slug": "heading-primary",
                  "color": "#333333"
                },
                {
                  "name": "Heading Secondary",
                  "slug": "heading-secondary",
                  "color": "#666666"
                }
              ]
…

می‌بینید که ویژگی‌ها نشان می‌دهند چگونه می‌توانید تغییرات جهانی را اعمال کنید. بیایید خلاصه کنیم که چه کار می‌کنیم:

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

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

استفاده از ترکیب مناسب namespace و slug

هنگام فراخوانی نوع‌های بلاک، مهم است که از ترکیب صحیح namespace و slug استفاده کنید. در غیر این صورت، تغییرات شما بر بلاک‌هایی که می‌خواهید اعمال نمی‌شوند.

هر بلاک یک namespace و یک slug دارد. بلاک‌های اصلی وردپرس معمولاً namespace با نام core دارند. slug نیز نام بلاک خواهد بود:

… “blocks”: { “core/image”: { …

اگر نیاز دارید slug یک بلاک را بدانید، می‌توانید به فایل block.json خاص آن بلاک مراجعه کنید. این فایل را می‌توانید در پوشه wp-includes/blocks پیدا کنید. در اینجا پوشه‌های مختلفی وجود دارد که هرکدام دارای یک فایل block.json هستند. در هر فایل، namespace و slug بلاک باید در بالای فایل قرار داشته باشد.

…
"blocks": {
  "core/button": {
    "border": {
      "radius": true
     }
  },
…

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

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

توسعه بلاک‌های سفارشی با theme.json

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

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

• ایجاد ساختار اولیه بلاک: این مرحله شامل تنظیم محیط توسعه محلی و ایجاد ساختار فایل برای کل بلاک است.
• به‌روزرسانی فایل block.json: در اینجا باید هویت بلاک را تغییر دهید و ویژگی‌های پشتیبانی را اضافه کنید. این ویژگی‌ها نحوه پشتیبانی از قابلیت‌های خاص وردپرس را اعلام می‌کنند. به عنوان مثال، می‌توانید ترازها را مدیریت کنید، فیلدهای لنگر (anchor) اضافه کنید، با تنظیمات مختلف تایپوگرافی کار کنید و غیره.
• تغییر فایل‌های جاوااسکریپت بلاک: هر دو فایل index.js و edit.js به کدی نیاز دارند که به وردپرس بگوید چگونه بلاک کار می‌کند و آن را در ویرایشگر سایت نشان دهد.

همچنین ممکن است نیاز باشد فایل render.php را ویرایش کنید، رندر استاتیک اضافه کنید و مجموعه‌ای از کارهای دیگر را انجام دهید. در این مرحله، می‌توانید مانند هر بلاک دیگر تغییرات ظاهری را در theme.json اعمال کنید. حال بیایید نگاهی دقیق‌تر به block.json بیندازیم.

فایل block.json

این فایل همان چیزی است که تیم توسعه وردپرس از آن به عنوان روش “اصلی” برای ثبت بلاک‌ها هم در سمت سرور و هم در سمت کاربر یاد می‌کند. متادیتاهایی که در اینجا وارد می‌کنید به وردپرس اطلاعات لازم درباره نوع بلاک و فایل‌های پشتیبان آن را می‌دهد.

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "my-plugin/notice",
  "title": "Notice",
  "category": "text",
  "parent": [ "core/group" ],
  "icon": "star",
  "description": "Shows warning, error or success notices...",
  "keywords": [ "alert", "message" ],
  "version": "1.0.3",
  "textdomain": "my-plugin",
  "attributes": {
    "message": {
      "type": "string",
      "source": "html",
      "selector": ".message"
    }
  },
…

این شبیه به ابرداده ای است که در بالای یک فایل PHP برای تم ها و افزونه ها قرار می دهید. در حالی که فایل به طور انحصاری از داده های JSON استفاده می کند، همچنان می توانید کد را از طریق PHP، جاوا اسکریپت و CSS به اشتراک بگذارید:

…
"editorScript": "file:./index.js",
"script": "file:./script.js",
"viewScript": [ "file:./view.js", "example-shared-view-script" ],
"editorStyle": "file:./index.css",
"style": [ "file:./style.css", "example-shared-style" ],
"viewStyle": [ "file:./view.css", "example-view-style" ],
"render": "file:./render.php"
…

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

برای مثال، می‌توانید یک نوع پست موجود را به‌روزرسانی کرده و یک الگوی بلاک به آن اضافه کنید. در اینجا یک مثال ساده آورده شده است:

…
function load_post_type_patterns() {
    // Define an initial pattern for the 'HypnoToad' post type
    $post_type_object = get_post_type_object( 'hypnoToad' );
    $post_type_object->template = array(
    array(
        'core/block',
…

یک راه دیگر فراخوانی قلاب default_content و تعریف Block با استفاده از نشانه گذاری است:

function toad_content( $content, $post ) {
    if ( $post->post_type === 'hypnoToad' ) {
        $content ='<!-- wp:columns -->
        <div class="wp-block-columns"><!-- wp:column →
        <div class="wp-block-column"><!-- wp:paragraph -->
        <p></p>
        <!-- /wp:paragraph --></div>
        <!-- /wp:column -->
        <!-- wp:column -->
        <div class="wp-block-column"><!-- wp:paragraph -->
        <p></p>
        <!-- /wp:paragraph --></div>
        <!-- /wp:column --></div>
        <!-- /wp:columns -->';
    }
    return $content;
}
add_filter( 'default_content', 'toad_content', 10, 2 );

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

استفاده از ویژگی‌های CSS سفارشی برای بلاک‌های خود

می‌توانید با استفاده از ویژگی‌ها، خصوصیات و اشیاء موجود در theme.json به نتایج زیادی دست پیدا کنید، اما این فایل تمام موارد استفاده را پوشش نمی‌دهد. این فایل به شما ویژگی سفارشی‌ای می‌دهد که به کمک آن می‌توانید خصوصیات CSS مرتبط را ایجاد کنید.

{
"version": 3,
  "settings": {
    "custom": {
      "toad": "hypno"
    }
  }
}

در اینجا، یک جفت کلید-مقدار می‌دهید که به یک متغیر CSS در قسمت فرانت تبدیل می‌شود:

body {
    --wp--custom--toad: hypno;
}

{
"version": 3,
  "settings": {
    "custom": {
      "hypnoToad": "active"
    }
  }
}

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

body {
    --wp--custom--hypno-toad: active;
}

بین ویژگی سفارشی و block.json، شما دامنه کاملی برای ایجاد بلوک‌های خود به دلخواه دارید، از جمله هر گونه تغییری که ممکن است بخواهید اضافه کنید.

نگاهی سریع به واریاسیون‌های بلاک، سبک و سبک بلاک

قبل از این که به استایل‌دهی با استفاده از ویژگی blocks بپردازیم، بیایید نگاهی به واریاسیون‌ها بیندازیم. شما چند نوع مختلف از واریاسیون‌ها برای طراحی‌های خود دارید، و نحوه نام‌گذاری ممکن است باعث شود نوع اشتباهی را انتخاب کنید. در اینجا تفاوت‌ها را توضیح می‌دهیم:

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

ممکن است بپرسید که از واریاسیون بلاک استفاده کنید یا واریاسیون سبک بلاک؛ پاسخ ساده است. اگر تغییراتی که می‌خواهید انجام دهید از طریق theme.json یا CSS قابل انجام است، واریاسیون سبک بلاک ایجاد کنید. برای هر چیزی فراتر از این، واریاسیون بلاک نیاز دارید.

واریاسیون‌های بلاک

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

برای blockName، باید namespace را نیز مانند ویژگی blocks مشخص کنید. درون شیء variation، نام، عنوان، توضیحات، اینکه آیا واریاسیون به‌طور پیش‌فرض فعال است یا خیر و موارد دیگر را اضافه می‌کنید. برای بارگذاری فایل در ویرایشگر سایت، کافیست hook به نام enqueue_block_editor_assets را فراخوانی کرده و اسکریپت خود را در آن صف‌بندی کنید.

واریاسیون‌های سبک بلاک

در مورد واریاسیون‌های سبک بلاک، دو گزینه دارید:

• از تابع register_block_style() با PHP استفاده کنید.
• یک فایل block-editor.js جاوااسکریپت ایجاد کنید، تابع registerBlockStyle() را مشابه واریاسیون‌های بلاک استفاده کرده و اسکریپت را صف‌بندی کنید.

هنگامی که یک واریاسیون سبک بلاک را ثبت کردید، می‌توانید بلاک را با استفاده از ویژگی variations هدف قرار دهید.

…
"styles": {
  "blocks": {
    "core/button": {
      "variations": {
        "outline": {
          "border": {
            "color": "var:preset|color|black",
            "radius": "0",
            "style": "solid",
            "width": "3px"
          },
…

این بدان معناست که ممکن است اصلاً به هیچ CSS سفارشی نیاز نداشته باشید – تقریباً همه جنبه های طراحی یک Block از طریق ویژگی blocks امکان پذیر است.

استایل دادن به یک بلوک پیش‌فرض با استفاده از ویژگی blocks از ابتدا تا انتها

برای نشان دادن نحوه عملکرد ویژگی بلوک‌ها، اجازه دهید از طریق یک مثال در دنیای واقعی قدم برداریم. سایت ما از تم Twenty Twenty Four استفاده می کند و از تغییر سبک پیش فرض استفاده می کند:

{
"version": 3,
  "styles": {
    "blocks": {}
  }
}

"blocks": {
  "core/heading": {
    "color": {}
  }
}

حالا که ساختار کارمون تموم شده، می‌تونیم شروع کنیم به تغییر ظاهر متن‌ها.

انتخاب رنگ و اعمال تغییرات

حالا نیاز داریم رنگی رو انتخاب کنیم که مناسب کارمون باشه. تم پیش‌فرض Twenty Twenty-Four پالت رنگ خیلی خوبی داره. اگه این پالت رو توی یه ابزار بررسی کنتراست رنگ بذاریم، ایده‌های خوبی بهمون میده:

…
"core/paragraph": {
    "color": { "text": "var(--wp--preset--color--contrast)" },
…

اگر می‌خواهید نام یک پالت رنگ را بدانید، می‌توانید آن را در ویرایشگر سایت از انتخابگر رنگ پیدا کنید:

"blocks": {
  "core/heading": {
    "color": { "text": "var(--wp--preset--color--accent-3)" }
  },
  "core/paragraph": {
    "color": { "text": "var(--wp--preset--color--contrast)" }
  }
}

پس از ذخیره تغییرات و بازخوانی قسمت فرانت، خواهید دید که Heading Block دارای تعریف بیشتری است:

…
"core/paragraph": {
  "color": { "text": "var(--wp--preset--color--contrast)" },
  "typography": { "dropCap": true }
…

هنگامی که آن تغییرات را ذخیره کردیم و ویرایشگر را بازخوانی کردیم، گزینه تغییر یک drop cap در دسترس شما خواهد بود:

سحن پایانی

درک ویژگی blocks در فایل theme.json یک گام ضروری برای همه توسعه دهندگان تم است. این می تواند یک طراحی کلی را منحصر به فردتر، منسجم تر و مرتبط تر کند. داشتن دامنه کامل برای کار با تنظیمات بلوک های اصلی و سفارشی به هر کاربری کمک می کند تا از قابلیت های ویرایش کامل سایت بهره ببرد. علاوه بر این، در دسترس بودن این گزینه ها در ویرایشگر سایت به این معنی است که کاربران نهایی می توانند بدون نیاز به کد تغییرات خود را ایجاد کنند در حالی که شما گزینه های پیش فرض عالی ارائه می دهید.

آیا سوالی در مورد استفاده از ویژگی blocks با فایل theme.json دارید؟ در بخش نظرات زیر سوال خود را بپرسید!