انتقل إلى المحتوى

إنشاء مكتبة كتل

مكتبة الكتل هي مجموعة من كتل الأقسام المستقلة التي تتحد لتكوين صفحات كاملة. لكل كتلة مخططها وقالبها وتنسيقها الخاص. يوفر Blockstudio إطار العمل: معالجة Tailwind CSS، وتسجيل السمات، ومزامنة الصفحات. أما الكتل فتتولاها أنت.

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

بنية المجلدات

تتبع كل قوالب Blockstudio التخطيط نفسه:

الكود
my-theme/
├── style.css                           # WordPress header + Tailwind v4 config
├── blockstudio.json                    # Blockstudio settings
├── functions.php                       # Section helper + Tailwind filter
├── index.php                           # Main WordPress template
├── blockstudio/
│   ├── fields/
│   │   └── section/
│   │       └── field.json              # Shared section controls
│   └── sections/
│       ├── hero/
│       │   ├── block.json
│       │   └── index.php
│       └── features/
│           ├── block.json
│           └── index.php
└── pages/
    └── home/
        ├── page.json
        └── index.php

توجد الكتل في blockstudio/sections/. وكل كتلة مجلد يحتوي على مخطط block.json وقالب index.php. أما الصفحات فتوجد في pages/ وتجمع الكتل باستخدام صياغة <block>.

ملفات الأساس

blockstudio.json

يضبط هذا الملف طريقة معالجة Blockstudio لقالبك. الإعدادات واحدة في كل القوالب:

JSON
{
	"assets": {
		"enqueue": true,
		"reset": {
			"enabled": true,
			"fullWidth": ["page"]
		},
		"minify": { "css": true, "js": true },
		"process": { "scss": false, "scssFiles": true }
	},
	"tailwind": {
		"enabled": true,
		"config": ""
	},
	"dev": {
		"canvas": { "enabled": true }
	},
	"$schema": "https://blockstudio.dev/schema/blockstudio"
}

يزيل reset أنماط كتل WordPress الافتراضية. ويجعل fullWidth أنواع منشورات page بعرض كامل. أما canvas فيفعّل وضع لوحة المحرر لتجربة تحرير أنظف.

حقل tailwind.config فارغ عمدًا. مع Tailwind v4، يوجد الإعداد كله في style.css باتباع نهج يبدأ بـCSS.

index.php

القالب الرئيسي لـWordPress. هذا WordPress اعتيادي ولا يتضمن شيئًا خاصًا بـBlockstudio:

PHP
<!DOCTYPE html>
<html <?php language_attributes(); ?>>
<head>
	<meta charset="<?php bloginfo( 'charset' ); ?>">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<?php wp_head(); ?>
</head>
<body <?php body_class(); ?>>
<?php wp_body_open(); ?>

<main>
<?php
if ( have_posts() ) {
	while ( have_posts() ) {
		the_post();
		the_content();
	}
}
?>
</main>

<?php wp_footer(); ?>
</body>
</html>

أضف header.php وfooter.php عند الحاجة إلى التنقل. يكفي الآن قالب بسيط لعرض الكتل.

رموز التصميم

تتم كل عمليات تصميم القالب في style.css باستخدام التوجيه @theme في Tailwind v4. وهذا جوهر نظام التصميم لديك.

CSS
/*
Theme Name: My Theme
Theme URI: https://example.com
Description: A clean theme built with Blockstudio.
Version: 1.0.0
Requires at least: 6.0
Requires PHP: 8.2
Author: Your Name
Text Domain: my-theme
*/

@theme {
	--font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
	--color-bg: #050505;
	--color-elevated: #111111;
	--color-subtle: rgb(255 255 255 / 0.06);
	--color-muted: #888888;
	--color-accent: #6366f1;
	--color-accent-hover: #4f46e5;
}

يحتاج كل قالب إلى الأقل إلى:

الرمز الغرض
--font-sans أو --font-serif الخط الأساسي
--color-bg خلفية الصفحة
--color-elevated خلفية البطاقة/السطح
--color-subtle الحدود والفواصل
--color-muted النص الثانوي
--color-accent لون العلامة التجارية الأساسي

تُنشئ هذه الرموز أدوات Tailwind تلقائيًا. يتحول --color-accent إلى bg-accent وtext-accent وborder-accent وما إلى ذلك.

لإنشاء قالب فاتح، اعكس القيم:

