Programmable Search Element Control API

يمكنك تضمين مكوّنات "محرك البحث المبرمَج" (مربّعات البحث وصفحات نتائج البحث) في صفحات الويب الخاصة بك وتطبيقات الويب الأخرى باستخدام ترميز 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>
.

عند استرداد عنصر، إذا كان هناك أكثر من مكوّن واحد يستخدم السمة gname نفسها، سيستخدم "محرك البحث المبرمَج" المكوِّن الأخير على الصفحة.

أي طول
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 بأنّك تريد السماح بالإعلانات التي تستخدم ملفات تعريف ارتباط غير صالحة خاصة بالزيارات فقط ومساحة تخزين محلية في الزيارات التي تمت الموافقة عليها وتلك التي لم يوافق عليها.

true في حال عدم توفّر هذه المَعلمة أو ضبطها على "صحيح"، سنضبط ملف تعريف ارتباط غير صالح للزيارات فقط وسنستخدم مساحة التخزين المحلية على الزيارات التي تمت الموافقة عليها فقط.

false عند ضبط هذه المَعلمة على "خطأ"، سنضبط ملف تعريف ارتباط غير صالح للزيارات فقط وسنستخدم مساحة التخزين المحلية لكل من الزيارات التي تمت الموافقة عليها وتلك التي لم تتم الموافقة عليها.

عناوين URL التلقائية: false

مثال على الاستخدام: <div class="gcse-search" data-ivt="true"></div>

نتائج البحث

نتائج البحث فقط

mobileLayout سلسلة

تحدِّد هذه السياسة ما إذا كان يجب استخدام أنماط تنسيق الأجهزة الجوّالة للأجهزة الجوّالة.

enabled يستخدم تنسيق الجهاز الجوّال للأجهزة الجوّالة فقط.

لا يستخدم disabled تنسيق الجهاز الجوّال لأي أجهزة.

forced: يستخدم هذا الوضع تنسيق الأجهزة الجوّالة لجميع الأجهزة.

عناوين URL التلقائية: enabled

مثال على الاستخدام: <div class="gcse-search" data-mobileLayout="disabled"></div>

أي طول
الإكمال التلقائي
enableAutoComplete منطقي لا يتوفّر هذا الخيار إلا إذا تم تفعيل ميزة "الإكمال التلقائي" في لوحة تحكُّم "محرك البحث المبرمَج". تفعِّل true ميزة الإكمال التلقائي. أي طول
autoCompleteMaxCompletions عدد صحيح الحد الأقصى لعدد عمليات الإكمال التلقائي المطلوب عرضها.

searchbox

مربّع البحث فقط

autoCompleteMaxPromotions عدد صحيح الحد الأقصى لعدد العروض الترويجية التي يتم عرضها في الإكمال التلقائي.

searchbox

مربّع البحث فقط

autoCompleteValidLanguages سلسلة قائمة مفصولة بفواصل للغات التي يجب تفعيل ميزة الإكمال التلقائي لها. اللغات المتاحة:

searchbox

مربّع البحث فقط

التحسينات
defaultToRefinement سلسلة لا تتوفّر إلّا إذا تم إنشاء التحسينات في لوحة التحكّم في "محرك البحث المبرمَج". تحدد تصنيف التصفية التلقائي الذي سيتم عرضه.ملاحظة: هذه السمة غير متاحة للتنسيق المستضاف على Google. أي طول
refinementStyle سلسلة القيمتان المقبولتان هما tab (التلقائية) وlink. لا يتوفّر link إلا في حال إيقاف ميزة "البحث بالصور" أو إيقاف بحث الصور بدون تفعيل بحث الويب.

نتائج البحث

نتائج البحث فقط

بحث الصور
enableImageSearch منطقي لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".

إذا كانت true، سيتم تفعيل بحث الصور. سيتم عرض نتائج الصور في علامة تبويب منفصلة.

نتائج البحث

نتائج البحث فقط

defaultToImageSearch منطقي لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".

إذا تم اختيار true، ستعرض صفحة نتائج البحث نتائج بحث الصور تلقائيًا. ستكون نتائج الويب متاحة في علامة تبويب منفصلة.

أي طول
imageSearchLayout سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".

لتحديد تنسيق صفحة نتائج بحث الصور. والقيم المقبولة هي classic أو column أو popup.

نتائج البحث

نتائج البحث فقط

