Programmable Search Element Control API

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

يتم تحميل كل ملفات JavaScript بشكل غير متزامن، الأمر الذي يتيح لصفحة الويب مواصلة التحميل أثناء استرجاع المتصفِّح لمحتوى JavaScript الخاص بـ "محرك البحث المبرمَج"

Introduction

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

المستوى

توضح هذه الوثيقة كيفية استخدام الدوال والخصائص الخاصة واجهة برمجة التطبيقات للتحكّم في محرك البحث المبرمَج

توافُق المتصفّح

يمكن العثور على قائمة المتصفِّحات المتوافقة مع "محرك البحث المبرمَج" هنا.

الجمهور

هذا المستند مخصّص للمطوّرين الذين يريدون إضافة Google Programmable. وظائف البحث على صفحاتهم.

عناصر البحث القابلة للبرمجة

يمكنك استخدام ترميز HTML لإضافة "عنصر بحث مبرمَج" إلى صفحتك. على كل من مكون واحد على الأقل: مربع البحث، أو كتلة البحث أو كليهما. يقبل مربّع البحث إدخال المستخدم في أي مما يلي الطرق:

  • طلب بحث مكتوب في حقل إدخال النص
  • سلسلة طلب بحث مضمّنة في عنوان URL
  • التنفيذ الآلي

بالإضافة إلى ذلك، يقبل حظر نتائج البحث الإدخال في الطرق التالية:

  • سلسلة طلب بحث مضمّنة في عنوان URL
  • التنفيذ الآلي

تتوفّر الأنواع التالية من "عناصر البحث المبرمَجة":

نوع العنصر المكونات الوصف
القيمة العادية <div class="gcse-search"> مربع البحث ونتائج البحث، يتم عرضه في سمة <div> نفسها.
عمودان <div class="gcse-searchbox"> و<div class="gcse-searchresults"> تخطيط من عمودين مع نتائج بحث على جانب واحد ومربع بحث من جهة أخرى. إذا كنت تخطط لإدراج عناصر متعددة في وضع العمودين في صفحتك على الويب، يمكنك استخدام السمة gname لإقران مربع بحث مع جزء من نتائج البحث.
مربّع البحث فقط <div class="gcse-searchbox-only"> مربّع بحث مستقلّ
searchresults-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 سلسلة (اختياري) اسم لكائن "عنصر البحث". يُستخدم الاسم لاسترداد مكوِّن مقترن بالاسم، أو لإقران searchbox مع مكون searchresults. وفي حال عدم توفّره، سينشئ "محرك البحث المبرمَج" تلقائيًا gname، استنادًا إلى ترتيب المكونات على صفحة الويب. على سبيل المثال، أول بدون اسم يتضمّن searchbox-only gname "مربع البحث-فقط0" والثاني يحتوي على 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، سيتم تفعيل إدارة السجلّ للمتصفّح "رجوع" و"إعادة التوجيه". مشاهدة عرض توضيحي

مربّع البحث

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

