API کنترل عنصر جستجوی قابل برنامه ریزی

می توانید اجزای موتور جستجوی قابل برنامه ریزی (جعبه های جستجو و صفحات نتایج جستجو) را با استفاده از نشانه گذاری HTML در صفحات وب خود و سایر برنامه های کاربردی وب جاسازی کنید. این عناصر موتور جستجوی قابل برنامه ریزی شامل اجزایی هستند که بر اساس تنظیمات ذخیره شده توسط سرور جستجوی قابل برنامه ریزی همراه با هر گونه سفارشی سازی که انجام می دهید ارائه می شوند.

همه جاوا اسکریپت به صورت ناهمزمان بارگیری می شود، که به صفحه وب شما اجازه می دهد تا زمانی که مرورگر جاوا اسکریپت موتور جستجوی قابل برنامه ریزی را واکشی می کند، به بارگیری ادامه دهد.

مقدمه

این سند یک مدل پایه برای افزودن عناصر موتور جستجوی قابل برنامه ریزی به صفحه وب شما به همراه توضیحاتی در مورد اجزای قابل تنظیم عنصر و API انعطاف پذیر جاوا اسکریپت ارائه می دهد.

دامنه

این سند نحوه استفاده از توابع و ویژگی های خاص API کنترل موتور جستجوی برنامه پذیر را شرح می دهد.

سازگاری با مرورگر

لیست مرورگرهای پشتیبانی شده توسط موتور جستجوی برنامه پذیر را می توانید در اینجا بیابید.

مخاطب

این مستندات برای توسعه دهندگانی در نظر گرفته شده است که مایلند قابلیت جستجوی قابل برنامه ریزی 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>

با استفاده از عناصر جستجوی قابل برنامه ریزی گزینه های طرح بندی مختلف را بنویسید

گزینه های طرح بندی زیر در صفحه ظاهر و احساس صفحه کنترل قابل برنامه ریزی موتور جستجو در دسترس هستند. در اینجا چند دستورالعمل کلی در مورد ترکیب گزینه‌های طرح‌بندی با استفاده از عناصر جستجوی برنامه‌پذیر آمده است. برای مشاهده نسخه نمایشی هر یک از این گزینه ها، روی پیوند کلیک کنید.

گزینه جزء(های)
تمام عرض <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">
میزبانی گوگل <div class="gcse-searchbox-only">

اطلاعات بیشتر در مورد گزینه های طرح بندی.

سفارشی کردن عناصر جستجوی قابل برنامه ریزی

برای سفارشی کردن رنگ ها، فونت یا سبک پیوند، به صفحه Look and Feel موتور جستجوی قابل برنامه ریزی خود بروید.

