التخزين
افتراضيًا، تُخزّن جميع قيم الحقول كسمات للكتلة ضمن تعليق الكتلة في محتوى المنشور. وتتيح ميزة التخزين حفظ القيم أيضًا في البيانات الوصفية للمنشور (wp_postmeta) أو الخيارات (wp_options)، لتصبح متاحة خارج سياق الكتلة.
لماذا تستخدم التخزين؟
تُخزّن سمات الكتلة داخل تعليقات HTML في محتوى المنشور، ما يعني أنها لا تتاح إلا عند تحليل محتوى الكتلة. وباستخدام مواقع تخزين إضافية، يمكنك:
- الاستعلام عن المنشورات بحسب قيم الحقول باستخدام
meta_query - الوصول إلى القيم عبر REST API في الإعدادات دون واجهة أمامية
- مشاركة البيانات مع إضافات أخرى مثل SEO أو إضافات التخزين المؤقت
- إنشاء إعدادات عامة تظل محفوظة بين المنشورات
أنواع التخزين
| النوع | الموقع | النطاق | الأنسب لـ |
|---|---|---|---|
postMeta |
جدول wp_postmeta |
لكل منشور | بيانات خاصة بمنشور يمكن الاستعلام عنها |
option |
جدول wp_options |
عام (على مستوى الموقع) | إعدادات الموقع والقيم المشتركة |
ملاحظة
يحدث تخزين سمات الكتلة (في تعليق محتوى المنشور HTML) تلقائيًا دائمًا. تضيف الخاصية
storageمواقع تخزين إضافية، ولا تستبدل تخزين الكتلة.
الإعداد
أضف الخاصية storage إلى أي تعريف حقل:
{
"name": "blockstudio/example",
"title": "Example Block",
"blockstudio": {
"attributes": [
{
"id": "subtitle",
"type": "text",
"label": "Subtitle",
"storage": {
"type": "postMeta",
"postMetaKey": "my_subtitle"
}
}
]
}
}
خصائص التخزين
| الخاصية | النوع | الوصف |
|---|---|---|
type |
string | string[] |
موقع تخزين إضافي location(s): "postMeta"، "option" |
postMetaKey |
string |
مفتاح بيانات وصفية مخصص (الافتراضي: {block_name}_{field_id}) |
optionKey |
string |
مفتاح خيار مخصص (الافتراضي: {block_name}_{field_id}) |
تخزين مفرد أو متعدد
// Add post meta storage
"storage": {
"type": "postMeta"
}
// Add both post meta and option storage
"storage": {
"type": ["postMeta", "option"]
}
آلية العمل
- التسجيل: عند تحميل WordPress، يسجّل Blockstudio مفاتيح البيانات الوصفية والإعدادات بناءً على إعدادات حقولك
- التحرير: تُدار القيم كسمات للكتلة في المحرر (وتُخزّن دائمًا في الكتلة)
- الحفظ: تُزامَن البيانات الوصفية للمنشور عند حفظه. وتُزامَن خيارات الموقع عند نشر المنشور أو تغيير قيمة حقل في منشور منشور.
لا تزامن عمليات الحفظ التلقائي والمراجعات أيًا من موقعي التخزين. ويمكن للمسودات والمنشورات المعلّقة والخاصة والمجدولة تحديث بياناتها الوصفية الخاصة، لكنها لا تغيّر خيارات الموقع الفعلية. وتُزامَن الخيارات عند نشر المنشور المجدول بواسطة WordPress.
تُنسخ القيم حرفيًا، بما في ذلك الشرطات المائلة العكسية وعلامات الاقتباس وقيم المكررات المتداخلة. لا تضف تهريبًا إلى قيم الحقول للتعويض عن تخزين البيانات الوصفية في WordPress؛ إذ يتولى Blockstudio معالجة هذا الحد الفاصل. وتحتفظ خيارات الموقع بالقيم الحرفية نفسها من دون إضافة شرطات مائلة.
إذا أزالت نسخة سابقة الشرطات المائلة العكسية من نسخة البيانات الوصفية للمنشور، فأعد حفظ المنشور بعد الترقية. تُستخدم قيمة الحقل الأصلية في سمات الكتلة لتحديث نسخة البيانات الوصفية.
حفظ خيارات الموقع
تُشارك الخيارات على مستوى الموقع بأكمله. يؤدي نشر كتلة جديدة إلى كتابة حقول الخيارات الواردة في سماتها المحفوظة. وتقارن عمليات الحفظ اللاحقة كل حقل بنسخته المحفوظة السابقة من تلك الكتلة، ولا تكتب إلا القيم التي تغيّرت. ولا يؤدي حفظ عنوان المنشور أو نسخة قديمة لم تتغير من الكتلة في منشور آخر إلى استبدال قيمة خيار أحدث.
إذا لم يُدرج حقل في السمات المحفوظة، يبقى خياره كما هو. ويحمي ذلك أيضًا الخيارات الحالية عند إضافة حقل جديد إلى block.json. يؤدي استخدام null صراحةً إلى حذف خيار، بينما تُحفظ السلاسل الفارغة وfalse و0 والمصفوفات الفارغة كقيم. ولا يؤدي حذف كتلة إلى حذف خياراتها.
استخدم كتلة منشورة مخصصة لإدارة كل خيار مشترك. إذا غيّرت كتل متعددة الخيار نفسه عمدًا، فستسود آخر قيمة متغيرة تم حفظها. ولا يحمّل التخزين الخيار الحالي إلى كل كتلة؛ إذ تحتفظ كل كتلة بقيم حقولها الخاصة في محتوى المنشور.
في الصفحات المعتمدة على الملفات، يتيح مفتاح دائم للكتلة key لـBlockstudio التعرّف على الكتلة نفسها بعد نقلها في المستند. أما الكتل التي لا تملك مفتاحًا فتُطابق بحسب اسم الكتلة وموضعها.
الوصول إلى القيم المخزنة
في قوالب الكتل
تكون قيم الحقول متاحة دائمًا داخل قالب الكتلة عبر $attributes:
PHP
<div>
<h1><?php echo $a['subtitle']; ?></h1>
</div>
Twig
<div>
<h1>{{ a.subtitle }}</h1>
</div>
البيانات الوصفية للمنشور (خارج سياق الكتلة)
يمكن الوصول إلى القيم المخزنة في postMeta من أي مكان في WordPress:
PHP
// Get meta value
$subtitle = get_post_meta( $post_id, 'my_subtitle', true );
// Query posts by meta value
$posts = get_posts([
'meta_key' => 'my_subtitle',
'meta_value' => 'Hello World',
]);
Twig
{# Using Timber #}
{{ post.meta('my_subtitle') }}
{# Or via function #}
{{ function('get_post_meta', post.id, 'my_subtitle', true) }}
تتوفر البيانات الوصفية للمنشور أيضًا عبر REST API:
GET /wp-json/wp/v2/posts/123
# Response includes: { "meta": { "my_subtitle": "Hello World" } }
الخيارات (قيم عامة)
يمكن الوصول إلى القيم المخزنة في option على مستوى الموقع:
PHP
$company_name = get_option( 'site_company_name' );
Twig
{{ function('get_option', 'site_company_name') }}
أمثلة
حقول البيانات الوصفية لـ SEO
خزّن بيانات SEO في البيانات الوصفية للمنشور لتتوافق مع إضافات SEO:
{
"blockstudio": {
"attributes": [
{
"id": "seo_title",
"type": "text",
"label": "SEO Title",
"storage": {
"type": "postMeta",
"postMetaKey": "_yoast_wpseo_title"
}
},
{
"id": "seo_description",
"type": "textarea",
"label": "Meta Description",
"storage": {
"type": "postMeta",
"postMetaKey": "_yoast_wpseo_metadesc"
}
}
]
}
}
محتوى مميز مع إمكانية الاستعلام
أضف تخزين البيانات الوصفية للمنشور لإتاحة الاستعلام عن المنشورات بحسب قيمة الحقل:
{
"blockstudio": {
"attributes": [
{
"id": "featured",
"type": "toggle",
"label": "Featured",
"storage": {
"type": "postMeta",
"postMetaKey": "is_featured"
}
}
]
}
}
استعلم عن المنشورات المميزة:
$featured_posts = get_posts([
'meta_key' => 'is_featured',
'meta_value' => '1',
]);
إعدادات الموقع العامة
خزّن الإعدادات العامة للموقع في الخيارات:
{
"blockstudio": {
"attributes": [
{
"id": "company_name",
"type": "text",
"label": "Company Name",
"storage": {
"type": "option",
"optionKey": "site_company_name"
}
},
{
"id": "support_email",
"type": "text",
"label": "Support Email",
"storage": {
"type": "option",
"optionKey": "site_support_email"
}
}
]
}
}
يمكنك الوصول إليها في أي مكان على موقعك:
<footer>
<p>© <?php echo get_option( 'site_company_name' ); ?></p>
<p>Contact: <?php echo get_option( 'site_support_email' ); ?></p>
</footer>
البيانات الوصفية للمنشور والخيار
للبيانات التي يلزم إتاحتها على مستوى المنشور وعلى المستوى العام:
{
"blockstudio": {
"attributes": [
{
"id": "important_value",
"type": "text",
"label": "Important Value",
"storage": {
"type": ["postMeta", "option"],
"postMetaKey": "important_meta",
"optionKey": "important_option"
}
}
]
}
}
أسماء المفاتيح الافتراضية
إذا لم تحدد مفتاحًا مخصصًا، ينشئ Blockstudio مفتاحًا تلقائيًا:
| نوع التخزين | تنسيق المفتاح الافتراضي | مثال |
|---|---|---|
postMeta |
{block_name}_{field_id} |
blockstudio_example_subtitle |
option |
{block_name}_{field_id} |
blockstudio_example_subtitle |
يُنظّف اسم الكتلة (باستبدال الشرطات المائلة بخطوط سفلية).
تحذير
يُوصى باستخدام مفاتيح مخصصة في بيئة الإنتاج. قد تتغير المفاتيح الافتراضية إذا غيّرت اسم الكتلة.