CSS
@theme {
	--font-serif: 'Zilla Slab', serif;
	--font-sans: 'DM Sans', sans-serif;
	--color-bg: #f5f0e8;
	--color-elevated: #ece6da;
	--color-heading: #2c1810;
	--color-body: #6b5c4f;
	--color-muted: #9a8b7d;
	--color-accent: #2d5016;
	--color-subtle: #d9d1c4;
}

الأنماط الأساسية والأدوات المساعدة

أضف أنماط الجسم والإعدادات الافتراضية للطبقة الأساسية والأدوات المساعدة المخصصة أسفل كتلة @theme.

يجب أن تكون أنماط الجسم خارج @layer حتى يلتقطها محرر WordPress:

CSS
body {
	@apply bg-bg font-sans text-white antialiased;
}

الطبقة الأساسية للإعدادات الافتراضية للعناصر:

CSS
@layer base {
	section {
		@apply relative overflow-hidden;
	}

	h1, h2, h3 {
		text-wrap: balance;
	}

	p {
		text-wrap: pretty;
	}
}

الأدوات المساعدة المخصصة للأنماط القابلة لإعادة الاستخدام. يعرّف كل قالب أداة container مساعدة لتوحيد المسافات بين الأقسام، وعادةً ما يعرّف card وbadge وأدوات الأزرار:

CSS
@utility container-px {
	@apply mx-auto max-w-5xl px-6;
}

@utility container {
	@apply container-px py-24 sm:py-32;
}

@utility container-no-pb {
	@apply pb-0 sm:pb-0;
}

@utility card {
	@apply rounded-2xl border border-subtle bg-elevated/80 p-8 transition-all duration-300;

	&:hover {
		border-color: rgb(255 255 255 / 0.1);
	}
}

@utility badge {
	@apply inline-flex items-center gap-2 rounded-full border border-subtle bg-white/5 px-3.5 py-1.5 text-sm text-muted;
}

@utility btn-primary {
	@apply inline-flex items-center gap-2 rounded-full bg-accent px-6 py-3 text-sm font-medium text-white transition-colors;

	&:hover {
		@apply bg-accent-hover;
	}
}

@utility btn-secondary {
	@apply inline-flex items-center gap-2 rounded-full border border-subtle px-6 py-3 text-sm font-medium text-white transition-all;

	&:hover {
		border-color: rgb(255 255 255 / 0.15);
		background: rgb(255 255 255 / 0.04);
	}
}

ضع المحددات الزائفة داخل كتلة @utility باستخدام التداخل في CSS (&:hover). لا تضعها مطلقًا في اسم الأداة. @utility btn-primary:hover {} غير صالح وسيُرفض بواسطة Tailwind.

تضمين @source مباشرة

يمسح Blockstudio قوالب الكتل تلقائيًا بحثًا عن أصناف Tailwind. لكن لا تُمسح الأصناف المستخدمة خارج قوالب الكتل (في functions.php وheader.php وindex.php). أعلِن عنها باستخدام @source inline:

CSS
@source inline("bg-bg bg-accent-tint container container-px container-no-pb");

يطلب هذا من Tailwind تضمين هذه الأصناف في الناتج، حتى لو لم تظهر إلا في ملفات PHP التي لا يجري مسحها.

نمط القسم

نمط القسم هو أهم اصطلاح في مكتبة كتل Blockstudio. فهو يمنح كل كتلة مسافات متسقة، وإمكانية تبديل الخلفية، والتحكم في الحشو من خلال آليتين مشتركتين: حقل مخصص ومساعد PHP.

حقل القسم

أنشئ تعريفًا مشتركًا للحقل يمكن لكل كتلة الإشارة إليه:

JSON
{
	"$schema": "https://blockstudio.dev/schema/field",
	"name": "section",
	"title": "Section",
	"attributes": [
		{
			"type": "group",
			"attributes": [
				{
					"id": "removeBottomPadding",
					"type": "toggle",
					"label": "Remove bottom padding"
				},
				{
					"id": "accentBg",
					"type": "toggle",
					"label": "Accent background"
				}
			]
		}
	]
}

يظهر هذا الحقل في لوحة فحص كل كتلة ضمن علامة تبويب «القسم». ويحصل العملاء على عنصرَي تحكم: تبديل خلفية مميزة، وإزالة الحشو السفلي (وهو مفيد لتكديس الأقسام بلا فجوات).

