يمكنك تضمين مكوّنات "محرك البحث المبرمَج" (مربّعات البحث وصفحات نتائج البحث) في صفحات الويب الخاصة بك وتطبيقات الويب الأخرى باستخدام ترميز HTML. تتكوّن عناصر "محرك البحث المبرمَج" هذه من مكونات يتم عرضها استنادًا إلى الإعدادات التي يخزّنها خادم "البحث المبرمَج"، بالإضافة إلى أي تخصيصات يتم إجراؤها.
يتم تحميل كل محتوى JavaScript بشكل غير متزامن، ما يسمح لصفحة الويب بمواصلة التحميل أثناء جلب المتصفّح رمز JavaScript لمحرّك البحث المبرمَج.
مقدمة
يقدّم هذا المستند نموذجًا أساسيًا لإضافة عناصر "محرك البحث المبرمَج" إلى صفحة الويب الخاصة بك، بالإضافة إلى توضيح لمكونات العنصر القابلة للضبط وواجهة برمجة تطبيقات JavaScript المرنة.
النطاق
يوضّح هذا المستند طريقة استخدام الدوال والسمات الخاصة بواجهة برمجة التطبيقات للتحكّم في محرك البحث المبرمَج.
توافق المتصفّح
يمكن العثور على قائمة بالمتصفّحات المتوافقة مع "محرك البحث المبرمَج" هنا.
الجمهور
هذه المستندات مخصّصة للمطوّرين الذين يريدون إضافة وظيفة "بحث Google المبرمَج" إلى صفحاتهم.
عناصر البحث المبرمَج
يمكنك استخدام ترميز HTML لإضافة "عنصر البحث المبرمَج" إلى صفحتك. ويتألف كل عنصر من مكون واحد على الأقل: مربّع بحث أو مجموعة من نتائج البحث أو كليهما. يقبل مربّع البحث إدخالات المستخدم بأي من الطرق التالية:
- طلب بحث تمت كتابته في حقل إدخال النص
- سلسلة طلب بحث مضمّنة في عنوان URL
- التنفيذ الآلي
بالإضافة إلى ذلك، تقبل مجموعة نتائج البحث الإدخالات بالطرق التالية:
- سلسلة طلب بحث مضمّنة في عنوان URL
- التنفيذ الآلي
تتوفّر الأنواع التالية من "عناصر البحث المبرمَجة":
نوع العنصر | المكونات | الوصف |
---|---|---|
القيمة العادية | <div class="gcse-search"> |
مربّع بحث ونتائج بحث يتم عرضهما في <div> نفسه |
عمودان | <div class="gcse-searchbox"> و<div class="gcse-searchresults"> |
تنسيق من عمودَين يعرض نتائج بحث على أحد الجانبَين ومربّع بحث على الجانب الآخر إذا كنت تريد إدراج عدة عناصر في وضع العمودين
في صفحة الويب، يمكنك استخدام السمة gname لإقران
مربّع بحث بمجموعة من نتائج البحث. |
مربّع البحث فقط | <div class="gcse-searchbox-only"> |
مربع بحث مستقل. |
نتائج البحث فقط | <div class="gcse-searchresults-only"> |
مجموعة مستقلة من نتائج البحث. |
يمكنك إضافة أي عدد من عناصر البحث الصالحة إلى صفحة الويب. بالنسبة إلى الوضع المكوَّن من عمودين، يجب أن تتوفّر جميع المكوّنات المطلوبة (مربّع بحث وكتلة نتائج البحث).
في ما يلي مثال على عنصر بحث بسيط:
<!-- Put the following javascript before the closing </head> tag and replace 123456 with your own Programmable Search Engine ID. --> <script async src="https://cse.google.com/cse.js?cx=123456"></script> <!-- Place this tag where you want both of the search box and the search results to render --> <div class="gcse-search"></div>
إنشاء خيارات تنسيق مختلفة باستخدام "عناصر البحث المبرمَجة"
تتوفّر خيارات التنسيق التالية في صفحة "الشكل والأداء" للوحة تحكّم "محرك البحث المبرمَج". في ما يلي بعض الإرشادات العامة حول إنشاء خيارات التنسيق باستخدام "عناصر البحث المبرمَجة". لمشاهدة عرض توضيحي لأيٍ من هذه الخيارات، انقر على الرابط.
Option | المكونات |
---|---|
عرض كامل | <div class="gcse-search"> |
مكثّفة | <div class="gcse-search"> |
عمودان | <div class="gcse-searchbox"> ، <div class="gcse-searchresults"> |
صفحتين | <div class="gcse-searchbox-only"> في الصفحة الأولى و<div class="gcse-searchresults-only"> (أو مكوّنات أخرى) في الصفحة الثانية |
النتائج فقط | <div class="gcse-searchresults-only"> |
تستضيفه Google | <div class="gcse-searchbox-only"> |
مزيد من المعلومات حول خيارات التنسيق
تخصيص عناصر البحث المبرمَجة
لتخصيص الألوان أو الخط أو نمط الروابط، انتقل إلى صفحة "الشكل والأداء" في محرك البحث المبرمج.
يمكنك استخدام السمات الاختيارية لاستبدال الإعدادات التي تم إنشاؤها في
لوحة تحكّم "محرك البحث المبرمَج". ويتيح لك ذلك إنشاء تجربة بحث خاصة بصفحة معيّنة.
على سبيل المثال، تُنشئ التعليمة البرمجية التالية مربع بحث يفتح صفحة نتائج (http://www.example.com?search=lady+gaga) في نافذة جديدة. يتمّ استخدام قيمة السمة queryParameterName
مع سلسلة طلب بحث المستخدم لإنشاء عنوان URL للنتائج.
يُرجى العِلم أنّ السمة queryParameterName
تبدأ بـ data-
.
هذه البادئة مطلوبة لجميع السمات.
<div class="gcse-searchbox-only" data-resultsUrl="http://www.example.com" data-newWindow="true" data-queryParameterName="search">
إذا كنت قد استخدمت لوحة تحكّم "محرك البحث المبرمَج" لتفعيل ميزات مثل الإكمال التلقائي أو التحسينات، يمكنك استخدام السمات لتخصيص هذه الميزات. ستلغي أي تخصيصات تحددها باستخدام هذه السمات الإعدادات التي تم إجراؤها في لوحة التحكم. ينشئ المثال التالي عنصر بحث من عمودين مع الميزات التالية:
- تم تفعيل إدارة السجلّ
- تم ضبط الحد الأقصى لعدد عمليات الإكمال التلقائي المعروضة على 5.
- يتم عرض التحسينات كروابط.
<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5"> <div class="gcse-searchresults" data-refinementStyle="link">
السمات المسموح بها
السمة | النوع | الوصف | المكوِّن |
---|---|---|---|
الإعدادات العامة | |||
gname |
سلسلة | (اختياري) اسم لكائن Search Element. يُستخدم الاسم لاسترداد مكوِّن مرتبط حسب الاسم أو لإقران مكوِّن searchbox مع مكوِّن searchresults . وفي حال عدم توفيره، سيُنشئ "محرك البحث المبرمَج" تلقائيًا gname استنادًا إلى ترتيب المكوّنات على صفحة الويب. على سبيل المثال، يحتوي الحقل searchbox-only الأول بدون اسم على gname "searchbox-only0" والثاني gname "seachbox-only1"، وما إلى ذلك.
يُرجى العلم أنّ دالة gname التي يتم إنشاؤها تلقائيًا للمكوِّن
بالتنسيق المكوَّن من عمودين ستكون two-column . يستخدم المثال التالي اسم gname storesearch لربط مكوِّن searchbox بمكوِّن searchresults : <div class="gcse-searchbox" data-gname="storesearch"></div> <div class="gcse-searchresults" data-gname="storesearch"></div>. عند استرداد عنصر، إذا كان هناك أكثر من مكوّن واحد يستخدم السمة |
أي طول |
autoSearchOnLoad |
منطقي | تحدّد ما إذا كان سيتم تنفيذ بحث حسب طلب البحث المضمّن في عنوان URL
للصفحة التي يتم تحميلها. يُرجى العِلم أنّه يجب توفير سلسلة طلب بحث في عنوان URL لتنفيذ البحث التلقائي. اللغة التلقائية: true . |
أي طول |
enableHistory |
منطقي | إذا كان true ، سيتم تفعيل إدارة السجلّ لزرَي "الرجوع" و"إعادة التوجيه" في المتصفّح. مشاهدة عرض توضيحي. |
searchbox مربّع البحث فقط |
queryParameterName |
سلسلة | اسم معلَمة طلب البحث، على سبيل المثال، q (تلقائية)
أو query . سيتم تضمينها في عنوان URL (على سبيل المثال،
http://www.example.com?q=lady+gaga). يُرجى العِلم أنّ تحديد
اسم معلَمة طلب البحث وحده لا يؤدي إلى تشغيل البحث التلقائي عند التحميل. يجب أن تتوفر سلسلة طلب البحث في عنوان URL لتنفيذ البحث التلقائي. |
أي طول |
resultsUrl |
عنوان URL | تمثّل هذه السمة عنوان URL لصفحة النتائج. (الصفحة الافتراضية هي الصفحة التي تستضيفها Google.) | مربّع البحث فقط |
newWindow |
منطقي | تحدِّد هذه السياسة ما إذا كانت صفحة النتائج ستفتح في نافذة جديدة.
اللغة التلقائية: false . |
مربّع البحث فقط |
ivt |
منطقي |
تسمح لك هذه المَعلمة بتقديم قيمة منطقية تُعلِم Google بأنّك تريد السماح بالإعلانات التي تستخدم ملفات تعريف ارتباط غير صالحة خاصة بالزيارات فقط ومساحة تخزين محلية في الزيارات التي تمت الموافقة عليها وتلك التي لم يوافق عليها.
عناوين URL التلقائية: مثال على الاستخدام: |
نتائج البحث نتائج البحث فقط |
mobileLayout |
سلسلة |
تحدِّد هذه السياسة ما إذا كان يجب استخدام أنماط تنسيق الأجهزة الجوّالة للأجهزة الجوّالة.
لا يستخدم
عناوين URL التلقائية: مثال على الاستخدام: |
أي طول |
الإكمال التلقائي | |||
enableAutoComplete |
منطقي | لا يتوفّر هذا الخيار إلا إذا تم تفعيل ميزة "الإكمال التلقائي" في لوحة تحكُّم "محرك البحث المبرمَج".
تفعِّل true ميزة الإكمال التلقائي. |
أي طول |
autoCompleteMaxCompletions |
عدد صحيح | الحد الأقصى لعدد عمليات الإكمال التلقائي المطلوب عرضها. | searchbox مربّع البحث فقط |
autoCompleteMaxPromotions |
عدد صحيح | الحد الأقصى لعدد العروض الترويجية التي يتم عرضها في الإكمال التلقائي. | searchbox مربّع البحث فقط |
autoCompleteValidLanguages |
سلسلة | قائمة مفصولة بفواصل للغات التي يجب تفعيل ميزة الإكمال التلقائي لها. اللغات المتاحة: | searchbox مربّع البحث فقط |
التحسينات | |||
defaultToRefinement |
سلسلة | لا تتوفّر إلّا إذا تم إنشاء التحسينات في لوحة التحكّم في "محرك البحث المبرمَج". تحدد تصنيف التصفية التلقائي الذي سيتم عرضه.ملاحظة: هذه السمة غير متاحة للتنسيق المستضاف على Google. | أي طول |
refinementStyle |
سلسلة | القيمتان المقبولتان هما tab (التلقائية) وlink .
لا يتوفّر link إلا في حال إيقاف ميزة "البحث بالصور" أو إيقاف
بحث الصور بدون تفعيل بحث الويب. |
نتائج البحث نتائج البحث فقط |
بحث الصور | |||
enableImageSearch |
منطقي | لا يتوفّر هذا الخيار إلا إذا تم تفعيل
البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".
إذا كانت |
نتائج البحث نتائج البحث فقط |
defaultToImageSearch |
منطقي | لا يتوفّر هذا الخيار إلا إذا تم تفعيل
البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".
إذا تم اختيار |
أي طول |
imageSearchLayout |
سلسلة | لا يتوفّر هذا الخيار إلا إذا تم تفعيل
البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".
لتحديد تنسيق صفحة نتائج بحث الصور. والقيم المقبولة هي |
نتائج البحث نتائج البحث فقط |
imageSearchResultSetSize |
عدد صحيح، سلسلة | لا يتوفّر هذا الخيار إلا إذا تم تفعيل
البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".
تحدّد هذه العلامة الحد الأقصى لحجم نتائج البحث التي يتم ضبطها للبحث عن الصور.
على سبيل المثال، |
أي طول |
image_as_filetype |
سلسلة | لا يتوفّر هذا الخيار إلا إذا تم تفعيل
البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".
لقصر النتائج على ملفات بامتداد محدَّد. الإضافات المتوافقة هي | أي طول |
image_as_oq |
سلسلة | لا يتوفّر هذا الخيار إلا إذا تم تفعيل
البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".
تصفية نتائج البحث باستخدام المنطقية OR. مثال على الاستخدام إذا كنت تريد نتائج بحث تتضمّن "term1" أو "term2": | أي طول |
image_as_rights |
سلسلة | لا يتوفّر هذا الخيار إلا إذا تم تفعيل
البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".
الفلاتر المستندة إلى الترخيص والقيم المسموح بإدراجها هي اطّلِع على التركيبات النموذجية. | أي طول |
image_as_sitesearch |
سلسلة | لا يتوفّر هذا الخيار إلا إذا تم تفعيل
البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".
لحصر النتائج على صفحات من موقع إلكتروني معيّن مثال على الاستخدام: | أي طول |
image_colortype |
سلسلة | لا يتوفّر هذا الخيار إلا إذا تم تفعيل
البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".
يحصر البحث على الصور بالأبيض والأسود (أحادية) أو تدرّج الرمادي أو الصور الملونة. والقيمتان المسموح بإدراجهما هما | أي طول |
image_cr |
سلسلة | لا يتوفّر هذا الخيار إلا إذا تم تفعيل
البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".
لقصر نتائج البحث على المستندات التي تم إنشاؤها في بلد معيّن. | أي طول |
image_dominantcolor |
سلسلة | لا يتوفّر هذا الخيار إلا إذا تم تفعيل
البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".
لحصر البحث على الصور ذات اللون السائد.
والقيم المسموح بإدراجها هي | أي طول |
image_filter |
سلسلة | لا يتوفّر هذا الخيار إلا إذا تم تفعيل
البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".
الفلترة التلقائية لنتائج البحث القيم المسموح بها: 0/1 مثال على الاستخدام: | أي طول |
image_gl |
سلسلة | لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج". يمكنك تعزيز نتائج البحث التي يتطابق بلد مصدرها مع قيمة المَعلمة. | أي طول |
image_size |
سلسلة | لا يتوفّر هذا الخيار إلا إذا تم تفعيل
البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".
عرض صور بحجم محدد، حيث يمكن أن يكون الحجم واحدًا مما يلي: | أي طول |
image_sort_by |
سلسلة | لا يتوفّر هذا الخيار إلا إذا تم تفعيل
البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".
يمكنك ترتيب النتائج باستخدام التاريخ أو محتوى منظم آخر. للترتيب حسب مدى الصلة بالموضوع، استخدِم سلسلة فارغة (image_sort_by=""). مثال على الاستخدام: | أي طول |
image_type |
سلسلة | لا يتوفّر هذا الخيار إلا إذا تم تفعيل
البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".
لحصر البحث على صور من نوع معيّن.
القيم المسموح بها هي | أي طول |
بحث الويب | |||
disableWebSearch |
منطقي | سيتم إيقاف بحث الويب إذا كان true . يُستخدم عادةً فقط إذا تم تفعيل
البحث بالصور في لوحة تحكّم "محرك البحث المبرمَج". |
نتائج البحث نتائج البحث فقط |
webSearchQueryAddition |
سلسلة | تمت إضافة العبارات الإضافية إلى طلب البحث باستخدام OR المنطقية.
مثال على الاستخدام: |
أي طول |
webSearchResultSetSize |
عدد صحيح، سلسلة | الحد الأقصى لحجم النتائج التي تم تعيينها. ينطبق ذلك على كل من بحث الصور وبحث الويب. يعتمد الإعداد التلقائي على التنسيق وما إذا كان "محرك البحث المبرمَج" قد تم ضبطه للبحث في الويب بأكمله أو في مواقع إلكترونية محدّدة فقط. وتشمل القيم المقبولة ما يلي:
|
أي طول |
webSearchSafesearch |
سلسلة |
تحدِّد هذه السياسة ما إذا كانت ميزة SafeSearch مفعّلة لنتائج البحث على الويب. القيم المقبولة هي off وactive .
|
أي طول |
as_filetype |
سلسلة | لقصر النتائج على ملفات بامتداد محدَّد. يمكن العثور على قائمة بأنواع الملفات التي يمكن لمحرّك بحث Google فهرستها في مركز المساعدة في Search Console. | أي طول |
as_oq |
سلسلة | تصفية نتائج البحث باستخدام المنطقية OR.
مثال على الاستخدام إذا كنت تريد نتائج بحث تتضمّن "term1" أو "term2": |
أي طول |
as_rights |
سلسلة | الفلاتر المستندة إلى الترخيص
والقيم المسموح بإدراجها هي ويمكنك الانتقال إلى https://wiki.creativecommons.org/wiki/CC_Search_integration للحصول على مجموعات نموذجية. | أي طول |
as_sitesearch |
سلسلة | لحصر النتائج على صفحات من موقع إلكتروني معيّن
مثال على الاستخدام: |
أي طول |
cr |
سلسلة | لقصر نتائج البحث على المستندات التي تم إنشاؤها في بلد معيّن.
مثال على الاستخدام: |
أي طول |
filter |
سلسلة | الفلترة التلقائية لنتائج البحث
القيم المسموح بها: 0/1 مثال على الاستخدام: |
أي طول |
gl |
سلسلة | يمكنك تعزيز نتائج البحث التي يتطابق بلد مصدرها مع قيمة المَعلمة.
لن يعمل هذا الإجراء إلا مع الإعداد قيمة اللغة. مثال على الاستخدام: |
أي طول |
lr |
سلسلة | لحصر نتائج البحث بالمستندات المكتوبة بلغة معيّنة.
مثال على الاستخدام: |
أي طول |
sort_by |
سلسلة | يمكنك ترتيب النتائج باستخدام التاريخ أو محتوى منظم آخر. يجب أن تكون قيمة السمة أحد الخيارات المتوفرة في إعدادات ترتيب النتائج في البحث المبرمج.
للترتيب حسب مدى الصلة بالموضوع، استخدم سلسلة فارغة (sort_by=""). مثال على الاستخدام: |
أي طول |
نتائج البحث | |||
enableOrderBy |
منطقي | لتفعيل ترتيب النتائج حسب مدى الصلة بالموضوع أو التاريخ أو التصنيف. | أي طول |
linkTarget |
سلسلة | لضبط هدف الرابط. اللغة التلقائية: _blank . |
نتائج البحث نتائج البحث فقط |
noResultsString |
سلسلة | تحدِّد هذه العلامة النص التلقائي الذي سيتم عرضه عندما لا تتطابق أي نتائج مع طلب البحث. يمكن استخدام سلسلة النتيجة التلقائية لعرض سلسلة مترجَمة بجميع اللغات المتاحة، في حين لا يتم استخدام السلسلة المخصّصة. | نتائج البحث نتائج البحث فقط |
resultSetSize |
عدد صحيح، سلسلة | الحد الأقصى لحجم النتائج التي تم تعيينها. على سبيل المثال، large
وsmall وfiltered_cse و10 . ويعتمد
الإعداد التلقائي على التنسيق وما إذا كان قد تم ضبط المحرّك للبحث في
الويب بأكمله أو في مواقع إلكترونية محدّدة فقط. |
أي طول |
safeSearch |
سلسلة | تحدِّد هذه السياسة ما إذا كانت
ميزة "البحث الآمن" مفعّلة لكل من بحث الويب والبحث بالصور. القيمتان المقبولتان هما off
وactive . |
أي طول |
عمليات معاودة الاتصال
تتيح عمليات معاودة الاتصال التحكم التفصيلي في إعداد عنصر البحث وعمليات البحث.
ويتم تسجيلها في JavaScript Element Search من خلال كائن __gcse
العام. يوضّح القسم تسجيل طلبات معاودة الاتصال تسجيل جميع
عمليات معاودة الاتصال المتوافقة.
معاودة الاتصال بالإعداد
يتم استدعاء استدعاء الإعداد قبل أن تعرض لغة JavaScript لعنصر البحث عناصر البحث في نموذج العناصر في المستند (DOM). وإذا تم ضبط parsetags
على explicit
في
__gcse
، يترك رمز JavaScript في عنصر البحث عناصر البحث لعرض عناصر البحث في
استدعاء الإعداد (كما هو موضّح في مقالة تسجيل طلبات معاودة الاتصال).
ويمكن استخدام هذه السمة لاختيار العناصر المطلوب عرضها أو لتأجيل عرض عناصر العرض إلى أن
تكون هناك حاجة إليها. ويمكنه أيضًا إلغاء سمات العناصر، على سبيل المثال، يمكنه تحويل مربّع بحث تم ضبطه من خلال "لوحة التحكّم" أو سمات HTML إلى مربّع بحث عن الصور بشكل تلقائي، أو تحديد أنّ طلبات البحث المرسَلة من خلال نموذج "محرك البحث المبرمَج" يتم تنفيذها في عنصر نتائج البحث فقط.
اطّلِع على عرض توضيحي.
ويتم تحديد دور معاودة الاتصال بالإعداد من خلال قيمة السمة parsetags
في __gcse
.
- وإذا كانت قيمتها
onload
، يعرض عنصر JavaScript لعنصر البحث جميع عناصر البحث على الصفحة تلقائيًا. لا يزال تم استدعاء استدعاء الإعداد، ولكنه ليس مسؤولاً عن عرض عناصر البحث. - وإذا كانت قيمتها
explicit
، لن تعرض JavaScript عنصر البحث عناصر البحث. قد يعرض رد الاتصال هذه العناصر بشكل انتقائي باستخدام الدالةrender()
، أو قد يتم عرض جميع عناصر البحث باستخدام الدالةgo()
.
يوضّح الرمز التالي كيفية عرض مربّع بحث مع نتائج البحث في div
باستخدام تحليل explicit
واستدعاء الإعداد:
البحث في طلبات معاودة الاتصال
تتيح لغة JavaScript لعنصر البحث ستة عمليات استدعاء تعمل ضمن مسار التحكّم في البحث. تأتي استدعاءات "بحث Google" في شكل أزواج، استدعاء بحث الويب، ومعاودة اتصال بحث صور مطابقة:
- بدء البحث
- لبحث الصور
- لبحث الويب
- النتائج جاهزة
- لبحث الصور
- لبحث الويب
- النتائج المعروضة
- لبحث الصور
- لبحث الويب
كما هو الحال مع استدعاء الإعداد، يتم ضبط عمليات استدعاء البحث باستخدام الإدخالات في الكائن __gcse
. ويحدث ذلك عند بدء تشغيل JavaScript لعنصر البحث. يتم تجاهل التعديلات على __gcse
بعد بدء التشغيل.
يتم تمرير كل من استدعاءات الاستدعاء هذه gName
لعنصر البحث كوسيطة.
تكون السمة gname
مفيدة عندما تحتوي الصفحة على أكثر من عملية بحث واحدة. أضِف قيمًا gname
إلى عنصر بحث باستخدام السمة data-gname
:
<div class="gcse-searchbox" data-gname="storesearch"></div>
وإذا لم يتعرّف رمز HTML على ملف gname، ستنشئ JavaScript عنصر البحث قيمة ستظل متسقة إلى أن يتم تعديل رمز HTML.
معاودة الاتصال لبدء بحث الويب أو الصور
يتم استدعاء استدعاءات بدء البحث مباشرةً قبل أن يطلب عنصر JavaScript في Search Element نتائج البحث من خادمه. ومن الأمثلة على حالة الاستخدام استخدام الوقت المحلي من اليوم للتحكّم في التغييرات التي تطرأ على طلب البحث.
searchStartingCallback(gname, query)
gname
- السلسلة التعريفية لعنصر البحث
query
- القيمة التي أدخلها المستخدم (يمكن أن يتم تعديلها من خلال عنصر البحث JavaScript)
تعرض معاودة الاتصال القيمة التي يجب استخدامها كطلب بحث لهذا البحث. وفي حال عرض سلسلة فارغة، يتم تجاهل القيمة المعروضة ويستخدم الطلب طلب البحث غير المعدّل.
ويمكنك بدلاً من ذلك وضع دالة رد الاتصال في الكائن __gcse
أو إضافة رد الاتصال ديناميكيًا إلى العنصر باستخدام JavaScript:
window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
مثال على عملية بحث لبدء معاودة الاتصال
يضيف مثال البحث الذي يبدأ معاودة الاتصال في مثال على معاودة الاتصال بالبحث إما morning
أو afternoon
إلى طلب البحث بناءً على الوقت من اليوم.
تثبيت معاودة الاتصال هذه في window.__gcse:
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
image: {
starting: 'myImageSearchStartingCallbackName',
},
web: {
starting: myWebSearchStartingCallback,
},
};
<script
async src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>
معاودة الاتصال جاهزة لنتائج بحث الويب أو الصور
ويتم استدعاء عمليات الاسترداد هذه مباشرةً قبل أن تعرض JavaScript "عنصر البحث" العروض الترويجية والنتائج. ومن أمثلة حالات الاستخدام معاودة الاتصال التي تعرض العروض الترويجية وتنتج نمطًا لا يمكن تحديده باستخدام التخصيص العادي.
resultsReadyCallback(gname, query, promos, results, div)
gname
- السلسلة التعريفية لعنصر البحث
query
- طلب البحث الذي أدّى إلى ظهور هذه النتائج
promos
- مجموعة من عناصر العروض الترويجية التي تتوافق مع العروض الترويجية المطابقة لطلب بحث المستخدم. اطّلِع على تعريف عنصر العرض الترويجي.
results
- مصفوفة من عناصر النتائج. اطّلِع على تعريف كائن النتيجة.
div
- يتم وضع علامة div بتنسيق HTML في نموذج العناصر في المستند (DOM) حيث يشير عنصر البحث عادةً
إلى العروض الترويجية ونتائج البحث. في العادة، ستتعامل لغة JavaScript لعنصر البحث مع تعبئة div هذا، إلا أنّ استدعاء الاتصال هذا قد يختار إيقاف العرض التلقائي للنتائج واستخدام
div
لعرض النتائج نفسها.
إذا عرضت معاودة الاتصال هذه القيمة true
، سيتم تخطي JavaScript لعنصر البحث
إلى عمل تذييل الصفحة.
مثال على النتائج الجاهزة لمعاودة الاتصال
ويؤدي مثال معاودة الاتصال resultsReady
في مثال على معاودة الاتصال الجاهزة إلى إلغاء العرض التلقائي للعروض الترويجية والنتائج مع استبدال بسيط جدًا.
معاودة الاتصال المعروضة بنتائج بحث الويب أو الصور
يتم استدعاء عمليات الاسترداد هذه مباشرةً قبل أن تعرض JavaScript "عنصر البحث" تذييل الصفحة. وتشمل الأمثلة على حالات الاستخدام معاودة الاتصال التي تضيف محتوى نتائج لا يعرضها عنصر البحث، مثل مربّع الاختيار حفظ هذا أو المعلومات التي لا يتم عرضها تلقائيًا، أو معاودة الاتصال التي تضيف أزرار لمزيد من المعلومات.
إذا كانت النتائج التي يتم عرضها في معاودة الاتصال بحاجة إلى معلومات كانت في المعلّمتَين promos
وresults
في دالتَي معاودة الاتصال بالنتائج الجاهزة، يمكن تمرير هذه المعلومات بينهما، على النحو التالي:
callback(gname, query, promoElts, resultElts);
gname
- السلسلة التعريفية لعنصر البحث
query
- سلسلة البحث
promoElts
- مصفوفة من عناصر DOM التي تحتوي على عروض ترويجية.
resultElts
- مصفوفة من عناصر DOM التي تحتوي على نتائج.
لا تتوفّر قيمة معروضة.
مثال على نتائج معاودة الاتصال المعروضة
يضيف مثال معاودة الاتصال resultsRendered
في مثال على النتائج المعروضة لمعاودة الاتصال مربع اختيار احتفاظ وهمي لكل عرض ترويجي ونتيجة.
إذا كانت النتائج المعروضة لمعاودة الاتصال بحاجة
إلى معلومات تم تمريرها إلى معاودة الاتصال بالنتائج الجاهزة، يمكن تمرير هذه البيانات بين
عمليات معاودة الاتصال. يعرض المثال التالي إحدى الطرق المتعددة لتمرير قيمة تقييم من richSnippet
من استدعاء النتائج الجاهزة إلى النتائج المعروضة لمعاودة الاتصال.
المزيد من الأمثلة على معاودة الاتصال
يمكن العثور على أمثلة إضافية لمعاودة الاتصال في المستند المزيد من الأمثلة على معاودة الاتصال.
خصائص العروض الترويجية والنتائج
باستخدام تدوين JSDoc، هذه هي سمات كائنات promotion والنتيجة. نعرض هنا جميع الخصائص التي قد تكون موجودة. ويعتمد توفُّر العديد من السمات على تفاصيل العرض الترويجي أو نتيجة البحث.
تحتوي richSnippet
في results على النوع الحر لمصفوفة
من العناصر. يتم التحكّم في قيم الإدخالات في هذه المصفوفة من خلال
البيانات المنظَّمة
المتوفّرة في صفحة الويب لكل نتيجة بحث. على سبيل المثال، قد يتضمّن موقع إلكتروني للمراجعات بيانات منظَّمة تضيف إدخال المصفوفة هذا إلى richSnippet
:
'review': { 'ratingstars': '3.0', 'ratingcount': '1024', },
واجهة برمجة التطبيقات Programmable Search Element Control API (V2)
ينشر الكائن google.search.cse.element
الدوال الثابتة التالية:
الوظيفة | الوصف | ||||||
---|---|---|---|---|---|---|---|
.render(componentConfig, opt_componentConfig) |
يعرض عنصر بحث.
المعلّمات
|
||||||
.go(opt_container) |
عرض جميع علامات/فئات "عناصر البحث" في الحاوية المحدّدة
المعلّمات
|
||||||
.getElement(gname) |
يحصل على كائن العنصر بحلول gname . إذا لم يتم العثور عليه، يتم عرض قيمة فارغة.
يضم كائن
تنفذ التعليمة البرمجية التالية طلب البحث "news" في عنصر البحث "element1": var element = google.search.cse.element.getElement('element1'); element.execute('news'); |
||||||
.getAllElements() |
تعرض خريطة لجميع كائنات العناصر التي تم إنشاؤها بنجاح، ويتم مفتاحها بالاستناد إلى gname . |