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

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

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

مقدمه

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

محدوده

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

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

فهرست مرورگرهای پشتیبانی‌شده توسط موتور جستجوی قابل برنامه‌ریزی را می‌توانید اینجا بیابید.

مخاطب

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

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

شما می‌توانید از نشانه‌گذاری 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">

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

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

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

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

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

  • مدیریت تاریخچه فعال است
  • حداکثر تعداد تکمیل خودکار نمایش داده شده روی ۵ تنظیم شده است
  • اصلاحات به صورت لینک نمایش داده می‌شوند. 

<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 آدرس اینترنتی آدرس اینترنتی صفحه نتایج. (به طور پیش‌فرض، صفحه میزبانی شده توسط گوگل است.) فقط کادر جستجو
newWindow بولی مشخص می‌کند که آیا صفحه نتایج در پنجره جدید باز شود یا خیر. پیش‌فرض: false . فقط کادر جستجو
ivt بولی

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

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 رشته فقط در صورتی موجود است که اصلاحات در پنل کنترل موتور جستجوی قابل برنامه‌ریزی ایجاد شده باشند. برچسب اصلاح پیش‌فرض برای نمایش را مشخص می‌کند. توجه: این ویژگی برای طرح میزبانی‌شده توسط گوگل پشتیبانی نمی‌شود. هر
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 (Clip art)، face (Faces of people)، lineart (Lineart)، تصاویر stock (Stock photos)، photo (Photographs) و تصاویر animated (Animated GIFs).

هر

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

نتایج جستجو

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

webSearchQueryAddition رشته عبارات اضافی با استفاده از OR منطقی به عبارت جستجو اضافه شدند.

نمونه کاربرد: <div class="gcse-search" data-webSearchQueryAddition="term1 term2"></div>

 هر
webSearchResultSetSize عدد صحیح، رشته حداکثر اندازه مجموعه نتایج. هم برای جستجوی تصویر و هم برای جستجوی وب اعمال می‌شود. مقدار پیش‌فرض به طرح‌بندی و اینکه آیا موتور جستجوی قابل برنامه‌ریزی برای جستجو در کل وب یا فقط سایت‌های مشخص‌شده پیکربندی شده است، بستگی دارد. مقادیر قابل قبول عبارتند از:
  • یک عدد صحیح از ۱ تا ۲۰
  • small : درخواست یک مجموعه نتایج کوچک، معمولاً ۴ نتیجه در هر صفحه.
  • large : یک مجموعه نتایج بزرگ را درخواست می‌کند، معمولاً ۸ نتیجه در هر صفحه.
  • filtered_cse : حداکثر ۱۰ نتیجه در هر صفحه، برای حداکثر ۱۰ صفحه یا ۱۰۰ نتیجه، درخواست می‌کند.
 هر
webSearchSafesearch رشته مشخص می‌کند که آیا جستجوی ایمن برای نتایج جستجوی وب فعال است یا خیر. مقادیر پذیرفته شده off و active هستند. هر
as_filetype رشته نتایج را به فایل‌هایی با پسوند مشخص محدود می‌کند. فهرستی از انواع فایل‌های قابل فهرست‌بندی توسط گوگل را می‌توانید در مرکز راهنمای کنسول جستجو پیدا کنید.

هر

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 هستند. هر

تماس‌های برگشتی

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

فراخوانی‌های برگشتی از کنترل دقیق مقداردهی اولیه عنصر جستجو و فرآیندهای جستجو پشتیبانی می‌کنند. آن‌ها از طریق شیء سراسری __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 در __gcse به explicit تنظیم شده باشد، عنصر جستجو جاوا اسکریپت رندر عناصر جستجو را به فراخوانی اولیه (همانطور که در Register Callbacks نشان داده شده است) واگذار می‌کند. این ممکن است برای انتخاب عناصر برای رندر یا به تعویق انداختن رندر عناصر تا زمانی که مورد نیاز باشند، استفاده شود. همچنین می‌تواند ویژگی‌های عناصر را نادیده بگیرد. به عنوان مثال، می‌تواند یک کادر جستجو را که از طریق کنترل پنل یا ویژگی‌های HTML پیکربندی شده است، به طور پیش‌فرض برای جستجوی وب به یک کادر جستجوی تصویر تبدیل کند، یا مشخص کند که پرس‌وجوهای ارسال شده از طریق فرم موتور جستجوی قابل برنامه‌ریزی در یک عنصر فقط نتایج جستجو اجرا می‌شوند. نسخه آزمایشی را ببینید.

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

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

کد زیر نحوه رندر کردن یک کادر جستجو، به همراه نتایج جستجو، در یک div را با استفاده از parsetag explicit و فراخوانی اولیه نشان می‌دهد:

مثال فراخوانی اولیه

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

    <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 قرار دهید یا به صورت پویا با جاوا اسکریپت تابع callback را به شیء اضافه کنید: 

window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
مثال جستجو شروع فراخوانی

مثال فراخوانی شروع جستجو در Example Search Starting Callback بسته به زمان روز 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>

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

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

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