imageSearchResultSetSize عدد صحيح، سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".

تحدّد هذه العلامة الحد الأقصى لحجم نتائج البحث التي يتم ضبطها للبحث عن الصور. على سبيل المثال، large وsmall وfiltered_cse و10.

أي طول
image_as_filetype سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".

لقصر النتائج على ملفات بامتداد محدَّد.

الإضافات المتوافقة هي jpg وgif وpng وbmp وsvg وwebp وico وraw.

أي طول

image_as_oq سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".

تصفية نتائج البحث باستخدام المنطقية OR.

مثال على الاستخدام إذا كنت تريد نتائج بحث تتضمّن "term1" أو "term2":<div class="gcse-search" data-image_as_oq="term1 term2"></div>

أي طول

image_as_rights سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".

الفلاتر المستندة إلى الترخيص

والقيم المسموح بإدراجها هي cc_publicdomain وcc_attribute وcc_sharealike وcc_noncommercial وcc_nonderived ومجموعات منها.

اطّلِع على التركيبات النموذجية.

أي طول

image_as_sitesearch سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".

لحصر النتائج على صفحات من موقع إلكتروني معيّن

مثال على الاستخدام: <div class="gcse-search" data-image_as_sitesearch="example.com"></div>

أي طول

image_colortype سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".

يحصر البحث على الصور بالأبيض والأسود (أحادية) أو تدرّج الرمادي أو الصور الملونة. والقيمتان المسموح بإدراجهما هما mono وgray وcolor.

أي طول

image_cr سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".

لقصر نتائج البحث على المستندات التي تم إنشاؤها في بلد معيّن.

القيم المسموح بها

أي طول

image_dominantcolor سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".

لحصر البحث على الصور ذات اللون السائد. والقيم المسموح بإدراجها هي red وorange وyellow وgreen وteal وblue وpurple وpink وwhite وgray وblack وbrown.

أي طول

image_filter سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".

الفلترة التلقائية لنتائج البحث

القيم المسموح بها: 0/1

مثال على الاستخدام: <div class="gcse-search" data-image_filter="0"></div>

أي طول

image_gl سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج". يمكنك تعزيز نتائج البحث التي يتطابق بلد مصدرها مع قيمة المَعلمة.

القيم المسموح بها

أي طول

image_size سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".

عرض صور بحجم محدد، حيث يمكن أن يكون الحجم واحدًا مما يلي: icon أو small أو medium أو large أو xlarge أو xxlarge أو huge.

أي طول

image_sort_by سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".

يمكنك ترتيب النتائج باستخدام التاريخ أو محتوى منظم آخر.

للترتيب حسب مدى الصلة بالموضوع، استخدِم سلسلة فارغة (image_sort_by="").

مثال على الاستخدام: <div class="gcse-search" data-image_sort_by="date"></div>

أي طول

image_type سلسلة لا يتوفّر هذا الخيار إلا إذا تم تفعيل البحث بالصور في لوحة تحكُّم "محرك البحث المبرمَج".

لحصر البحث على صور من نوع معيّن. القيم المسموح بها هي clipart (قصاصات فنية) وface (وجوه أشخاص) وlineart (رسومات خطية) وstock (صور جاهزة) وphoto (صور) وanimated (ملفات GIF متحركة).

أي طول

بحث الويب
disableWebSearch منطقي سيتم إيقاف بحث الويب إذا كان true. يُستخدم عادةً فقط إذا تم تفعيل البحث بالصور في لوحة تحكّم "محرك البحث المبرمَج".

نتائج البحث

نتائج البحث فقط

webSearchQueryAddition سلسلة تمت إضافة العبارات الإضافية إلى طلب البحث باستخدام OR المنطقية.

مثال على الاستخدام: <div class="gcse-search" data-webSearchQueryAddition="term1 term2"></div>

أي طول
webSearchResultSetSize عدد صحيح، سلسلة الحد الأقصى لحجم النتائج التي تم تعيينها. ينطبق ذلك على كل من بحث الصور وبحث الويب. يعتمد الإعداد التلقائي على التنسيق وما إذا كان "محرك البحث المبرمَج" قد تم ضبطه للبحث في الويب بأكمله أو في مواقع إلكترونية محدّدة فقط. وتشمل القيم المقبولة ما يلي:
  • عدد صحيح من 1 إلى 20
  • small: يطلب هذا الخيار مجموعة نتائج صغيرة، وتكون عادةً 4 نتائج في كل صفحة.
  • large: يطلب مجموعة كبيرة من النتائج، وتكون عادةً 8 نتائج في كل صفحة.
  • filtered_cse: يطلب هذا الخيار ما يصل إلى 10 نتائج في كل صفحة، وبحد أقصى 10 صفحات أو 100 نتيجة.
