نقوم بتعريف نوع جديد type: objects ضمن الأنواع المدعومة لإعدادات السمة، والذي يمكن استخدامه لاستبدال نوع json_schema الحالي الذي نعتزم إيقاف دعمه قريباً.
تعريف إعداد سمة من نوع objects
لإنشاء إعداد سمة من نوع objects، قم أولاً بتعريف مفتاح رئيسي (top level key) بنفس الطريقة التي تُعرّف بها أي إعداد سمة، وسيُستخدم هذا المفتاح كاسم للإعداد.
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) فقط لهذه الخاصية. حالياً، الأنواع التالية مدعومة:
string: قيمة الخاصية مخزنة كنص (string).integer: قيمة الخاصية مخزنة كعدد صحيح (integer).float: قيمة الخاصية مخزنة كعدد عشري (float).boolean: قيمة الخاصية هيtrueأوfalse.upload: قيمة الخاصية هي رابط المرفق (attachment URL).enum: يجب أن تكون قيمة الخاصية أحد القيم المحددة في كلمة المفتاحchoices.links: type: objects default: [] schema: name: link properties: name: type: enum choices: - name 1 - name 2 - name 3categories: قيمة الخاصية هي مصفوفة من معرّفات الفئات (category ids) الصالحة.groups: قيمة الخاصية هي مصفوفة من معرّفات المجموعات (group ids) الصالحة.tags: قيمة الخاصية هي مصفوفة من أسماء الوسوم (tag names) الصالحة.icon: قيمة الخاصية هي اسم أيقونة واحدة من مجموعة أيقونات Discourse. تُضاف الأيقونات المحددة تلقائياً إلى ورقة الصور الرمزية (sprite sheet)، بحيث يمكن عرضها دون تسجيلها بشكل منفصل.
مع تعريف المخطط، يمكن الآن تعيين القيمة الافتراضية للإعداد من خلال تعريف مصفوفة في 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
التحقق المخصص (Custom Validations)
لأنواع الخصائص معينة، يوجد دعم مدمج للتحقق المخصص الذي يمكن إعلانه عن طريق إضافة التعليق validations للخاصية.
links:
type: objects
default: []
schema:
name: link
properties:
name:
type: string
required: true
validations:
min: 1
max: 2048
url: true
التحقق لأنواع string
min_length: الحد الأدنى لطول الخاصية. يجب أن تكون قيمة كلمة المفتاح عدداً صحيحاً (integer).max_length: الحد الأقصى لطول الخاصية. يجب أن تكون قيمة كلمة المفتاح عدداً صحيحاً (integer).url: يتحقق من أن الخاصية هي رابط URL صالح. يمكن أن تكون قيمة كلمة المفتاحtrue/false.
التحقق لأنواع integer و float
min: الحد الأدنى لقيمة الخاصية. يجب أن تكون قيمة كلمة المفتاح عدداً صحيحاً (integer).max: الحد الأقصى لقيمة الخاصية. يجب أن تكون قيمة كلمة المفتاح عدداً صحيحاً (integer).
التحقق لأنواع tags و groups و categories
min: الحد الأدنى لعدد السجلات للخاصية. يجب أن تكون قيمة كلمة المفتاح عدداً صحيحاً (integer).max: الحد الأقصى لعدد السجلات للخاصية. يجب أن تكون قيمة كلمة المفتاح عدداً صحيحاً (integer).
حل عضوية المجموعة (Resolving group membership)
يمكن لإعدادات الكائنات حل خصائص 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
لا يزال واجهة الإدارة (admin UI) والقيمة المخزنة للإعداد تستخدم مصفوفة groups الأصلية. في كائن settings وقت التشغيل في الواجهة الأمامية (frontend runtime)، تقوم Discourse بإزالة معرّفات المجموعات من كل كائن وتضيف قيمة منطقية (boolean) بنفس اسم الخاصية مع بادئة user_in_:
for (const section of settings.menu_sections) {
if (section.user_in_groups) {
// User is in at least one selected group for this section.
}
}
هذه الخيار صالح فقط لخصائص مخطط الكائنات التي يكون نوعها type: groups. كما يعمل أيضاً مع مخططات الكائنات المتداخلة (nested object schemas) ومع المجموعات التلقائية مثل logged_in_users و anonymous_users.
بنية الكائنات المتداخلة (Nested objects structure)
يمكن أن يحتوي الكائن أيضاً على خاصية تحتوي على مصفوفة من الكائنات. لإنشاء بنية كائنات متداخلة، يمكن تعليم خاصية أيضاً بنوع 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
وصف الإعداد والتوطين (Localization)
لإضافة وصف للإعداد في لغة 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: This is a description for the sections theme setting
schema:
properties:
name:
label: Name
description: The description for the property
links:
name:
label: Name
description: The description for the property
url:
label: URL
description: The description for the property
هذا المستند يخضع للتحكم بالإصدار - اقترح تعديلات على github.
