نقدم نوعًا جديدًا type: objects في أنواع إعدادات القوالب المدعومة، والذي يمكن استخدامه كبديل للنوع json_schema الموجود، والذي ننوي إيقاف استخدامه قريبًا.
تعريف إعداد قالب من نوع objects
لإنشاء إعداد قالب من نوع objects، حدد أولًا مفتاحًا على المستوى الأعلى تمامًا مثل أي إعداد قالب آخر، والذي سيُستخدم كاسم للإعداد.
links: ...
بعد ذلك، أضف الكلمات المفتاحية type وdefault وschema إلى الإعداد.
links:
type: objects
default: []
schema: ...
تشير type: objects إلى أن هذا سيكون إعدادًا من نوع objects، بينما تحدد التعليق default: [] القيمة الافتراضية للإعداد إلى مصفوفة فارغة. لاحظ أن القيمة الافتراضية يمكن أيضًا ضبطها على مصفوفة من الكائنات، وهو ما سنوضحه بمجرد تعريف schema.
لتعريف المخطط (schema)، حدد أولًا name للمخطط على النحو التالي:
links:
type: objects
default: []
schema:
name: link
بعد ذلك، سنضيف الكلمة المفتاحية properties إلى المخطط، والتي ستسمح لنا بتحقق وتحديد كيفية ظهور كل كائن.
links:
type: objects
default: []
schema:
name: link
properties:
name: ...
في المثال أعلاه، نحن نقرر أن الكائن link يحتوي على الخاصية name. لتحديد نوع البيانات المتوقعة، يجب أن تُعرّف كل خاصية الكلمة المفتاحية type.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
يحدد تعريف المخطط أعلاه أن الكائن link يحتوي على الخاصية name من نوع string، مما يعني أنه سيتم قبول قيم نصية فقط لهذه الخاصية. حاليًا، الأنواع التالية مدعومة:
-
string: يتم تخزين قيمة الخاصية كنص. ضعtextarea: trueلاستخدام منطقة نص قابلة للتوسيع:description: type: string textarea: true validations: max_length: 500 -
integer: يتم تخزين قيمة الخاصية كعدد صحيح. -
float: يتم تخزين قيمة الخاصية كعدد عشري. -
boolean: قيمة الخاصية هيtrueأوfalse. -
upload: قيمة الخاصية هي رابط المرفق (URL). -
enum: يجب أن تكون قيمة الخاصية إحدى القيم المحددة في الكلمة المفتاحيةchoices.links: type: objects default: [] schema: name: link properties: name: type: enum choices: - name 1 - name 2 - name 3 -
categories: قيمة الخاصية هي مصفوفة من معرفات الفئات الصالحة. -
groups: قيمة الخاصية هي مصفوفة من معرفات المجموعات الصالحة. -
tags: قيمة الخاصية هي مصفوفة من أسماء الوسوم (Tags) الصالحة. -
icon: قيمة الخاصية هي اسم لأيقونة واحدة من مجموعة أيقونات Discourse. يتم إضافة الأيقونات المحددة تلقائيًا إلى ورقة الرقعة (sprite sheet)، بحيث يمكن عرضها دون تسجيلها بشكل منفصل.
عند تحديث إعداد قالب من نوع objects عبر واجهة برمجة التطبيقات (API)، يمكن أن تحتوي مصفوفات tags على أسماء الوسوم المصدرية، معرفات الوسوم الرقمية، أو كليهما. يتم تحويل المعرفات إلى أسماء مصدرية قبل التحقق والتخزين. لا تزال القوالب تتلقى مصفوفات من الأسماء المصدرية. تُعامل السلاسل الرقمية كأسماء، وليست معرفات، ويجب أن تستخدم القيم الافتراضية الأسماء.
تتضمن عارضة الوسوم في الواجهة الأمامية الافتراضية data-tag-id لكائنات الوسوم التي لها معرف، أو لأسماء الوسوم التي تُعرض باستخدام خيار tagId. لم تتغير السمة data-tag-name الموجودة. يبقى المعرف ثابتًا عبر اللغات حتى لو تغير الاسم المعروض. تستدعيات العرض بالاسم فقط دون معرف تتجاهل data-tag-id.
الكائنات ذات الخصائص المباشرة tags تتلقى تلقائيًا مصفوفة مرافقة tag_objects في إعدادات الواجهة الأمامية:
{
tags: ["support"],
tag_objects: [
{ id: 42, name: "support" }
]
}
لم تتغير مصفوفات أسماء الوسوم الموجودة. يحتوي كل كائن مرافق على معرف الوسم والسلسلة الأصلية الدقيقة للاسم المصدري من الإعداد، بما في ذلك حالة الأحرف. لا يستبدل اسم العرض المترجم. يمكن للمكونات استخدام المعرفات للإشارة إلى الوسوم المحددة، على سبيل المثال عند استهداف data-tag-id في CSS. لا يقوم النواة (Core) بعرض المصفوفة المرفقة كواجهة مستخدم ولا يضيف إعداد إداري لها.
يجمع المرافق بين اختيارات tags المباشرة للكائن بترتيبها الأصلي، مع الحفاظ على الاختيارات المكررة. تحصل الكائنات المتداخلة على مرافقاتها الخاصة. يتم تضمين الوسوم المرئية للزائر فقط؛ يتم تجاهل الاختيارات المفقودة، المحذوفة أو المخفية. يظل المرافق موجودًا كـ [] عندما لا تحل أي وسوم. لا تفترض أن فهارسه تطابق مصفوفة السلاسل الأصلية.
لا يلزم الاشتراك اليدوي أو طلب إضافي لواجهة برمجة التطبيقات للمتصفح. تعطي خاصية مخطط يسميها المؤلف tag_objects الأولوية: يحافظ النواة على هذا الحقل ولا يولد مرافقًا على هذا المستوى. اعلن عن أي حقل مخصص موجود بهذا الاسم؛ قيم tag_objects غير المعلنة تعامل كبيانات وصفية مولدة وتزال. الكائنات التي لا تحتوي على خصائص tags مباشرة وإعدادات قائمة الوسوم القديمة على المستوى الأعلى لم تتغير.
يتم توليد المرافق فقط لبيانات صفحة الواجهة الأمامية. تحافظ الإعدادات المخزنة وقيم التحرير الإداري على شكلها الحالي؛ البيانات الوصفية المولدة المرسلة مرة أخرى عبر واجهة برمجة تطبيقات الإعدادات تُرمى. يمكن للمكونات التي تدعم سياقات أو إصدارات Discourse القديمة دون هذه البيانات التحقق من Array.isArray(style.tag_objects) والرجوع إلى سلوكها القديم القائم على الأسماء عندما لا تكون متاحة.
بعد تعريف المخطط، يمكن الآن ضبط القيمة الافتراضية للإعداد عن طريق تحديد مصفوفة في YAML كما يلي:
links:
type: objects
default:
- name: link 1
title: link 1 title
- name: link 2
title: link 2 title
schema:
name: link
properties:
name:
type: string
title:
type: string
الخصائص المطلوبة
جميع الخصائص المحددة اختيارية افتراضيًا. لتمييز خاصية كمطلوبة، ما عليك سوى إضافة التعليق required: true إلى الخاصية. يمكن أيضًا تمييز خاصية كاختيارية عن طريق إضافة التعليق required: false.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
title:
type: string
required: false
قيم string، datetime وicon الفارغة، وقوائم categories، groups وtags الفارغة تُحسب كقيّم مفقودة: ترفض الخصائص المطلوبة تلك، وتتخطى الخصائص الاختيارية عمليات التحقق الخاصة بها. تُحسب القيمة false كمضبوطة.
عمليات التحقق المخصصة
بالنسبة لأنواع خصائص معينة، هناك دعم مدمج لعمليات التحقق المخصصة التي يمكن إعلانها عن طريق إضافة التعليق validations إلى الخاصية.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
validations:
min_length: 1
max_length: 2048
url: true
عمليات التحقق للأنواع string
min_length: الحد الأدنى لطول الخاصية. يجب أن تكون قيمة الكلمة المفتاحية عددًا صحيحًا.max_length: الحد الأقصى لطول الخاصية. يجب أن تكون قيمة الكلمة المفتاحية عددًا صحيحًا.url: تحقق من أن الخاصية عبارة عن رابط صالح (URL). يمكن أن تكون قيمة الكلمة المفتاحيةtrue/false.
عمليات التحقق للأنواع integer وfloat
min: الحد الأدنى لقيمة الخاصية. يجب أن تكون قيمة الكلمة المفتاحية عددًا صحيحًا.max: الحد الأقصى لقيمة الخاصية. يجب أن تكون قيمة الكلمة المفتاحية عددًا صحيحًا.
عمليات التحقق للأنواع tags، groups وcategories
min: الحد الأدنى لعدد السجلات للخاصية. يجب أن تكون قيمة الكلمة المفتاحية عددًا صحيحًا.max: الحد الأقصى لعدد السجلات للخاصية. يجب أن تكون قيمة الكلمة المفتاحية عددًا صحيحًا.
حل عضوية المجموعة
يمكن لإعدادات الكائنات حل خصائص type: groups إلى قيمة منطقية (boolean) للمستخدم الحالي. هذا مفيد عندما يحتاج كود القالب فقط إلى معرفة ما إذا كان المستخدم الحالي عضوًا في إحدى المجموعات المحددة، لأن currentUser.groups تتضمن فقط المجموعات المرئية للمستخدم.
أضف resolve_group_membership: true إلى الخاصية groups:
menu_sections:
type: objects
default:
- name: section 1
groups:
- 1
- 3
schema:
name: menu section
properties:
name:
type: string
groups:
type: groups
resolve_group_membership: true
لا تزال واجهة المستخدم الإدارية وقيمة الإعداد المخزنة تستخدم مصفوفة groups الأصلية. في كائن إعدادات settings في بيئة تشغيل الواجهة الأمامية، يزيل Discourse معرفات المجموعات من كل كائن ويضيف قيمة منطقية بنفس اسم الخاصية مع البادئة user_in_:
for (const section of settings.menu_sections) {
if (section.user_in_groups) {
// المستخدم في واحدة على الأقل من المجموعات المحددة لهذا القسم.
}
}
هذا الخيار صالح فقط لخصائص مخطط الكائنات ذات type: groups. كما يعمل مع مخططات الكائنات المتداخلة والمجموعات التلقائية مثل logged_in_users وanonymous_users.
هيكل الكائنات المتداخلة
يمكن أيضًا أن يكون للكائن خاصية تحتوي على مصفوفة من الكائنات. لإنشاء هيكل كائنات متداخل، يمكن أيضًا إضافة التعليق type: objects إلى الخاصية مع تعريف schema المرتبط.
sections:
type: objects
default:
- name: section 1
links:
- name: link 1
url: /some/url
- name: link 2
url: /some/other/url
schema:
name: section
properties:
name:
type: string
required: true
links:
type: objects
schema:
name: link
properties:
name:
type: string
url:
type: string
وصف الإعداد والترجمة
لإضافة وصف للإعداد في اللغة en، قم بإنشاء ملف locales/en.yml بالتنسيق التالي نظرًا لإعداد القالب التالي من نوع objects.
sections:
type: objects
default:
- name: section 1
links:
- name: link 1
url: /some/url
- name: link 2
url: /some/other/url
schema:
name: section
properties:
name:
type: string
required: true
links:
type: objects
schema:
name: link
properties:
name:
type: string
url:
type: string
en:
theme_metadata:
settings:
sections:
description: هذا هو وصف لإعداد القالب sections
schema:
properties:
name:
label: الاسم
description: وصف للخاصية
links:
name:
label: الاسم
description: وصف للخاصية
url:
label: الرابط (URL)
description: وصف للخاصية
نص كائن قابل للترجمة
اعلن عن خاصية نصية مطلوبة باسم translation_key وحدد الخصائص النصية بـ
translatable: true لعرضها في نصوص الموقع. يقرأ النواة القيم الافتراضية من إعدادات الكائنات المحفوظة
ويربطها ضمن أصول ترجمة القالب العادية. لا تتطلب مكونات القالب أي كود خادومي.
links:
type: objects
default:
- translation_key: guidelines
label: إرشادات المجتمع
schema:
name: link
identifier: label
properties:
translation_key:
type: string
required: true
label:
type: string
translatable: true
هذا يكشف عن js.theme_translations.<theme_id>.links.guidelines.label مع النص الافتراضي
“إرشادات المجتمع” ولغة النص الافتراضي en. تستمر الواجهة الأمامية
في استخدام i18n(themePrefix(`links.${link.translation_key}.label`), { defaultValue: link.label })
لكل رابط في الإعداد.
يعرض المحرر مفاتيح نسبية لتمريرها إلى themePrefix وروابط إلى
نصوص الموقع مفلترة إلى المكون. احفظ التغييرات قبل إدارة الترجمات.
يقصر النواة المفاتيح على معرف القالب المثبت واسم إعداد الكائن. لغة النص الافتراضي هي en؛ اختر
translations: { default_locale: fr } في مخطط الجذر لتغييرها.
لا حاجة لحظر translations خلاف ذلك. تعلن المخططات المتداخلة عن خاصية
نصية مطلوبة translation_key خاصة بها وتحدد خصائصها القابلة للترجمة؛
يتم تضمين مفاتيح الكائنات الأصلية وأسماء خصائص المجموعة في كل مفتاح متداخل. على سبيل المثال، قسم مع
مفتاح getting_started يحتوي على رابط مع مفتاح guidelines ينتج
theme_translations.<theme_id>.resource_sections.getting_started.links.guidelines.label
للإعداد resource_sections.
يجب أن تعلن المخططات ذات الحقول القابلة للترجمة، بما في ذلك مخططات الكائنات الأصلية، عن
translation_key مع type: string وrequired: true. يتحقق صيغة المخطط
من هذا حتى عندما تكون قائمة الكائنات الافتراضية فارغة. خيار
schema.identifier: label المنفصل يختار تسمية عرض المحرر؛ إنه لا
يحدد معرّف الترجمة.
استخدم معرفات يدوية التعيين ثابتة تبدأ بحرف صغير وتحتوي فقط على أحرف
صغيرة، أرقام، وشرطات سفلية. يجب أن تكون المعرفات
بطول 80 حرفًا كحد أقصى وفريدة داخل كل مجموعة. تبدأ أيضًا
أسماء الإعدادات القابلة للترجمة، وأسماء الحقول، وأسماء المجموعات المتداخلة
بحرف صغير وتحتوي فقط على أحرف
صغيرة، أرقام، وشرطات سفلية. إعادة الترتيب تحافظ على الترجمات. إعادة تسمية معرف
تُنشئ مفاتيح ترجمة جديدة؛ تكرار كائن يتطلب مفتاحًا مختلفًا.
تثبيتات المكونات المنفصلة لها مساحات أسماء مستقلة.
عند إضافة حقول قابلة للترجمة إلى مكون موجود، قدم ترحيل إعدادات
يضيف قيم translation_key صالحة للكائنات المخصصة.
تتحقق تحديثات المكون من مفاتيح ترجمة الكائن النهائية وتعيد بناء ترجماتها بعد
اكتمال ترحيل الإعدادات. المفاتيح النهائية غير الصالحة تعيد التحديث للخلف.
عمليات حفظ محرر الكائنات العادية تتحقق فورًا. إذا كانت معرفات الكائن المحفوظة غير صالحة،
تتجاهل مسارات القراءة قيم الكائن الافتراضية بحيث تبقى ترجمات ملف اللغة والأصول متاحة؛
حفظ إعدادات الكائنات وتطبيق الترحيلات لا يزال يتحقق بصرامة.
تشارك فقط الحقول النصية المحددة بـ translatable: true. الحقول غير المحددة
والحقول ذات translatable: false مستثناة. الحقول الاختيارية الفارغة تحتفظ بمفاتيحها
وترجماتها الموجودة. مسح النص الافتراضي لا يحذف الترجمات.
تشمل المجموعات المتداخلة اسم خاصيتها في المفتاح، لذا يمكن لمجموعات منفصلة
إعادة استخدام نفس معرفات الكائن.
تتضمن القيم الافتراضية قيم القالب الافتراضية والإعدادات المستوردة. تغيير النص الافتراضي
يعلم الترجمات بأنها قديمة. تبقى القيم الافتراضية في إعداد الكائن؛ تستخدم
الترجمات نموذج ThemeTranslationOverride الموجود، تمامًا مثل حقول ملف اللغة.
لا يوجد سجل نص منفصل.
إزالة كائن، إعلان حقل قابل للترجمة، أو مفتاح ملف اللغة لا يحذف
تجاوزات الترجمة المحفوظة. التجاوزات دون مصدر حالي لها
حالة deprecated وتحتفظ بها خلال حفظ الإعدادات، الترحيلات،
وتحديثات المكون. استعادة نفس مفتاح الترجمة تعيد استخدام التخصيص المحفوظ، بما في ذلك
بعد إرجاع المكون للوراء. هذا يحافظ على سلوك ترجمة ملف اللغة الموجود
للمكونات التي لا تختار ترجمات الكائنات. لا تُدرج المفاتيح المحذوفة
في نصوص الموقع حتى تعود إعلانات المصدر.
إذا جعلت تغييرات المخطط مفتاحًا محفوظًا يتعارض مع البنية المتداخلة لمفتاح حالي،
فالإعلان الحالي يحدد شكل وقت التشغيل. كلا التجاوزين المحفوظين يبقين
متاحين للاستعادة إذا تم إرجاع المخطط للوراء.
الإرجاع الصريح لترجمة لا يزال يزيل ذلك التجاوز ويستعيد
النص الافتراضي المشحون للغة المحددة. حذف المكون يزيل جميع
تجاوزات ترجمته.
يعرض نصوص الموقع النص الافتراضي ولغته جنبًا إلى جنب مع الترجمة القابلة للتحرير.
كلا حقول محرر الكائنات والسلاسل المشحونة في ملفات اللغة تستخدم
js.theme_translations.<theme_id>.<key> في نصوص الموقع. الترجمات المحفوظة قبل
تتبع الافتراضي كانت متاحة لها خط أساس غير معروف وتستثنى من مرشح
القديم. الإقرار بالافتراضي الحالي يؤسس خط أساس دون
تغيير الترجمة. يتم فحص عناصر نيابة الاستبدال في حقل الكائن مقابل
نص المصدر المعلن، وليس تجاوزات المصدر المخصصة. يمكن أشكال الجمع استخدام عناصر نيابة
المعلن من قبل شكل other الشقيق. تحتفظ تجاوزات ملف اللغة بسلوك
عنصر نيابة غير المقيد الحالي لأن المكون يمكنه تقديم وسائط وقت التشغيل
التي نصها المشحون لا يستخدمها. لا يعلم نصوص الموقع هذه الوسائط كغير صالحة.
تستخدم تتبعات الافتراضي حقل الكائن المحفوظ أو النص الإنجليزي المشحون، مع الرجوع
إلى النص المشحون للغة المحددة عندما لا يوجد مفتاح إنجليزي.
تجاوزات لغة المصدر
لا تستبدل هذا الخط الأساسي. تُعرض لغة الافتراضي بشكل صريح؛ إرجاع
تجاوز ملف اللغة لا يزال يستعيد النص المشحون للغة المحددة.
اسم الإعداد يحجز مساحة أسماء داخل القالب. لا يمكن لملف لغة
تحديد أيضًا المفتاح الجذر لذلك الإعداد: حفظ إعداد الكائن أو تحديث القالب
يرفض التعارض. يتم تسليم النص عبر أصول ترجمة القالب المخزنة المؤقتة الحالية
فقط للقالب النشط ومكوناته، بما في ذلك المعاينات.
هذا الوثيقة تحت سيطرة الإصدار - اقترح تغييرات على github.