أي طول
webSearchSafesearch سلسلة تحدِّد هذه السياسة ما إذا كانت ميزة SafeSearch مفعّلة لنتائج البحث على الويب. القيم المقبولة هي off وactive. أي طول
as_filetype سلسلة لقصر النتائج على ملفات بامتداد محدَّد. يمكن العثور على قائمة بأنواع الملفات التي يمكن لمحرّك بحث Google فهرستها في مركز المساعدة في Search Console.

أي طول

as_oq سلسلة تصفية نتائج البحث باستخدام المنطقية OR.

مثال على الاستخدام إذا كنت تريد نتائج بحث تتضمّن "term1" أو "term2":<div class="gcse-search" data-as_oq="term1 term2"></div>

أي طول
as_rights سلسلة الفلاتر المستندة إلى الترخيص

والقيم المسموح بإدراجها هي cc_publicdomain وcc_attribute وcc_sharealike وcc_noncommercial وcc_nonderived ومجموعات منها.

ويمكنك الانتقال إلى https://wiki.creativecommons.org/wiki/CC_Search_integration للحصول على مجموعات نموذجية.

أي طول

as_sitesearch سلسلة لحصر النتائج على صفحات من موقع إلكتروني معيّن

مثال على الاستخدام: <div class="gcse-search" data-as_sitesearch="example.com"></div>

أي طول
cr سلسلة لقصر نتائج البحث على المستندات التي تم إنشاؤها في بلد معيّن.

القيم المسموح بها

مثال على الاستخدام: <div class="gcse-search" data-cr="countryFR"></div>

أي طول
filter سلسلة الفلترة التلقائية لنتائج البحث

القيم المسموح بها: 0/1

مثال على الاستخدام: <div class="gcse-search" data-filter="0"></div>

أي طول
gl سلسلة يمكنك تعزيز نتائج البحث التي يتطابق بلد مصدرها مع قيمة المَعلمة.

لن يعمل هذا الإجراء إلا مع الإعداد قيمة اللغة.

القيم المسموح بها

مثال على الاستخدام: <div class="gcse-search" data-gl="fr"></div>

أي طول
lr سلسلة لحصر نتائج البحث بالمستندات المكتوبة بلغة معيّنة.

القيم المسموح بها

مثال على الاستخدام: <div class="gcse-search" data-lr="lang_fr"></div>

أي طول
sort_by سلسلة يمكنك ترتيب النتائج باستخدام التاريخ أو محتوى منظم آخر. يجب أن تكون قيمة السمة أحد الخيارات المتوفرة في إعدادات ترتيب النتائج في البحث المبرمج.

للترتيب حسب مدى الصلة بالموضوع، استخدم سلسلة فارغة (sort_by="").

مثال على الاستخدام: <div class="gcse-search" data-sort_by="date"></div>

أي طول
نتائج البحث
enableOrderBy منطقي لتفعيل ترتيب النتائج حسب مدى الصلة بالموضوع أو التاريخ أو التصنيف. أي طول
linkTarget سلسلة لضبط هدف الرابط. اللغة التلقائية: _blank.

نتائج البحث

نتائج البحث فقط

noResultsString سلسلة تحدِّد هذه العلامة النص التلقائي الذي سيتم عرضه عندما لا تتطابق أي نتائج مع طلب البحث. يمكن استخدام سلسلة النتيجة التلقائية لعرض سلسلة مترجَمة بجميع اللغات المتاحة، في حين لا يتم استخدام السلسلة المخصّصة.

نتائج البحث

نتائج البحث فقط

resultSetSize عدد صحيح، سلسلة الحد الأقصى لحجم النتائج التي تم تعيينها. على سبيل المثال، large وsmall وfiltered_cse و10. ويعتمد الإعداد التلقائي على التنسيق وما إذا كان قد تم ضبط المحرّك للبحث في الويب بأكمله أو في مواقع إلكترونية محدّدة فقط. أي طول
safeSearch سلسلة تحدِّد هذه السياسة ما إذا كانت ميزة "البحث الآمن" مفعّلة لكل من بحث الويب والبحث بالصور. القيمتان المقبولتان هما off وactive. أي طول