می‌توانید از ویژگی‌های اختیاری برای بازنویسی پیکربندی‌های ایجاد شده در پانل کنترل موتور جستجوی قابل برنامه‌ریزی استفاده کنید. این به شما امکان می دهد تا یک تجربه جستجوی خاص برای صفحه ایجاد کنید. به عنوان مثال، کد زیر یک کادر جستجو ایجاد می کند که یک صفحه نتیجه (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 "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 ، مدیریت سابقه را برای دکمه‌های برگشت و جلو مرورگر فعال می‌کند. دمو را ببینید.

جعبه جستجو

فقط در جعبه جستجو

queryParameterName رشته نام پارامتر پرس و جو - برای مثال q (پیش فرض) یا query . این در URL جاسازی خواهد شد (به عنوان مثال، http://www.example.com?q=lady+gaga). توجه داشته باشید که تعیین نام پارامتر پرس و جو به تنهایی باعث ایجاد جستجوی خودکار در بار نمی شود. برای اجرای جستجوی خودکار، یک رشته پرس و جو باید در URL وجود داشته باشد. هر
resultsUrl URL آدرس صفحه نتایج (پیش‌فرض صفحه میزبان گوگل است.) فقط در جعبه جستجو
newWindow بولی مشخص می کند که آیا صفحه نتایج در یک پنجره جدید باز می شود یا خیر. پیش فرض: false . فقط در جعبه جستجو
ivt بولی

این پارامتر به شما امکان می‌دهد یک بولی ارائه دهید که به Google اطلاع می‌دهد که می‌خواهید به تبلیغاتی که از کوکی فقط ترافیک نامعتبر و فضای ذخیره‌سازی محلی استفاده می‌کنند، هم در ترافیک مورد رضایت و هم بدون رضایت اجازه دهید.

true وقتی این پارامتر وجود نداشته باشد یا آن را روی "true" تنظیم کنید، یک کوکی فقط برای ترافیک نامعتبر تنظیم می کنیم و از فضای ذخیره سازی محلی فقط در ترافیک مورد رضایت استفاده می کنیم.

false وقتی این پارامتر را روی "نادرست" تنظیم می‌کنید، یک کوکی فقط ترافیکی نامعتبر تنظیم می‌کنیم و از فضای ذخیره‌سازی محلی هم در ترافیک مورد رضایت و هم بدون رضایت استفاده می‌کنیم.

پیش فرض: false

استفاده از نمونه: <div class="gcse-search" data-ivt="true"></div>

نتایج جستجو

فقط نتایج جستجو

mobileLayout رشته

مشخص می کند که آیا سبک های چیدمان تلفن همراه باید برای دستگاه های تلفن همراه استفاده شود یا خیر.

enabled از طرح‌بندی تلفن همراه فقط برای دستگاه‌های تلفن همراه استفاده می‌کند.

disabled از چیدمان تلفن همراه برای هیچ دستگاهی استفاده نمی کند.

forced از چیدمان موبایل برای همه دستگاه ها استفاده می کند.

پیش فرض: enabled

استفاده از نمونه: <div class="gcse-search" data-mobileLayout="disabled"></div>

 هر
تکمیل خودکار
enableAutoComplete بولی فقط در صورتی در دسترس است که تکمیل خودکار در کنترل پنل موتور جستجوی قابل برنامه ریزی فعال شده باشد. true تکمیل خودکار را فعال می کند. هر
autoCompleteMaxCompletions عدد صحیح حداکثر تعداد تکمیل خودکار برای نمایش.

جعبه جستجو

فقط برای جعبه جستجو

autoCompleteMaxPromotions عدد صحیح حداکثر تعداد تبلیغات برای نمایش در تکمیل خودکار.

جعبه جستجو

فقط برای جعبه جستجو

autoCompleteValidLanguages رشته فهرست زبان‌هایی که با ویرگول جدا شده‌اند، باید تکمیل خودکار برای آنها فعال شود. زبان های پشتیبانی شده

جعبه جستجو

فقط برای جعبه جستجو

اصلاحات
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 رشته تنها در صورتی در دسترس است که جستجوی تصویر در کنترل پنل موتور جستجوی قابل برنامه ریزی فعال شده باشد.

نتایج جستجو را با استفاده از Logical 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 رشته مشخص می کند که آیا جستجوی ایمن برای نتایج جستجوی وب فعال باشد یا خیر. مقادیر پذیرفته شده off و active هستند. هر
as_filetype رشته نتایج را به فایل های یک پسوند مشخص محدود می کند. فهرستی از انواع فایل‌های قابل فهرست‌بندی توسط Google را می‌توانید در مرکز راهنمای کنسول جستجو پیدا کنید.

هر

as_oq رشته نتایج جستجو را با استفاده از Logical 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 هستند. هر

تماس های تلفنی

نمودار توالی برگشت به تماس
نمودار توالی فراخوان ها از جستجوی عنصر جاوا اسکریپت

Callbacks از کنترل دقیق اولیه سازی عنصر جستجو و فرآیندهای جستجو پشتیبانی می کند. آنها با جستجوی عنصر جاوا اسکریپت از طریق شیء جهانی __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,
      },
    },
  };

پاسخ به تماس اولیه