مساعد القسم

أنشئ في functions.php مساعدًا يحوّل هذه السمات إلى أصناف CSS:

PHP
<?php
/**
 * My Theme functions.
 *
 * @package My_Theme
 */

/**
 * Returns section and container class strings based on block attributes.
 *
 * @param array  $a               Block attributes.
 * @param string $extra_section   Additional classes for the section element.
 * @param string $extra_container Additional classes for the container element.
 * @return array Array of [ section_classes, container_classes ].
 */
function mytheme_section_classes( array $a, string $extra_section = '', string $extra_container = '' ): array {
	$section   = ! empty( $a['accentBg'] ) ? 'bg-accent-tint' : 'bg-bg';
	$container = 'container';

	if ( ! empty( $a['removeBottomPadding'] ) ) {
		$container .= ' container-no-pb';
	}

	if ( $extra_section ) {
		$section .= ' ' . $extra_section;
	}

	if ( $extra_container ) {
		$container .= ' ' . $extra_container;
	}

	return array( $section, $container );
}

يستدعي كل قالب كتلة هذا المساعد في سطره الأول. ويعيد المساعد سلسلتَي أصناف: واحدة لعنصر <section> الخارجي، وأخرى للحاوية <div> الداخلية.

مرشح إعدادات Tailwind

أضف أيضًا في functions.php المرشح الذي يمرر style.css إلى معالج Tailwind في Blockstudio:

PHP
add_filter(
	'blockstudio/settings/tailwind/config',
	function () {
		$style = get_stylesheet_directory() . '/style.css';

		if ( file_exists( $style ) ) {
			// phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- Reading local theme file.
			return file_get_contents( $style );
		}

		return '';
	}
);

يطلب هذا من Blockstudio استخدام style.css بوصفه مصدر إعدادات Tailwind v4. ومن دونه، لن تتوفر رموز @theme وتعريفات @utility في قوالب الكتل.

كتلتك الأولى: القسم الرئيسي

يوضح القسم الرئيسي نمط الكتلة كاملًا. ابدأ بالمخطط:

JSON
{
	"$schema": "https://blockstudio.dev/schema/block",
	"name": "my-theme/hero",
	"title": "Hero",
	"category": "my-theme",
	"icon": "star-filled",
	"description": "Full-width hero section with heading, description, and buttons.",
	"blockstudio": {
		"attributes": [
			{
				"type": "tabs",
				"tabs": [
					{
						"title": "Content",
						"attributes": [
							{
								"type": "group",
								"attributes": [
									{
										"id": "heading",
										"type": "text",
										"label": "Heading",
										"default": "Build beautiful websites without the complexity"
									},
									{
										"id": "description",
										"type": "textarea",
										"label": "Description",
										"default": "A powerful framework that lets you create stunning designs using the WordPress editor."
									}
								]
							},
							{
								"type": "group",
								"attributes": [
									{
										"id": "primaryButton",
										"type": "link",
										"label": "Primary Button",
										"default": {
											"title": "Get Started",
											"url": "#"
										}
									},
									{
										"id": "secondaryButton",
										"type": "link",
										"label": "Secondary Button",
										"default": {
											"title": "Learn More",
											"url": "#"
										}
									}
								]
							}
						]
					},
					{
						"title": "Section",
						"attributes": [
							{ "type": "custom/section" }
						]
					}
				]
			}
		]
	}
}

أنماط أساسية جديرة بالملاحظة:

ينشئ الغلاف tabs لوحة فحص بعلامتَي تبويب: «المحتوى» لحقول الكتلة و«القسم» لعناصر التحكم المشتركة بالقسم. تستخدم كل كتلة هذه البنية.

تُنظم الحقول داخل حاويات group. تفصل المجموعات الحقول المرتبطة بصريًا في لوحة الفحص. تضم المجموعة الأولى حقول النص، والثانية حقول الروابط.

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

والآن القالب:

PHP
<?php list( $section_classes, $container_classes ) = mytheme_section_classes( $a, '', 'text-center' ); ?>