عمليات معاودة الاتصال

مخطّط تسلسل معاودة الاتصال
مخطّط بياني لتسلسل عمليات الاسترداد من JavaScript لعنصر البحث

تتيح عمليات معاودة الاتصال التحكم التفصيلي في إعداد عنصر البحث وعمليات البحث. ويتم تسجيلها في JavaScript Element Search من خلال كائن __gcse العام. يوضّح القسم تسجيل طلبات معاودة الاتصال تسجيل جميع عمليات معاودة الاتصال المتوافقة.

تسجيل عمليات معاودة الاتصال

  window.__gcse = {
    parsetags: 'explicit', // Defaults to 'onload'
    initializationCallback: myInitializationCallback,
    searchCallbacks: {
      image: {
        starting: myImageSearchStartingCallback,
        ready: myImageResultsReadyCallback,
        rendered: myImageResultsRenderedCallback,
      },
      web: {
        starting: myWebSearchStartingCallback,
        ready: myWebResultsReadyCallback,
        rendered: myWebResultsRenderedCallback,
      },
    },
  };
  

معاودة الاتصال بالإعداد

يتم استدعاء استدعاء الإعداد قبل أن تعرض لغة JavaScript لعنصر البحث عناصر البحث في نموذج العناصر في المستند (DOM). وإذا تم ضبط parsetags على explicit في __gcse، يترك رمز JavaScript في عنصر البحث عناصر البحث لعرض عناصر البحث في استدعاء الإعداد (كما هو موضّح في مقالة تسجيل طلبات معاودة الاتصال). ويمكن استخدام هذه السمة لاختيار العناصر المطلوب عرضها أو لتأجيل عرض عناصر العرض إلى أن تكون هناك حاجة إليها. ويمكنه أيضًا إلغاء سمات العناصر، على سبيل المثال، يمكنه تحويل مربّع بحث تم ضبطه من خلال "لوحة التحكّم" أو سمات HTML إلى مربّع بحث عن الصور بشكل تلقائي، أو تحديد أنّ طلبات البحث المرسَلة من خلال نموذج "محرك البحث المبرمَج" يتم تنفيذها في عنصر نتائج البحث فقط. اطّلِع على عرض توضيحي.

ويتم تحديد دور معاودة الاتصال بالإعداد من خلال قيمة السمة parsetags في __gcse.

  • وإذا كانت قيمتها onload، يعرض عنصر JavaScript لعنصر البحث جميع عناصر البحث على الصفحة تلقائيًا. لا يزال تم استدعاء استدعاء الإعداد، ولكنه ليس مسؤولاً عن عرض عناصر البحث.
  • وإذا كانت قيمتها explicit، لن تعرض JavaScript عنصر البحث عناصر البحث. قد يعرض رد الاتصال هذه العناصر بشكل انتقائي باستخدام الدالة render()، أو قد يتم عرض جميع عناصر البحث باستخدام الدالة go().

يوضّح الرمز التالي كيفية عرض مربّع بحث مع نتائج البحث في div باستخدام تحليل explicit واستدعاء الإعداد:

مثال على معاودة الاتصال للإعداد

نحتاج إلى تضمين <div> مع قيمة id حيث نريد رمز "عنصر البحث":

    <div id="test"></div>
أضِف رمز JavaScript هذا بعد <div>. يُرجى العِلم أنّها تشير إلى test، أي id التي استخدمناها لتحديد <div>
const myInitCallback = function() {
  if (document.readyState == 'complete') {
    // Document is ready when Search Element is initialized.
    // Render an element with both search box and search results in div with id 'test'.
    google.search.cse.element.render(
        {
          div: "test",
          tag: 'search'
         });
  } else {
    // Document is not ready yet, when Search Element is initialized.
    google.setOnLoadCallback(function() {
       // Render an element with both search box and search results in div with id 'test'.
        google.search.cse.element.render(
            {
              div: "test",
              tag: 'search'
            });
    }, true);
  }
};

// Insert it before the Search Element code snippet so the global properties like parsetags and callback
// are available when cse.js runs.
window.__gcse = {
  parsetags: 'explicit',
  initializationCallback: myInitCallback
};
.

