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

المقدمة

استعلام واحد عبر مشروعك بالكامل - المنتجات، الصفحات، الكتل، النماذج، الطلبات والمزيد، مجمعة حسب نوع الكيان.

🎯 ماذا يفعل هذا الموديل؟​

يحيط موديل البحث نقطة النهاية العامة للبحث عبر الكيانات. تقوم بتمرير استعلام نصي وتسترجع كل سجل يتطابق فيه الاسم أو قيمة السمة، من 18 نوع كيان دفعة واحدة، مجمعة حسب النوع ومشروحة بـ كيف تطابق كل سجل.

استخدمه لتشغيل صندوق "ابحث عن كل شيء" عالمي - النوع الذي يظهر بعض المنتجات، وعدد قليل من الصفحات ونموذج مطابق في قائمة منسدلة واحدة - ثم قم بالتعمق في نوع واحد عندما يطلب المستخدم المزيد.

هذا هو بحث الكلمات الرئيسية: يتطابق مع النص الحرفي للعناوين، المعرفات، الروابط وقيم السمات. للبحث القائم على المعنى (استعلام مثل "جاكيت دافئ للشتاء" يتطابق مع منتج يسمى "باركا معزولة")، استخدم البحث الدلالي للوحدات الفردية - انظر البحث المتجه مقابل البحث العالمي أدناه.

🚀 البدء السريع​

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


const { Search } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

ابحث عن كل شيء، ثم استعرض المجموعات:

// Search every entity type for "winter".
const result = await Search.globalSearch('winter');

console.log(result.query); // "winter"

result.groups.forEach((group) => {
  console.log(group.type, group.items.length, group.hasMore);

  group.items.forEach((item) => {
    console.log(item.id, item.title, item.matchKind, item.fragment);
  });
});

✨ المفاهيم الأساسية​

المجموعات​

الاستجابة ليست قائمة مسطحة. إنها { query, groups }، حيث تحتوي كل مجموعة على سجلات من نوع كيان واحد:

{
  query: "winter",
  groups: [
    { type: "products", items: [ /* … */ ], hasMore: false },
    { type: "pages",    items: [ /* … */ ], hasMore: false }
  ]
}

hasMore يخبرك ما إذا كانت هناك سجلات أخرى من هذا النوع موجودة بخلاف الصفحة المعادة - الإشارة لتقديم رابط "عرض جميع المنتجات" الذي يعيد تشغيل الاستعلام في وضع التعمق.

سياق المطابقة​

كل عنصر يحمل سياق كيفية تطابقه، بحيث يمكنك عرض صف نتيجة ذو معنى بدلاً من عنوان عاري:

الحقلماذا يخبرك
matchKindنوع ترتيب المطابقة: exact، title، attributeName أو attributeValue
matchedFieldالحقل المحدد الذي تطابق: id، title، identifier، url، attributeName، attributeValue، importId، nodeName
matchedAttributeالسمة التي حدثت فيها المطابقة (عندما جاءت المطابقة من سمة)
fragmentسياق نصي عادي حول المطابقة، بدون تنسيق - قم بتمييزه بنفسك
langCodeلغة القيمة المطابقة، بحيث يمكنك وضع علامة على النتائج عبر اللغات
parentالسجل المالك للكيانات التي ليس لديها صفحة خاصة بها (شريحة → كتلتها، طلب → تخزينه)

أنواع الكيانات​

types يضيق نطاق البحث. قم بتمرير أي من هذه، وسيرسل SDK إياها مفصولة بفواصل:

products، pages، blocks، slides، templates، discounts، user_groups، users، admins، menus، forms، attributes_sets، attributes، orders، workflows، events، subscriptions، collections.

تجاهل types للبحث في جميعها.

وضع التعمق​

offset و limit تحول نقطة النهاية إلى وضع التعمق - التصفح عبر نوع كيان واحد بدلاً من عرض جميعها.

⚠️ يتم قبولها فقط مع نوع واحد قابل للوصول بالضبط في types. أي تركيبة أخرى تعيد 400 - وضع التعمق (limit/offset) يتطلب نوعًا واحدًا قابلًا للوصول بالضبط في types.