فراخوانی اولیه قبل از اینکه عنصر جستجو جاوا اسکریپت عناصر جستجو را در DOM ارائه کند فراخوانی می شود. اگر parsetags به explicit در __gcse تنظیم شده باشد، عنصر جستجو جاوا اسکریپت رندر عناصر جستجو را به بازگشت به تماس اولیه می‌گذارد (همانطور که در Register Callbacks نشان داده شده است). این ممکن است برای انتخاب عناصر برای رندر یا به تعویق انداختن عناصر رندر تا زمانی که آنها مورد نیاز هستند استفاده شود. همچنین می تواند ویژگی های عناصر را نادیده بگیرد. برای مثال، می‌تواند یک جعبه جستجو را که از طریق کنترل پنل یا ویژگی‌های HTML به صورت پیش‌فرض برای جستجوی وب پیکربندی شده است، به کادر جستجوی تصویر تبدیل کند، یا مشخص کند که درخواست‌های ارسال شده از طریق یک فرم موتور جستجوی قابل برنامه‌ریزی در یک عنصر فقط نتایج جستجو اجرا شوند. دمو را ببینید.

نقش بازخوانی اولیه توسط مقدار ویژگی parsetags __gcse کنترل می شود.

  • اگر مقدار آن onload باشد، جاوا اسکریپت عنصر جستجو همه عناصر جستجو را در صفحه به طور خودکار نمایش می دهد. فراخوانی اولیه هنوز فراخوانی می شود، اما مسئولیتی برای ارائه عناصر جستجو ندارد.
  • اگر مقدار آن explicit باشد، جاوا اسکریپت عنصر جستجو عناصر جستجو را نمایش نمی دهد. پاسخ تماس ممکن است آنها را به صورت انتخابی با استفاده از تابع render() رندر کند یا تمام عناصر جستجو را با تابع go() رندر کند.

کد زیر نشان می دهد که چگونه می توان یک جعبه جستجو را همراه با نتایج جستجو در یک div با استفاده از تگ parset explicit و بازخوانی اولیه ارائه کرد:

نمونه اولیه Callback

ما باید یک <div> با یک مقدار شناسه درج کنیم که در آن کد عنصر جستجو را می‌خواهیم:

    <div id="test"></div>
این جاوا اسکریپت را بعد از <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>

جستجوی تماس ها

جاوا اسکریپت عنصر جستجو از شش تماس برگشتی پشتیبانی می کند که در جریان کنترل جستجو عمل می کنند. تماس‌های جستجو به صورت جفت، یک تماس جستجوی وب و پاسخ به تماس جستجوی تصویر مطابقت دارند:

  • شروع جستجو
    • برای جستجوی تصویر
    • برای جستجوی وب
  • نتایج آماده است
    • برای جستجوی تصویر
    • برای جستجوی وب
  • نتایج ارائه شده
    • برای جستجوی تصویر
    • برای جستجوی وب

مانند پاسخ تماس اولیه، تماس های جستجو با استفاده از ورودی های شی __gcse پیکربندی می شوند. این با شروع جاوا اسکریپت عنصر جستجو اتفاق می افتد. تغییرات __gcse پس از راه‌اندازی نادیده گرفته می‌شوند.

به هر یک از این فراخوان ها gName برای عنصر جستجو به عنوان آرگومان ارسال می شود. gname زمانی مفید است که یک صفحه دارای بیش از یک جستجو باشد. با استفاده از ویژگی data-gname به عنصر جستجو مقادیر gname بدهید:

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

اگر HTML gname را شناسایی نکند، عنصر جستجو جاوا اسکریپت مقداری ایجاد می کند که تا زمانی که HTML اصلاح نشود، ثابت می ماند.

تصویر/جستجوی وب-شروع پاسخ به تماس

تماس‌های شروع جستجو بلافاصله قبل از درخواست جستجوی عنصر جاوا اسکریپت از سرور خود، فراخوانی می‌شوند. یک مثال مورد استفاده، استفاده از زمان محلی روز برای کنترل تغییرات در پرس و جو است.

