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

Menus

اجلب قوائم تنقل متعددة المستويات للموقع مبنية من الصفحات المُهيّأة في OneEntry.

مزيد من المعلومات حول واجهة مستخدم الوحدة https://doc.oneentry.cloud/docs/category/menu (يفتح في علامة تبويب جديدة)

تُعيد وحدة Menus بنى التنقل مثل قوائم الترويسة والتذييل والشريط الجانبي والجوال.

تنشئ القوائم في لوحة إدارة OneEntry (Menus ← Create Menu ← Add Pages ← Save) أو عبر Admin API، وتجلب هذه الوحدة شجرة القائمة بالكامل، فيمكنك عرض التنقل دون تضمين الروابط بشكل ثابت. يقرأ SDK القوائم فقط.

بدء سريع​

قم بتهيئة الوحدة من defineOneEntry:


const {  } = defineOneEntry(
  , {
    
  }
);

اجلب قائمة بواسطة علامتها وتنقّل بين صفحاتها:

// Fetch the "main_menu" structure in English.
const menu = await Menus.getMenusByMarker("main_menu", "en_US");
if ('statusCode' in menu) throw new Error(menu.message);

console.log(menu.identifier, menu.localizeInfos.title);

// Top-level items; nested items live in each item's children[].
menu.pages.forEach((item) => {
  console.log(item.pageUrl, item.localizeInfos.title, item.children);
});

القوائم​

القائمة (IMenusEntity) هي بنية تنقل تربط الصفحات معًا:

  • identifier: علامة القائمة (مثل "main_menu")
  • localizeInfos: عنوان القائمة المترجم
  • pages: عناصر القائمة: الصفحات والعناصر المخصّصة

تحتوي القائمة على صفحات مُهيّأة في OneEntry وعناصر مخصّصة، ويميّز itemType بينها (راجع أدناه). لإضافة رابط خارجي، أنشئ صفحة من النوع external_page في وحدة Pages وأضفها إلى القائمة. لاستخدام قوائم مختلفة لأقسام مختلفة، أنشئ عدة قوائم بعلامات مختلفة (مثل header_menu وfooter_menu وsidebar_menu) واجلب كلًّا منها باستخدام getMenusByMarker().

عناصر القائمة​

كل عنصر في pages هو كائن IMenusPages:

{
  id: 123,                       // Page ID
  pageUrl: "home",               // Page URL (marker)
  localizeInfos: { title: "Home" },
  attributeValues: {},           // Custom attribute values
  parentId: null,                // null for top-level items
  parentType: null,              // "page" | "custom" | null - kind of the parent
  itemType: "page",              // "page" | "custom" - kind of this item
  position: 1,                   // Display order
  children: []                   // Nested menu items
}

للعناصر حقل position. رتّب حسبه للحفاظ على ترتيب العرض المُهيّأ في لوحة الإدارة.

التداخل​

يمكن أن تكون القوائم متداخلة. يُعبَّر عن التداخل عبر مصفوفة children[] لكل عنصر مع parentId الخاص به (العناصر من المستوى الأعلى لها parentId: null). لا يوجد حقل للعمق؛ تحصل على العمق بالتنقل عبر children[]. لبناء قائمة متعددة المستويات (منسدلة)، رتّب الصفحات بشكل متداخل في لوحة الإدارة واعرض children[] بشكل تعاودي.

Header Menu
├─ Home (parentId: null)
├─ About (parentId: null)
│  ├─ Team (parentId: 2)
│  └─ History (parentId: 2)
├─ Products (parentId: null)
│  └─ Electronics (parentId: 4)
│     ├─ Phones (parentId: 5)
│     └─ Laptops (parentId: 5)
└─ Contact (parentId: null)

لتمييز العنصر النشط، قارن عنوان URL للصفحة الحالية مع pageUrl لكل عنصر. ولبناء مسار التنقل (breadcrumbs)، تتبّع parentId صعودًا من الصفحة الحالية (الرئيسية > الفئة > الفئة الفرعية > الصفحة الحالية).

نوعان من عناصر القائمة: itemType وparentType​

تحتوي القائمة على نوعين من العناصر، صفحات القائمة والعناصر المخصّصة، وتأتي معرّفاتها من تسلسلات مختلفة، لذا فهي تتداخل: parentId: 5 وحده لا يخبرك ما إذا كان الأصل هو الصفحة ذات المعرّف 5 أم العنصر المخصّص ذا المعرّف 5.

يحسم ذلك حقلان:

  • itemType ('page' | 'custom'): ما هو هذا العنصر نفسه.
  • parentType ('page' | 'custom' | null): ما هو أصله. القيمة null مع parentId: null تعني أن العنصر من المستوى الأعلى.

للعنصر المخصّص الشكل نفسه لعنصر الصفحة: يحمل pageUrl القيمة التي عيّنتها له (مثل رابط خارجي)، وattributeValues فارغ، وlocalizeInfos يكرّر العنوان في menuTitle مع htmlContent وplainContent فارغين. تحقّق من itemType قبل أن تعامل pageUrl كعلامة صفحة.

يحمل أبناء العنصر قيمة itemType الخاصة به بوصفها parentType لهم، لذا طابِق على الزوج عندما تعيد بناء الشجرة بنفسك:

const childrenOf = (items, parent) =>
  items.filter(
    (item) => item.parentId === parent.id && item.parentType === parent.itemType,
  );

اللغات​

تُترجم القوائم وفق langCode الذي تمرّره إلى getMenusByMarker()، مع الرجوع إلى اللغة المعيّنة في defineOneEntry(). اجلب القوائم بلغة المستخدم. أشِر إلى القوائم بالعلامة بدلًا من المعرّف (العلامات ثابتة عبر البيئات)، وخزّنها مؤقتًا (نادرًا ما تتغير)، واعرض بديلًا عندما لا يُعثر على علامة.

الطرق​

الطريقةالوصفحالة الاستخدام
getMenusByMarker()الحصول على قائمة بواسطة العلامةجلب بنية قائمة محددة

ذات صلة​