أدرِج رمز HTML هذا لبدء تحميل عنصر البحث. استبدِل القيمة cx في البند src بقيمة cx الخاصة بك.

<script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>

البحث في طلبات معاودة الاتصال

تتيح لغة 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 إلى طلب البحث بناءً على الوقت من اليوم.

مثال على معاودة الاتصال بالبحث
    const myWebSearchStartingCallback = (gname, query) => {
      const hour = new Date().getHours();
      return query + (hour < 12 ? ' morning' : ' afternoon');
    };
    window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;

تثبيت معاودة الاتصال هذه في 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 في مثال على معاودة الاتصال الجاهزة إلى إلغاء العرض التلقائي للعروض الترويجية والنتائج مع استبدال بسيط جدًا.

مثال على معاودة الاتصال بالنتائج الجاهزة
    const myResultsReadyCallback = function(name, q, promos, results, resultsDiv) {
      const makePromoElt = (promo) => {
        const anchor = document.createElement('a');
        anchor.href = promo['url'];
        anchor.target = '_blank';
        anchor.classList.add('gs-title');
        const span = document.createElement('span');
        span.innerHTML = 'Promo: ' + promo['title'];
        anchor.appendChild(span);
        return anchor;
      };
      const makeResultParts = (result) => {
        const anchor = document.createElement('a');
        anchor.href = result['url'];
        anchor.target = '_blank';
        anchor.classList.add('gs_title');
        anchor.appendChild(document.createTextNode(result['visibleUrl']));
        const span = document.createElement('span');
        span.innerHTML = ' ' + result['title'];
        return [anchor, span];
      };

      const table = document.createElement('table');
      if (promos) {
        for (const promo of promos) {
          const row = table.insertRow(-1);
          const cell = row.insertCell(-1);
          cell.appendChild(makePromoElt(promo));
        }
        resultsDiv.appendChild(table);
        resultsDiv.appendChild(document.createElement('br'));
      }
      if (results) {
        const table = document.createElement('table');
        for (const result of results) {
          const row = table.insertRow(-1);
          const cell = row.insertCell(-1);
          const [anchor, span] = makeResultParts(result);
          cell.appendChild(anchor);
          const cell2 = row.insertCell(-1);
          cell2.appendChild(span);
        }
        resultsDiv.appendChild(table);
      }
      return true;
    };

تثبيت معاودة الاتصال هذه في window.__gcse:

  window.__gcse || (window.__gcse = {});
    window.__gcse.searchCallbacks = {
      web: {
        ready: myResultsReadyCallback,
      },
    };
  <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

كما هي الحال بالنسبة إلى معاودة الاتصال عند بدء البحث، ما سبق ذكره هو إحدى الطرق العديدة لإدخال معاودة الاتصال في كائن __gcse.

معاودة الاتصال المعروضة بنتائج بحث الويب أو الصور

يتم استدعاء عمليات الاسترداد هذه مباشرةً قبل أن تعرض JavaScript "عنصر البحث" تذييل الصفحة. وتشمل الأمثلة على حالات الاستخدام معاودة الاتصال التي تضيف محتوى نتائج لا يعرضها عنصر البحث، مثل مربّع الاختيار حفظ هذا أو المعلومات التي لا يتم عرضها تلقائيًا، أو معاودة الاتصال التي تضيف أزرار لمزيد من المعلومات.

إذا كانت النتائج التي يتم عرضها في معاودة الاتصال بحاجة إلى معلومات كانت في المعلّمتَين promos وresults في دالتَي معاودة الاتصال بالنتائج الجاهزة، يمكن تمرير هذه المعلومات بينهما، على النحو التالي:

callback(gname, query, promoElts, resultElts);
gname
السلسلة التعريفية لعنصر البحث
query
سلسلة البحث
promoElts
مصفوفة من عناصر DOM التي تحتوي على عروض ترويجية.
resultElts
مصفوفة من عناصر DOM التي تحتوي على نتائج.

لا تتوفّر قيمة معروضة.

مثال على نتائج معاودة الاتصال المعروضة

يضيف مثال معاودة الاتصال resultsRendered في مثال على النتائج المعروضة لمعاودة الاتصال مربع اختيار احتفاظ وهمي لكل عرض ترويجي ونتيجة.