searchStartingCallback(gname, query)
gname
جستجوی رشته شناسایی عنصر
query
مقدار وارد شده توسط کاربر (احتمالاً توسط عنصر جستجو جاوا اسکریپت اصلاح شده است.)

تماس برگشتی مقداری را که باید به عنوان پرس و جو برای این جستجو استفاده شود برمی گرداند. اگر یک رشته خالی برگرداند، مقدار بازگشتی نادیده گرفته می شود و تماس گیرنده از پرس و جوی اصلاح نشده استفاده می کند.

همچنین، می‌توانید تابع callback را در شی __gcse قرار دهید یا به صورت پویا با جاوا اسکریپت پاسخ تماس را به شی اضافه کنید: 

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;

این callback را در 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>

نتایج جستجوی تصویر/وب - پاسخ به تماس آماده

این تماس‌ها بلافاصله قبل از اینکه عنصر جستجوی جاوا اسکریپت تبلیغات و نتایج را ارائه کند، فراخوانی می‌شوند. یک مثال استفاده از یک callback است که تبلیغات را ارائه می دهد و به سبکی منجر می شود که با سفارشی سازی معمولی قابل تعیین نیست.

resultsReadyCallback(gname, query, promos, results, div)
gname
جستجوی رشته شناسایی عنصر
query
جستجویی که این نتایج را ایجاد کرد
promos
آرایه ای از اشیاء تبلیغاتی، که با تبلیغات منطبق برای درخواست کاربر مطابقت دارد. تعریف شی تبلیغاتی را ببینید.
results
آرایه ای از اشیاء نتیجه تعریف شی نتیجه را ببینید.
div
یک div HTML در DOM که عنصر جستجو معمولاً تبلیغات و نتایج جستجو را در آن قرار می دهد. به طور معمول، جاوا اسکریپت عنصر جستجو، پر کردن این div را انجام می‌دهد، اما این فراخوان ممکن است رندر خودکار نتایج را متوقف کند و از این div برای ارائه خود نتایج استفاده کند.

اگر این فراخوانی مقدار true را برگرداند، جاوا اسکریپت عنصر جستجو به کار پاورقی صفحه خود می‌رود.

نتایج نمونه پاسخ به تماس آماده

مثال resultsReady callback در Example Results Ready Callback ارائه پیش‌فرض تبلیغات و نتایج را با یک جایگزین بسیار ساده لغو می‌کند.

نمونه پاسخ به تماس آماده نتایج 
    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;
    };

این callback را در 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 است.

تصویر/نتایج جستجوی وب - پاسخ به تماس ارائه شده

این تماس‌ها بلافاصله قبل از اینکه عنصر جستجوی جاوا اسکریپت پاورقی صفحه را ارائه کند، فراخوانی می‌شوند. موارد استفاده مثال شامل پاسخ به تماسی است که محتوای نتیجه‌ای را اضافه می‌کند که عنصر جستجو نمایش نمی‌دهد، مانند ذخیره این کادر انتخاب یا اطلاعاتی که به‌طور خودکار ارائه نمی‌شوند، یا پاسخ به تماسی که دکمه‌های اطلاعات بیشتر را اضافه می‌کند.

اگر یک نتیجه رندر شده به اطلاعاتی نیاز داشته باشد که در promos و پارامترهای results پاسخ به تماس آماده نتایج وجود داشته باشد، می تواند آن را بین آنها ارسال کند، مانند این:

callback(gname, query, promoElts, resultElts);
gname
جستجوی رشته شناسایی عنصر
query
رشته جستجو
promoElts
آرایه ای از عناصر DOM حاوی تبلیغات.
resultElts
آرایه ای از عناصر DOM حاوی نتایج.

هیچ ارزش بازگشتی وجود ندارد.

نتایج نمونه پاسخ به تماس ارائه شده

مثال resultsRendered callback در Example Results Rendered Callback یک چک باکس 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);
    }
  };

این callback را در 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>

نمونه های بیشتر برای پاسخ به تماس

نمونه‌های پاسخ به تماس اضافی را می‌توانید در سند More Callback Examples پیدا کنید.