<section useBlockProps class="<?php echo esc_attr( $section_classes ); ?>">
	<div class="<?php echo esc_attr( $container_classes ); ?>">
		<h1 class="text-5xl font-medium tracking-tight sm:text-6xl lg:text-7xl">
			<?php echo esc_html( $a['heading'] ); ?>
		</h1>

		<?php if ( ! empty( $a['description'] ) ) : ?>
			<p class="mt-6 text-lg leading-relaxed text-muted max-w-xl mx-auto">
				<?php echo esc_html( $a['description'] ); ?>
			</p>
		<?php endif; ?>

		<div class="mt-10 flex items-center justify-center gap-x-4">
			<?php if ( ! empty( $a['primaryButton']['url'] ) ) : ?>
				<a href="<?php echo esc_url( $a['primaryButton']['url'] ); ?>" class="btn-primary">
					<?php echo esc_html( $a['primaryButton']['title'] ); ?>
				</a>
			<?php endif; ?>

			<?php if ( ! empty( $a['secondaryButton']['url'] ) ) : ?>
				<a href="<?php echo esc_url( $a['secondaryButton']['url'] ); ?>" class="btn-secondary">
					<?php echo esc_html( $a['secondaryButton']['title'] ); ?>
				</a>
			<?php endif; ?>
		</div>
	</div>
</section>

يتبع القالب نمطًا ثابتًا:

  1. استدعاء مساعد القسم للحصول على أصناف CSS
  2. عنصر <section> خارجي مع useBlockProps وأصناف القسم
  3. عنصر <div> داخلي مع أصناف الحاوية
  4. عرض المحتوى من $a (الاختصار الخاص بالسمات)
  5. عرض شرطي للحقول الاختيارية
  6. تهريب صحيح: esc_html() للنص، وesc_url() لعناوين URL، وesc_attr() للسمات

إضافة العناصر المتكررة: شبكة الميزات

تتيح العناصر المتكررة للعملاء إضافة العناصر وإزالتها وإعادة ترتيبها. وشبكة الميزات مثال تقليدي:

JSON
{
	"$schema": "https://blockstudio.dev/schema/block",
	"name": "my-theme/features",
	"title": "Features",
	"category": "my-theme",
	"icon": "grid-view",
	"description": "Feature grid with titles and descriptions.",
	"blockstudio": {
		"attributes": [
			{
				"type": "tabs",
				"tabs": [
					{
						"title": "Content",
						"attributes": [
							{
								"type": "group",
								"attributes": [
									{
										"id": "heading",
										"type": "text",
										"label": "Heading",
										"default": "Everything you need"
									},
									{
										"id": "description",
										"type": "textarea",
										"label": "Description",
										"default": "Our toolkit gives you the building blocks to go from idea to production."
									}
								]
							},
							{
								"type": "group",
								"attributes": [
									{
										"id": "features",
										"type": "repeater",
										"label": "Features",
										"textMinimized": {
											"id": "title",
											"fallback": "Feature"
										},
										"default": [
											{
												"title": "Lightning Fast",
												"description": "Optimized for performance with minimal overhead."
											},
											{
												"title": "Fully Responsive",
												"description": "Every component adapts across all screen sizes."
											},
											{
												"title": "Easy to Customize",
												"description": "Adjust every detail to match your brand."
											}
										],
										"attributes": [
											{
												"id": "title",
												"type": "text",
												"label": "Title"
											},
											{
												"id": "description",
												"type": "textarea",
												"label": "Description"
											}
										]
									}
								]
							}
						]
					},
					{
						"title": "Section",
						"attributes": [
							{ "type": "custom/section" }
						]
					}
				]
			}
		]
	}
}

تحدد الخاصية textMinimized النص الظاهر عند طي صف عنصر متكرر. وهي تقرأ قيمة الحقل title، وتعرض «الميزة» إذا كان فارغًا. وهذا يجعل لوحة الفحص سهلة الاستخدام عند وجود عناصر كثيرة.

توفر مصفوفة default عناصر أولية تظهر عند إدراج الكتلة للمرة الأولى. احرص دائمًا على توفير قيم افتراضية واقعية كي تبدو الكتلة مكتملة فورًا.

PHP
<?php list( $section_classes, $container_classes ) = mytheme_section_classes( $a ); ?>