اگر این فراخوانی مقدار true ) را برگرداند، عنصر جستجو (Search Element) جاوا اسکریپت به کار پاورقی صفحه (page-footer) خود می‌پردازد.

نتایج مثال، پاسخ به تماس آماده

مثال فراخوانی resultsReady در 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 در تابع فراخوانی نتایج ready وجود دارد، می‌تواند آن اطلاعات را بین آنها به صورت زیر ارسال کند: 

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

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

مثال نتایج رندر شده پاسخ به تماس

مثال فراخوانی resultsRendered در 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>

اگر نتایج رندر شده‌ی callback به اطلاعاتی نیاز داشته باشد که به result ready callback ارسال شده باشد، می‌تواند آن داده‌ها را بین callbackها منتقل کند. مثال زیر یکی از روش‌های مختلف برای ارسال مقدار امتیاز از richSnippet از result ready callback به results render شده callback را نشان می‌دهد.

مثالی از فراخوانی نتایج آماده همکاری با فراخوانی نتایج رندر شده 
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};
};
 این callback را با استفاده از کدی مانند این هنگام راه‌اندازی __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>
مثال نتایج رندر شده فراخوانی پاسخ: باز کردن انواع فایل خاص در تب/پنجره جدید

مثال فراخوانی زیر می‌تواند لینک‌های نتایج جستجو را پس از رندر شدن، طوری تغییر دهد که یک فایل خاص را به جای پنجره فعلی (مثلاً PDF، Excel یا Word) در یک تب/صفحه جدید باز کنند. این کار باعث بهبود تجربه مرور می‌شود، زمانی که کاربران نمی‌خواهند فایلی را در همان پنجره باز کنند و از صفحه نتایج خارج شوند.

این مثال فراخوانی، لینک‌های PDF را در نتایج جستجو شناسایی می‌کند و ویژگی target="_blank" را روی لینک‌های PDF تنظیم می‌کند تا در یک تب جدید باز شوند. یک MutationObserver برای مدیریت پویای نتایج جدید در صورت به‌روزرسانی صفحه استفاده می‌شود. توجه: می‌توانید .pdf در handleSearchResults با هر نوع فایل دیگری مطابق با نیاز خود جایگزین کنید.

این مثال فراخوانی مجدد روی طرح‌بندی‌های Google Hosted و Overlay کار نمی‌کند.

باز کردن انواع فایل خاص در تب/پنجره جدید 
function handleSearchResults() {
  const links = document.querySelectorAll('.gsc-results .gs-title');
  links.forEach(link => {
    const url = link.href;
    if (url?.toLowerCase().endsWith('.pdf')) {
      link.setAttribute('target', '_blank');
    }
  });
}

const myWebResultsRenderedCallback = () => {
  // Call handleSearchResults when results are rendered
  handleSearchResults();
  // Set up a MutationObserver to handle subsequent updates to the results
  const observer = new MutationObserver(handleSearchResults);
  const searchResultsContainer = document.querySelector('.gsc-results');
  if (searchResultsContainer) {
    observer.observe(searchResultsContainer, {
      childList: true,
      subtree: true
    });
  } else {
    console.log('No Results.');
  }
};

این 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>

مثال‌های بیشتر برای فراخوانی مجدد

مثال‌های بیشتر برای فراخوانی مجدد را می‌توانید در سند « مثال‌های بیشتر برای فراخوانی مجدد» بیابید.

ویژگی‌های تبلیغات و نتایج

با استفاده از نمادگذاری JSDoc ، این‌ها ویژگی‌های اشیاء promotion و result هستند. در اینجا، تمام ویژگی‌هایی را که ممکن است وجود داشته باشند، فهرست می‌کنیم. وجود بسیاری از ویژگی‌ها به جزئیات 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',
},

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

شیء 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 دریافت می‌کند. اگر یافت نشد، مقدار null را برمی‌گرداند.

شیء element برگردانده شده دارای ویژگی‌های زیر است:

  • gname : نام شیء عنصر. در صورت عدم ارائه، موتور جستجوی قابل برنامه‌ریزی به طور خودکار یک gname برای شیء ایجاد می‌کند. اطلاعات بیشتر.
  • type : نوع عنصر.
  • uiOptions : آخرین ویژگی‌هایی که برای رندر کردن عنصر استفاده می‌شوند.
  • execute - تابع (رشته): یک پرس‌وجوی برنامه‌نویسی‌شده را اجرا می‌کند.
  • prefillQuery - function(string): کادر جستجو را بدون اجرای کوئری، با یک رشته کوئری از پیش پر می‌کند.
  • getInputQuery - تابع (): مقدار فعلی نمایش داده شده در کادر ورودی را برمی‌گرداند.
  • تابع () clearAllResults - تابع ()function: با مخفی کردن همه چیز به جز کادر جستجو، در صورت وجود، کنترل را پاک می‌کند.

کد زیر کوئری "news" را در عنصر جستجو "element1" اجرا می‌کند: 

var element = google.search.cse.element.getElement('element1');
            element.execute('news');
.getAllElements() نقشه‌ای از تمام اشیاء عنصر ایجاد شده با موفقیت، که با gname کلیدگذاری شده‌اند را برمی‌گرداند.