ویژگی های ارتقا و نتیجه

با استفاده از نماد JSDoc ، اینها ویژگی های اشیاء تبلیغاتی و نتیجه هستند. در اینجا، ما تمام ویژگی هایی را که ممکن است وجود داشته باشند، فهرست می کنیم. وجود بسیاری از خواص به جزئیات تبلیغات یا نتیجه جستجو بستگی دارد.

ویژگی های تبلیغاتی 
{
  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',
},

API کنترل عنصر جستجوی قابل برنامه ریزی (V2)

شی google.search.cse.element توابع ثابت زیر را منتشر می کند:

تابع توضیحات
.render(componentConfig, opt_componentConfig) یک عنصر جستجو را ارائه می دهد.

پارامترها

نام توضیحات
componentConfig پیکربندی برای یک جزء جستجوی قابل برنامه ریزی. موارد زیر را مشخص می کند:
  • div (string|Element): id <div> یا عنصر div که عنصر جستجوی قابل برنامه ریزی قرار است در آن رندر شود.
  • tag (رشته): نوع مؤلفه (های) که باید ارائه شود. (زمانی که opt_componentConfig ارائه می شود، مقدار مشخصه tag باید searchbox باشد.) مقادیر مجاز عبارتند از:
    • search : یک کادر جستجو و نتایج جستجو که با هم نمایش داده می شوند
    • searchbox : جزء جعبه جستجو از یک عنصر جستجوی قابل برنامه ریزی.
    • searchbox-only : یک کادر جستجوی مستقل، که با بلوکی از نتایج جستجو که توسط opt_componentConfig در طرح‌بندی دو ستونی مشخص شده است، جفت می‌شود.
    • searchresults-only : یک بلوک مستقل از نتایج جستجو. جستجوها توسط یک پارامتر پرس و جو تعبیه شده در URL یا با اجرای برنامه‌ای آغاز می‌شوند.
  • gname (رشته): (اختیاری) یک نام منحصر به فرد برای این مؤلفه. اگر ارائه نشود، موتور جستجوی قابل برنامه ریزی به طور خودکار یک gname ایجاد می کند.
  • attributes (Object): ویژگی های اختیاری در قالب یک جفت کلید:مقدار. ویژگی های پشتیبانی شده
opt_componentConfig اختیاری. آرگومان پیکربندی جزء دوم. در حالت TWO_COLUMN برای ارائه مولفه searchresults استفاده می شود. موارد زیر را مشخص می کند:
  • div (رشته): id <div> یا عنصر div که عنصر قرار است در آن رندر شود.
  • tag (رشته): نوع مؤلفه (های) که باید ارائه شود. وقتی opt_componentConfig ارائه می‌شود، مقدار مشخصه tag باید searchresults باشد. علاوه بر این، مقدار ویژگی tag componentConfig باید searchbox باشد.
  • gname (رشته): (اختیاری) یک نام منحصر به فرد برای این مؤلفه. در صورت عدم ارائه، موتور جستجوی قابل برنامه‌ریزی به‌طور خودکار یک gname برای این مؤلفه ایجاد می‌کند. در صورت ارائه، باید با gname در componentConfig مطابقت داشته باشد.
  • attributes (Object): ویژگی های اختیاری در قالب یک جفت کلید:مقدار. ویژگی های پشتیبانی شده
.go(opt_container) همه برچسب‌ها/کلاس‌های عنصر جستجو را در ظرف مشخص شده ارائه می‌کند.

پارامترها

نام توضیحات
opt_container ظرف حاوی اجزای عنصر جستجو برای ارائه. شناسه کانتینر (رشته) یا خود عنصر را مشخص کنید. اگر حذف شود، تمام اجزای عنصر جستجوی قابل برنامه ریزی در داخل تگ body صفحه نمایش داده می شود.
.getElement(gname) شی عنصر را با gname دریافت می کند. اگر پیدا نشد، null را برگردانید.

شی 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 کلید شده اند، برمی گرداند.