مثال على معاودة الاتصال بنتائج البحث
myWebResultsRenderedCallback = function(name, q, promos, results) {
    for (const div of promos.concat(results)) {
      const innerDiv = document.createElement('div');
      innerDiv.appendChild(document.createTextNode('Keep: '));
      const checkBox = document.createElement('input');
      checkBox.type = 'checkbox';
      checkBox.name = 'save';
      innerDiv.appendChild(checkBox);
      div.insertAdjacentElement('afterbegin', innerDiv);
    }
  };

تثبيت معاودة الاتصال هذه في window.__gcse:

window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    rendered: 'myWebResultsRenderedCallback',
  },
};
  <script async
    src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

إذا كانت النتائج المعروضة لمعاودة الاتصال بحاجة إلى معلومات تم تمريرها إلى معاودة الاتصال بالنتائج الجاهزة، يمكن تمرير هذه البيانات بين عمليات معاودة الاتصال. يعرض المثال التالي إحدى الطرق المتعددة لتمرير قيمة تقييم من richSnippet من استدعاء النتائج الجاهزة إلى النتائج المعروضة لمعاودة الاتصال.

مثال على معاودة الاتصال بالنتائج الجاهزة للتعاون مع معاودة الاتصال المعروضة بالنتائج
const makeTwoPartCallback = () => {
  let saveForRenderCallback;
  const readyCallback = (name, q, promos, results, resultsDiv) =>
  {
    saveForRenderCallback = [];
    for (const result of results) {
      const {
        richSnippet: {
          answer = []
        } = {},
      } = result;
      const firstAnswer = answer[0];
      if (firstAnswer) {
        const upVotes = firstAnswer['upvotecount'];
        if (upVotes) {
          saveForRenderCallback.push(
            {upvotes: parseInt(upVotes, 10)}
          );
          continue;
        }
      }
      saveForRenderCallback.push({});
    }
  };
  const renderedCallback = (name, q, promos, results) => {
    for (let i = 0; i < results.length; ++i) {
      const div = results[i];
      const votes = saveForRenderCallback[i]['upvotes'];
      if (votes) {
        const innerDiv = document.createElement('div');
        innerDiv.innerHTML = '<b>Upvotes: ' + votes + '</b>';
         div.insertAdjacentElement('afterbegin', innerDiv);
      }
    }
  };
  return {readyCallback, renderedCallback};
};
يمكنك تثبيت معاودة الاتصال هذه باستخدام رمز مثل هذا أثناء إعداد __gcse:
const {
  readyCallback: webResultsReadyCallback,
  renderedCallback: webResultsRenderedCallback,
} = makeTwoPartCallback();
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    ready: webResultsReadyCallback,
    rendered: webResultsRenderedCallback,
  },
};
  <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:kdroeu4mwju"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

المزيد من الأمثلة على معاودة الاتصال

يمكن العثور على أمثلة إضافية لمعاودة الاتصال في المستند المزيد من الأمثلة على معاودة الاتصال.

خصائص العروض الترويجية والنتائج

باستخدام تدوين JSDoc، هذه هي سمات كائنات promotion والنتيجة. نعرض هنا جميع الخصائص التي قد تكون موجودة. ويعتمد توفُّر العديد من السمات على تفاصيل العرض الترويجي أو نتيجة البحث.

خصائص العرض الترويجي
{
  content: string,
  image: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  url: string,
  visibleUrl: string,
}
خصائص عنصر النتائج
{
  content: string,
  contentNoFormatting: string,
  contextUrl: string, // For image search results only
  fileFormat: string,
  image: { // For image search reseults only
    height: number,
    url: string,
    width: number,
  },
  perResultLabels: !Array<{
    anchor: string,
    label: string,
    labelWithOp: string,
  }>,
  richSnippet: !Array<!Object>, // For web search results only
  thumbnailImage: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  titleNoFormatting: string,
  url: string,
  visibleUrl: string,
}

تحتوي richSnippet في results على النوع الحر لمصفوفة من العناصر. يتم التحكّم في قيم الإدخالات في هذه المصفوفة من خلال البيانات المنظَّمة المتوفّرة في صفحة الويب لكل نتيجة بحث. على سبيل المثال، قد يتضمّن موقع إلكتروني للمراجعات بيانات منظَّمة تضيف إدخال المصفوفة هذا إلى richSnippet:

'review': {
  'ratingstars': '3.0',
  'ratingcount': '1024',
},

واجهة برمجة التطبيقات Programmable Search Element Control API (V2)

ينشر الكائن google.search.cse.element الدوال الثابتة التالية:

