نُقدّم نوعًا جديدًا 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: قيمة الخاصية تُخزن كنص (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: قيمة الخاصية هي مصفوفة من معرفات الفئات الصالحة.groups: قيمة الخاصية هي مصفوفة من معرفات المجموعات الصالحة.tags: قيمة الخاصية هي مصفوفة من أسماء الوسوم الصالحة.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
تُعد قيم 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
لا يزال واجهة الإدارة (Admin UI) وقيمة الإعداد المخزنة تستخدم مصفوفة 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: 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.