<section useBlockProps class="<?php echo esc_attr( $section_classes ); ?>">
	<div class="<?php echo esc_attr( $container_classes ); ?>">
		<?php if ( ! empty( $a['heading'] ) ) : ?>
			<div class="text-center max-w-2xl mx-auto">
				<h2 class="text-3xl font-medium tracking-tight sm:text-4xl">
					<?php echo esc_html( $a['heading'] ); ?>
				</h2>

				<?php if ( ! empty( $a['description'] ) ) : ?>
					<p class="mt-4 text-base leading-relaxed text-muted">
						<?php echo esc_html( $a['description'] ); ?>
					</p>
				<?php endif; ?>
			</div>
		<?php endif; ?>

		<?php if ( ! empty( $a['features'] ) ) : ?>
			<div class="mt-16 grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
				<?php foreach ( $a['features'] as $feature ) : ?>
					<div class="card">
						<h3 class="text-sm font-medium">
							<?php echo esc_html( $feature['title'] ); ?>
						</h3>
						<p class="mt-2 text-sm leading-relaxed text-muted">
							<?php echo esc_html( $feature['description'] ); ?>
						</p>
					</div>
				<?php endforeach; ?>
			</div>
		<?php endif; ?>
	</div>
</section>

يمكن الوصول إلى عناصر المتكرر على هيئة مصفوفة PHP عادية. كرر باستخدام foreach، واستدعِ حقول كل عنصر عبر id الخاص به.

الصور والعناصر النائبة

للكتل التي تتضمن صورًا، استخدم نوع الحقل files والمكوّن MediaPlaceholder. تعرض العنصر النائب منطقة سحب وإفلات في المحرر:

JSON
{
	"id": "image",
	"type": "files",
	"label": "Image"
}

في القالب، اعرض الصورة باستخدام wp_get_attachment_image() وأظهر SVG نائبًا عند عدم تحديد صورة:

PHP
<div class="overflow-hidden rounded-2xl bg-elevated">
	<MediaPlaceholder attribute="image" allowedTypes="<?php echo esc_attr( wp_json_encode( array( 'image' ) ) ); ?>" />
	<?php if ( ! empty( $a['image'] ) ) : ?>
		<?php echo wp_get_attachment_image( $a['image'][0]['ID'], 'full', false, array( 'class' => 'block w-full' ) ); ?>
	<?php else : ?>
		<?php echo blockstudio_placeholder_dark(); ?>
	<?php endif; ?>
</div>

يعيد blockstudio_placeholder_dark() ملف SVG مضمنًا يستخدم currentColor مع المتغير --color-accent، فيتكيف تلقائيًا مع قالبك. للقوالب الفاتحة، استخدم blockstudio_placeholder_light(). ويقبل كلاهما وسيطة للتنوع:

PHP
blockstudio_placeholder_dark( 'dashboard' )  // Dashboard mockup
blockstudio_placeholder_dark( 'chart' )      // Chart illustration
blockstudio_placeholder_dark( 'product' )    // Product shot

تكوين الصفحات

تجمع الصفحات الكتل لتكوين تخطيطات كاملة باستخدام صياغة <block>. أنشئ صفحة رئيسية:

JSON
{
	"name": "home",
	"title": "Home",
	"slug": "home",
	"postType": "page",
	"postStatus": "publish",
	"templateLock": "all"
}
PHP
<block name="my-theme/hero"></block>
<block name="my-theme/features"></block>

هذا كل شيء. يدرج كل عنصر <block> الكتلة بقيم سماتها الافتراضية. شغّل wp bs pages sync لتطبيق مصدر الصفحة على WordPress.

لتجاوز القيم الافتراضية لصفحة معينة، مرّر السمات مباشرةً:

PHP
<block name="my-theme/hero" heading="About Us" description="Our story and mission."></block>
<block name="my-theme/features" heading="Our Values"></block>

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

التوسع

تبدأ المكتبة البسيطة بثلاث إلى خمس كتل، بينما تضم المكتبة الشاملة من 8 إلى 14 كتلة. إليك أنواع الكتل الشائعة، مرتبة تقريبًا بحسب معدل ظهورها:

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

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

إضافة صفحات أخرى

مع نمو مكتبتك، أنشئ صفحات مختلفة من الكتل نفسها:

PHP
<block name="my-theme/hero" heading="Simple, Transparent Pricing" description="Choose the plan that fits."></block>
<block name="my-theme/pricing"></block>
<block name="my-theme/faq" heading="Pricing FAQ"></block>
<block name="my-theme/cta"></block>
PHP
<block name="my-theme/hero" heading="About Us" description="Our story."></block>
<block name="my-theme/team"></block>
<block name="my-theme/testimonials"></block>
<block name="my-theme/cta" heading="Join Our Team"></block>

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

الخطوات التالية