الوظيفة الوصف
.render(componentConfig, opt_componentConfig) يعرض عنصر بحث.

المعلّمات

الاسم الوصف
componentConfig إعدادات أحد مكونات "عنصر البحث المبرمَج" يحدِّد ما يلي:
  • div (سلسلة|العنصر): id للسمة <div> أو العنصر div الذي سيتم عرض عنصر البحث المبرمَج فيه.
  • tag (سلسلة): نوع المكوّنات المطلوب عرضها (عند تقديم opt_componentConfig، يجب أن تكون قيمة السمة tag هي searchbox.) القيم المسموح بها هي:
    • search: مربع بحث ونتائج بحث يتم عرضهما معًا
    • searchbox: أحد مكوّنات مربّع البحث ضمن "عنصر البحث المبرمَج".
    • searchbox-only: مربّع بحث مستقل سيتم إقرانه مع مجموعة من نتائج البحث المحدّدة من قِبل opt_componentConfig بتنسيق من عمودين.
    • searchresults-only: مجموعة مستقلة من نتائج البحث تبدأ عمليات البحث من خلال مَعلمة طلب بحث مضمّنة في عنوان URL أو من خلال التنفيذ الآلي.
  • gname (سلسلة): (اختياري) اسم فريد لهذا المكوِّن في حال عدم توفيره، سيُنشئ "محرك البحث المبرمَج" gname تلقائيًا.
  • attributes (كائن): سمات اختيارية في شكل زوج المفتاح/القيمة. السمات المتوافقة:
opt_componentConfig اختياريّ. وسيطة ضبط المكون الثاني. يتم استخدامه في وضع TWO_COLUMN لتوفير المكوِّن searchresults. يحدِّد ما يلي:
  • div (سلسلة): تمثّل هذه السمة id للسمة <div> أو العنصر div الذي سيتم عرض العنصر فيه.
  • tag (سلسلة): نوع المكوّنات المطلوب عرضها عند توفير opt_componentConfig، يجب أن تكون قيمة السمة tag searchresults. بالإضافة إلى ذلك، يجب أن تكون قيمة السمة tag في componentConfig هي searchbox.
  • gname (سلسلة): (اختياري) اسم فريد لهذا المكوِّن في حال عدم توفيره، سينشئ "محرك البحث المبرمَج" تلقائيًا علامة gname لهذا المكوِّن. وفي حال توفيره، يجب أن يتطابق مع السمة gname في componentConfig.
  • attributes (كائن): سمات اختيارية في شكل زوج المفتاح/القيمة. السمات المسموح بها:
.go(opt_container) عرض جميع علامات/فئات "عناصر البحث" في الحاوية المحدّدة

المعلّمات

الاسم الوصف
opt_container الحاوية التي تحتوي على مكوّنات "عنصر البحث" المطلوب عرضها حدِّد إما رقم تعريف الحاوية (سلسلة) أو العنصر نفسه. في حال حذف هذه العناصر، سيتم عرض جميع مكوِّنات "عنصر البحث المبرمَج" داخل علامة body للصفحة.
.getElement(gname) يحصل على كائن العنصر بحلول gname. إذا لم يتم العثور عليه، يتم عرض قيمة فارغة.

يضم كائن element المعروض السمات التالية:

  • gname: اسم كائن العنصر في حال عدم توفيره، سيُنشئ "محرك البحث المبرمَج" تلقائيًا gname للكائن. مزيد من المعلومات
  • type: نوع العنصر
  • uiOptions: السمات النهائية المستخدَمة لعرض العنصر
  • execute - function(string): ينفذ طلب بحث آلي.
  • prefillQuery - الدالة(string): تملأ مربّع البحث مسبقًا بسلسلة طلب بحث بدون تنفيذ طلب البحث.
  • getInputQuery - function(): للحصول على القيمة الحالية المعروضة في مربّع الإدخال.
  • clearAllResults - function(): محو عنصر التحكّم من خلال إخفاء كل العناصر باستثناء مربّع البحث، إن وجد.

تنفذ التعليمة البرمجية التالية طلب البحث "news" في عنصر البحث "element1":

var element = google.search.cse.element.getElement('element1');
            element.execute('news');
.getAllElements() تعرض خريطة لجميع كائنات العناصر التي تم إنشاؤها بنجاح، ويتم مفتاحها بالاستناد إلى gname.