انتقل إلى المحتوى الرئيسي

قيم السمات

السمات هي الطريقة التي تصف بها OneEntry المحتوى: صفحة، منتج، كتلة، مستخدم، طلب أو حقل نموذج يحمل خريطة من قيم السمات مفاتيحها بواسطة علامة. يقوم SDK بتطبيع كل سمة من كل استجابة إلى نفس الشكل، لذا فإن نفس الحقل يبدو كما هو بغض النظر عن الوحدة التي أعادته.

const page = await Pages.getPageByUrl('catalog');

page.attributeValues.title.value;   // "Catalog"        — string
page.attributeValues.amount.value;  // 5                — number
page.attributeValues.cover.value;   // { downloadLink } — the file object itself
page.attributeValues.notes.value;   // null             — no value set

الشكل المطبع​

قيمة السمة هي IAttributeValue: { type, value, position?, additionalFields? }. ما تحمله value يعتمد على type:

نوع السمةvalue
string, textstring
integer, float, realnumber — تم تحويله من الشكل النصي لـ API
image, file مع ملف واحدكائن الملف نفسه
image, file مع عدة ملفاتمصفوفة من كائنات الملفات
groupOfImagesدائمًا مصفوفة — إنها مجموعة بالتعريف
listمصفوفة
timeIntervalمصفوفة من المجموعات — انظر الفترات الزمنية
لا توجد قيمة محددةدائمًا null

السمات ذات الملف الواحد غير مغلقة​

عندما تحمل سمة image أو file بالضبط ملف واحد، فإن value هي كائن الملف نفسه. فقط القيم التي تحتوي على ملفين أو أكثر تبقى مصفوفة.

const block = await Blocks.getBlockByMarker('promo');

// before: block.attributeValues.img.value[0].downloadLink
// now:    block.attributeValues.img.value.downloadLink

ينطبق هذا في كل وحدة. سابقًا، كانت عملية فك التغليف تحدث فقط في المنتجات، القوائم، النماذج، حقول بيانات النماذج، مجموعات السمات، مجموعات التكامل و Pages.searchPage، وفقط على مفتاح attributeValues — في كل مكان آخر (الكتل، جميع طرق الصفحات الأخرى، Products.getProductsEmptyPage, Products.getProductBlockById, المسؤولين، الخصومات، القوالب، الطلبات، المستخدمين) وصلت نفس السمة كمصفوفة ذات عنصر واحد، لذا كان على المستهلكين التفرع بناءً على الشكل. لم يتم فك تغليف سمات النماذج، حقول بيانات النماذج و additionalFields المتداخلة على الإطلاق.

⚠️ الهجرة: الكود الذي يقرأ value[0] من المنتجات أو القوائم غير متأثر — تلك الوحدات كانت تعيد الكائن بالفعل. يجب على الكود الذي يقرأ value[0] من الكتل، الصفحات، المستخدمين أو الطلبات إسقاط الفهرس.

groupOfImages هي مجموعة بالتعريف وتبقى دائمًا مصفوفة. على جانب الطلب، يتم تصنيف IBodyTypeFile.value كـ IFileValue | IFileValue[] وفقًا لذلك.

الأرقام هي أرقام​

تتحول قيم integer و float و real إلى رقم. كانت real تُترك كـ نص، لذا كان نفس الحقل الرقمي يصل إلى المستهلك كـ 10 أو كـ "10" اعتمادًا على أي من الأنواع الثلاثة تم الإعلان عنه:

const page = await Pages.getPageByUrl('catalog');

// before: page.attributeValues.amount.value // "5"
// now:    page.attributeValues.amount.value // 5

يتم أيضًا تشغيل تطبيع الأرقام على سمات النماذج و حقول بيانات النماذج، التي تم تخطيها تمامًا — حقل rating من سمة نموذج integer هو number، وليس نصًا.

عند تقديم البيانات، أرسل نصًا: IBodyTypeStringNumberFloat.value هو string | number | null، وتعود الاستجابات مطبعة.

القيمة الفارغة دائمًا null​

تُرجع API خريطة محلية فارغة لقيمة غير محددة. كان SDK يستخدم لتمريرها لأنواع النصوص بينما أصبحت الأنواع الرقمية null — كانت نفس حالة "لا قيمة" لها ثلاث تمثيلات. الآن هي دائمًا null.

if (page.attributeValues.notes.value === null) {
  // nothing configured for this attribute
}

⚠️ الهجرة: integer/float غير المحددة لم تعد 0. Number(null) هو 0، لذا كان يتم الإبلاغ عن null صريح من API كصفر حقيقي — قيمة لا يمكن تمييزها عن 0 المكونة.

كل شيء مرتّب حسب الموضع​

تم دائمًا إرجاع attributeValues بترتيب position، والآن أيضًا سمات النموذج. تُرجع API حقول النموذج بدون ترتيب — قد يصل حقل مع position: 10 بعد position: 14 — لذا كان يتطلب عرض نموذج بترتيب CMS فرزًا على جانب المستهلك.

نموذج بدون سمات يُرجع attributes: []. ترسل API كائنًا فارغًا في هذه الحالة، ويقوم SDK بتطبيعه إلى مصفوفة فارغة، لذا فإن attributes دائمًا IFormAttribute[] و form.attributes.map(...) آمن في كل نموذج.

الحقول المتداخلة: additionalFields​

تصل قيم السمات المتداخلة تحت additionalFields. بشكل افتراضي، يقوم SDK بتحويل المصفوفة التي ترجعها API إلى كائن مفاتيحه marker؛ قم بتعيين rawData: true في الإعدادات للاحتفاظ بالمصفوفة الأصلية — انظر تنسيق الحقول الإضافية.

// default (rawData: false)
attribute.additionalFields['my_field'].value;

// rawData: true
attribute.additionalFields.find((f) => f.marker === 'my_field').value;

تمر additionalFields المتداخلة بنفس التطبيع مثل السمات على المستوى الأعلى — يتم فك تغليف الملفات الفردية وتتحول الأرقام هناك أيضًا.

تصنيف قيمة السمة​

IAttributeValue.value مصنفة كـ unknown، لأن شكلها يعتمد على type. قم بتضييقها قبل الاستخدام — بالنسبة لسمات timeInterval، يوفر SDK حارس نوع:

import { isTimeIntervalAttribute } from 'oneentry';
import type { IAttributeValues } from 'oneentry';

function readText(values: IAttributeValues, marker: string): string {
  const value = values[marker]?.value;
  return typeof value === 'string' ? value : '';
}

🔗 الوثائق ذات الصلة​