queryParameterName سلسلة اسم معلَمة طلب البحث، مثل q (الإعداد التلقائي) أو query. سيتم تضمين ذلك في عنوان URL (على سبيل المثال، http://www.example.com?q=lady+gaga). لاحظ أن تحديد إذا كان اسم مَعلمة طلب البحث وحده لا يؤدي إلى تفعيل البحث التلقائي عند التحميل. طلب بحث يجب أن تكون السلسلة موجودة في عنوان URL لتنفيذ البحث التلقائي. أي لون
resultsUrl عنوان URL عنوان URL لصفحة النتائج. (الصفحة التلقائية هي الصفحة التي تستضيفها Google.) مربّع البحث فقط
newWindow منطقي تحدِّد هذه السياسة ما إذا كان سيتم فتح صفحة النتائج في نافذة جديدة. الإعدادات التلقائية: false. مربّع البحث فقط
ivt منطقي

تتيح لك هذه المعلمة تقديم قيمة منطقية تخبر Google بأنك تريد السماح الإعلانات التي تستخدم ملفات تعريف ارتباط الزيارات غير الصالحة فقط التخزين المحلي على كل من الزيارات التي لم تتم الموافقة على استخدامها

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

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

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

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

نتائج البحث

searchresults-only

mobileLayout سلسلة

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

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

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

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

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

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

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

مربّع البحث

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

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

مربّع البحث

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

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

مربّع البحث

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

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

نتائج البحث

searchresults-only

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

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

نتائج البحث

searchresults-only

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

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

أي لون
imageSearchLayout سلسلة متاح فقط في حالة تم تفعيل ميزة "البحث بالصور" في لوحة تحكّم "محرك البحث المبرمَج".

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

نتائج البحث

searchresults-only

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، فسيتم إيقاف بحث الويب. تُستخدم عادةً فقط إذا تم تفعيل ميزة "البحث بالصور" في لوحة تحكّم "محرك البحث المبرمَج".

نتائج البحث

searchresults-only

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.

نتائج البحث

searchresults-only

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

نتائج البحث

searchresults-only

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

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

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

تتيح عمليات معاودة الاتصال التحكم التفصيلي في إعداد عنصر البحث وعمليات البحث. يتم تسجيلها باستخدام JavaScript لعنصر البحث من خلال __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 على الوضع الافتراضي البحث في مربّع بحث صور، أو تحديد أنّ طلبات البحث التي يتم إرسالها من خلال نموذج "محرك البحث المبرمَج" تنفيذه في عنصر searchresults فقط. مشاهدة عرض توضيحي

يتم التحكّم في دور استدعاء الإعداد من خلال قيمة 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 عنصر البحث ست استدعاءات تعمل في عملية التحكّم في البحث تأتي استدعاءات البحث على شكل أزواج، ومعاودة اتصال لبحث الويب ومعاودة اتصال مطابقة للبحث بالصور:

  • بدء البحث
    • للبحث بالصور
    • لبحث الويب
  • النتائج جاهزة
    • للبحث بالصور
    • لبحث الويب
  • تمّ عرض النتائج
    • للبحث بالصور
    • لبحث الويب

مثل استدعاء الإعداد، يتم وصف استدعاءات البحث باستخدام إدخالات في الكائن __gcse. ويحدث هذا عندما يتم عرض عنصر البحث بدء تشغيل JavaScript. ويتم تجاهل التعديلات على __gcse بعد بدء التشغيل.

يتم اجتياز كل من عمليات معاودة الاتصال هذه وتجاوز gName عنصر البحث كوسيطة. ويمكن الاستفادة من gname عندما تحتوي الصفحة على أكثر من عملية بحث واحدة. إجراء بحث العنصر gname باستخدام السمة data-gname:

<div class="gcse-searchbox" data-gname="storesearch"></div>

إذا لم يحدد HTML الاسم gname، فإن JavaScript لعنصر البحث تنشئ قيمةً متسقة حتى يتم تعديل HTML.

معاودة الاتصال لبدء بحث الصور/الويب

يتم استدعاء استدعاءات بدء البحث مباشرةً قبل طلبات JavaScript لعنصر البحث نتائج البحث من خادمها. من الأمثلة على حالة الاستخدام هي استخدام التوقيت المحلي من اليوم التحكم في التغييرات على الاستعلام.

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 في يضيف مثال على معاودة الاتصال المعروضة بالنتائج Keep وهميًا مربّع اختيار لكل إعلان ترويجي ونتيجة

مثال على معاودة الاتصال المعروضة بالنتائج
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 في النتائج النوع غير القابل للضبط لمصفوفة من الأخرى. يتم التحكم في قيم الإدخالات في هذا الصفيف من خلال البيانات المنظَّمة الموجودة في صفحة الويب لكل نتيجة بحث. على سبيل المثال، قد يتضمن أحد مواقع المراجعات على الويب البيانات المنظَّمة التي تضيف إدخال الصفيف هذا إلى 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 (الكائن): السمات الاختيارية على شكل key:value زوج. السمات المسموح بها.
.go(opt_container) يعرض جميع علامات/فئات عنصر البحث في الحاوية المحددة.

المعلّمات

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

يتضمّن عنصر element المعروض السمات التالية:

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

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

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