لا يقوم SDK بتعيينها بشكل افتراضي: تجاهل كلاهما وستعود كل مجموعة كاملة.

// Overview: every type, every group complete.
const overview = await Search.globalSearch('winter');

// Drilldown: page 1 of the products only.
const products = await Search.globalSearch('winter', ['products'], 'visible', 0, 20);

الرؤية​

visibility تصفّي السجلات التي تم البحث عنها: 'all' (افتراضي)، 'visible' أو 'hidden'.

📋 ما تحتاج لمعرفته​

  • id هو رقم لمعظم الأنواع، سلسلة للعمليات والسمات - number | string، لذا لا تفترض معرفات رقمية عند بناء المفاتيح أو الروابط.
  • title اختياري: السجلات التي ليس لديها اسم خاص بها (الطلبات، المستخدمون بدون تسجيل دخول) تعود بدونها. ارجع إلى identifier أو subtitle.
  • subtitle يحمل السطر الثانوي الذي يحدث أن يكون للنوع - رابط صفحة، تخزين طلب، اسم عقدة.
  • attributeSetId موجود فقط لـ type: "attributes"، مشيرًا إلى المجموعة التي تنتمي إليها السمة.
  • فقط السجلات التي يمكن للمتصل الحالي رؤيتها تُعاد؛ البحث يحترم نفس قواعد الوصول كما هو الحال في بقية واجهة برمجة التطبيقات.

📊 جدول المراجع السريعة​

الطريقةالوصف
globalSearch()البحث عن الأسماء وقيم السمات عبر جميع أنواع الكيانات

البحث المتجه مقابل البحث العالمي​

كلاهما يجد السجلات من استعلام نصي، لكنهما يجيبون على أسئلة مختلفة:

globalSearchget…ByVectorSearch
يتطابق علىالنص الحرفي للعناوين، المعرفات، الروابط وقيم السماتالمعنى - تشابه دلالي (متجه)
النطاق18 نوع كيان في مكالمة واحدةوحدة واحدة لكل مكالمة
يعيد{ query, groups[] } - مجمعة حسب النوع{ items, total } - حاوية مسطحة
الاستخدام النموذجيصندوق بحث عالمي / لوحة أوامر"ابحث لي عن شيء مثل هذا" عبر كيان واحد

تعيش النظائر الدلالية في الوحدات نفسها: products، pages، users، orders، discounts، admins و form data.

❓ الأسئلة الشائعة (FAQ)​

لماذا يتم الرد على offset / limit بـ 400؟​

لأنها تعمل فقط في وضع التعمق. قم بتمرير نوع كيان واحد قابل للوصول في types بجانبها، أو تخلص منها تمامًا.

كيف يمكنني تمييز المطابقة في واجهة المستخدم؟​

استخدم fragment - إنه السياق النصي العادي حول المطابقة، خالي عمدًا من التنسيق، بحيث يمكنك تمييز الاستعلام فيه بنفسك دون تطهير أي شيء.

عنصر ليس لديه title. هل هذه مشكلة؟​

لا. الطلبات والمستخدمون بدون تسجيل دخول ليس لديهم اسم خاص بهم، لذا فإن title ببساطة غائب. قم بعرض identifier، subtitle أو تسمية محددة للنوع بدلاً من ذلك.

هل يمكنني البحث عن السجلات المخفية؟​

قم بتمرير visibility: 'hidden' (أو 'all') - مع مراعاة قواعد الوصول التي تنطبق على المتصل.

🎓 أفضل الممارسات​

  • قم بتأخير الاستعلام في صندوق البحث أثناء الكتابة: كل ضغطة مفتاح هي طلب.
  • اعرض مكالمة النظرة العامة أولاً (بدون offset/limit)، ثم انتقل إلى وضع التعمق عندما يختار المستخدم نوعًا - هذا هو بالضبط ما تم تصميم hasMore من أجله.
  • ضيق types إلى ما يمكن لواجهة المستخدم الخاصة بك عرضه فعليًا؛ البحث في 18 نوعًا لعرض 2 هو عمل ضائع.
  • اعتبر id كـ number | string عند بناء الروابط ومفاتيح React.

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