Programmable Search Element Control API

HTML işaretlemesini kullanarak Programlanabilir Arama Motoru bileşenlerini (arama kutuları ve arama sonuçları sayfaları) web sayfalarınıza ve diğer web uygulamalarınıza yerleştirebilirsiniz. Bu Programlanabilir Arama Motoru öğeleri, Programlanabilir Arama sunucusu tarafından depolanan ayarlara göre yaptığınız bileşenlerin yanı sıra yaptığınız özelleştirmelerden oluşur.

Tüm JavaScript'ler eşzamansız olarak yüklenir. Böylece, tarayıcı Programlanabilir Arama Motoru JavaScript'ini getirirken web sayfanız yüklenmeye devam eder.

Giriş

Bu dokümanda, web sayfanıza Programlanabilir Arama Motoru öğeleri eklemek için bir temel modelle birlikte, öğenin yapılandırılabilir bileşenlerinin ve esnek JavaScript API'sinin açıklamaları açıklanmaktadır.

Kapsam

Bu dokümanda, Programmable Search Engine Control API'ye özgü işlevlerin ve özelliklerin nasıl kullanılacağı açıklanmaktadır.

Tarayıcı uyumluluğu

Programlanabilir Arama Motoru'nun desteklediği tarayıcıların listesini burada bulabilirsiniz.

Kitle

Bu doküman, sayfalarına Google Programlanabilir Arama işlevini eklemek isteyen geliştiriciler için hazırlanmıştır.

Programlanabilir Arama Öğeleri

Sayfanıza Programlanabilir Arama Öğesi eklemek için HTML işaretlemesini kullanabilirsiniz. Her öğe en az bir bileşenden oluşur: arama kutusu, arama sonuçları bloku veya her ikisi. Arama kutusu aşağıdaki yöntemlerden herhangi biriyle kullanıcı girişini kabul eder:

  • Metin giriş alanına girilen arama sorgusu
  • URL'ye yerleştirilmiş bir sorgu dizesi
  • Programatik yürütme

Ayrıca, arama sonuçları bloğu aşağıdaki şekillerde girişi kabul eder:

  • URL'ye yerleştirilmiş bir sorgu dizesi
  • Programatik yürütme

Aşağıdaki Programlanabilir Arama Öğesi türleri kullanılabilir:

Öğe türü Bileşenler Açıklama
standart <div class="gcse-search"> Aynı <div> içinde gösterilen bir arama kutusu ve arama sonuçları.
iki sütunlu <div class="gcse-searchbox"> ve <div class="gcse-searchresults"> Bir tarafında arama sonuçları, bir tarafında ise arama kutusu içeren iki sütunlu düzen. Web sayfanızda iki sütunlu modda birden fazla öğe eklemeyi planlıyorsanız arama kutusunu bir arama kutusuyla eşlemek için gname özelliğini kullanabilirsiniz.
yalnızca arama kutusu <div class="gcse-searchbox-only"> Bağımsız arama kutusu.
yalnızca arama sonuçları <div class="gcse-searchresults-only"> Bağımsız bir arama sonuçları bloğu.

Web sayfanıza istediğiniz sayıda geçerli Arama Öğesi ekleyebilirsiniz. İki sütunlu modda, gerekli tüm bileşenler (arama kutusu ve arama sonuçları bloğu) bulunmalıdır.

Aşağıda basit bir Arama Öğesi örneği verilmiştir:

<!-- 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>

Programlanabilir Arama Öğelerini kullanarak farklı düzen seçenekleri oluşturma

Aşağıdaki düzen seçenekleri, Programlanabilir Arama Motoru kontrol panelinin Görünüm ve Tarz sayfasında yer alır. Aşağıda, Programlanabilir Arama Öğelerini kullanarak düzen seçenekleri oluşturma hakkında bazı genel yönergeler verilmiştir. Bu seçeneklerden herhangi birinin demosunu görmek için bağlantıyı tıklayın.

Option Bileşenler
Tam genişlik <div class="gcse-search">
Kompakt <div class="gcse-search">
İki sütunlu <div class="gcse-searchbox">, <div class="gcse-searchresults">
İki sayfa İlk sayfada <div class="gcse-searchbox-only">, ikinci sayfada <div class="gcse-searchresults-only"> (veya diğer bileşenler).
Yalnızca sonuçlar <div class="gcse-searchresults-only">
Google tarafından barındırılan <div class="gcse-searchbox-only">

Düzen seçenekleri hakkında daha fazla bilgi edinin.

Programlanabilir Arama Öğelerini Özelleştirme

Renkleri, yazı tipini veya bağlantı stilini özelleştirmek için programlanabilir arama motorunuzun Görünüm ve Tarz sayfasına gidin.

Programlanabilir Arama Motoru kontrol panelinde oluşturulan yapılandırmaların üzerine yazmak için isteğe bağlı özellikleri kullanabilirsiniz. Bu, sayfaya özgü bir arama deneyimi oluşturmanıza olanak tanır. Örneğin, aşağıdaki kod bir sonuç sayfasını (http://www.example.com?search=lady+gaga) yeni bir pencerede açan bir arama kutusu oluşturur. Sonuç URL'sini oluşturmak için kullanıcı sorgusu dizesiyle birlikte queryParameterName özelliğinin değeri kullanılır.

queryParameterName özelliğinin önüne data- eklendiğini unutmayın. Bu ön ek, tüm özellikler için zorunludur.

<div class="gcse-searchbox-only" data-resultsUrl="http://www.example.com" data-newWindow="true" data-queryParameterName="search">

Otomatik tamamlama veya hassaslaştırma gibi özellikleri etkinleştirmek için Programlanabilir Arama Motoru kontrol panelini kullandıysanız bu özellikleri özelleştirmek için özelliklerden yararlanabilirsiniz. Bu özellikleri kullanarak belirttiğiniz tüm özelleştirmeler, kontrol panelinde yapılan ayarları geçersiz kılar. Aşağıdaki örnekte, aşağıdaki özelliklere sahip iki sütunlu bir Arama Öğesi oluşturulur:

  • Geçmiş yönetimi etkin
  • Görüntülenen maksimum otomatik tamamlama sayısı 5 olarak ayarlanmıştır.
  • Ayrıntılandırmalar bağlantı olarak görüntülenir.

<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5">
<div class="gcse-searchresults" data-refinementStyle="link">

Desteklenen özellikler

Özellik Type Açıklama Bileşen
Genel
gname Dize (İsteğe bağlı) Search Element nesnesinin adı. Ad, ilişkili bir bileşeni ada göre almak veya searchbox bileşenini, searchresults bileşeniyle eşlemek için kullanılır. Sağlanmazsa Programlanabilir Arama Motoru, web sayfasındaki bileşenlerin sırasına göre otomatik olarak bir gname oluşturur. Örneğin, adsız ilk searchbox-only gname "searchbox-only0" ve gname ikincisi "gnameshipbox-only1" şeklinde içerir. İki sütunlu düzendeki bir bileşen için otomatik olarak oluşturulan gname değerinin two-column olacağını unutmayın. Aşağıdaki örnekte bir searchbox bileşeni bir searchresults bileşenine bağlamak için storesearch takma adı kullanılmaktadır:
<div class="gcse-searchbox" data-gname="storesearch"></div>
<div class="gcse-searchresults" data-gname="storesearch"></div>

Bir nesne alınırken birden fazla bileşen aynı gname öğesine sahipse Programlanabilir Arama Motoru, sayfadaki son bileşeni kullanır.

Hepsi
autoSearchOnLoad Boole Bir sayfanın, yüklenen sayfanın URL'sine yerleştirilmiş sorguya göre yürütülüp yürütülmeyeceğini belirtir. Otomatik arama gerçekleştirmek için URL'de bir sorgu dizesinin bulunması gerektiğini unutmayın. Varsayılan: true. Hepsi
enableHistory Boole true ise tarayıcının Geri ve İleri düğmeleri için geçmiş yönetimini etkinleştirir. Demoya göz atın.

arama kutusu

yalnızca arama kutusu

queryParameterName Dize Sorgu parametresi adı - örneğin, q (varsayılan) veya query. Bu, URL'nin içine yerleştirilir (örneğin, http://www.example.com?q=lady+gaga). Sorgu parametresi adını tek başına yüklemenin otomatik aramayı tetiklemediğini unutmayın. Otomatik aramanın gerçekleştirilmesi için URL'de bir sorgu dizesinin bulunması gerekir. Hepsi
resultsUrl URL Sonuç sayfasının URL'si. (Varsayılan olarak Google tarafından barındırılan sayfadır.) yalnızca arama kutusu
newWindow Boole Sonuç sayfasının yeni bir pencerede açılıp açılmayacağını belirtir. Varsayılan: false. yalnızca arama kutusu
personalizedAds Boole

Kullanıcıların, yayıncının kişiselleştirilmiş reklamcılık amacıyla kişisel bilgileri Google ile paylaşmasına izin vermeyi kabul edip etmediğini belirtir.

true Sorgu hedefli reklamları ve kullanıcının Google çerezleriyle hedeflenebilecek bazı reklamları döndürür. Kullanıcı Avrupa Birliği'ndeyse ilk olarak sitenizin, kişiselleştirilmiş reklamcılık için kişisel bilgileri Google ile paylaşmasına izin vermelidir.

false Yalnızca sorgu hedefli reklamları döndürür. Bu, kullanıcının Google çerezleriyle hedeflenen reklamları döndürmez. Kullanıcı, sitenizin kişiselleştirilmiş reklamcılık amacıyla kişisel bilgileri Google ile paylaşmasına izin vermeyi reddetmişse bu değeri false olarak ayarlamanız gerekir.

Varsayılan: true

Örnek kullanım: <div class="gcse-search" data-personalizedAds="false"></div>

arama sonuçları

yalnızca arama sonuçları

mobileLayout Dize

Mobil düzen stillerinin mobil cihazlar için kullanılıp kullanılmayacağını belirtir.

enabled Mobil düzeni yalnızca mobil cihazlar için kullanır.

disabled Mobil düzeni hiçbir cihaz için kullanmaz.

forced Tüm cihazlar için mobil düzeni kullanır.

Varsayılan: enabled

Örnek kullanım: <div class="gcse-search" data-mobileLayout="disabled"></div>

Hepsi
Otomatik tamamlama
enableAutoComplete Boole Yalnızca otomatik arama, Programlanabilir Arama Motoru kontrol panelinde etkinleştirildiyse kullanılabilir. true otomatik tamamlamayı etkinleştirir. Hepsi
autoCompleteMaxCompletions Tamsayı Gösterilecek maksimum otomatik tamamlama sayısı.

arama kutusu

yalnızca arama kutusu

autoCompleteMaxPromotions Tamsayı Otomatik tamamlamada görüntülenecek maksimum promosyon sayısı.

arama kutusu

yalnızca arama kutusu

autoCompleteValidLanguages Dize Otomatik tamamlamanın etkinleştirilmesi gereken dillerin virgülle ayrılmış listesi. Desteklenen diller.

arama kutusu

yalnızca arama kutusu

Ayrıntılandırmalar
defaultToRefinement Dize Yalnızca Programlanabilir Arama Motoru kontrol panelinde ayrıntılandırmalar oluşturulduysa kullanılabilir. Görüntülenecek varsayılan ayrıntılandırma etiketini belirtir.Not: Bu özellik, Google tarafından barındırılan düzen için desteklenmez. Hepsi
refinementStyle Dize Kabul edilebilir değerler tab (varsayılan) ve link'dir. link yalnızca görsel arama veya görsel arama etkinleştirilmiş ancak web araması devre dışı bırakılmışsa desteklenir.

arama sonuçları

yalnızca arama sonuçları

Görsel arama
enableImageSearch Boole Yalnızca Programlanabilir Arama Motoru kontrol panelinde görsel arama etkinleştirilmişse kullanılabilir.

true ise resim aramayı etkinleştirir. Görsel sonuçları ayrı bir sekmede gösterilir.

arama sonuçları

yalnızca arama sonuçları

defaultToImageSearch Boole Yalnızca Programlanabilir Arama Motoru kontrol panelinde görsel arama etkinleştirilmişse kullanılabilir.

true ise arama sonuçları sayfasında varsayılan olarak görsel arama sonuçları görüntülenir. Web sonuçları ayrı bir sekmede sunulacaktır.

Hepsi
imageSearchLayout Dize Yalnızca Programlanabilir Arama Motoru kontrol panelinde görsel arama etkinleştirilmişse kullanılabilir.

Görsel arama sonuçları sayfasının düzenini belirtir. Kabul edilebilir değerler classic, column veya popup'dur.

arama sonuçları

yalnızca arama sonuçları

imageSearchResultSetSize Tam sayı, Dize Yalnızca Programlanabilir Arama Motoru kontrol panelinde görsel arama etkinleştirilmişse kullanılabilir.

Görsel arama için belirlenen arama sonuçlarının maksimum boyutunu belirtir. Örneğin, large, small, filtered_cse, 10.

Hepsi
image_as_filetype Dize Yalnızca Programlanabilir Arama Motoru kontrol panelinde görsel arama etkinleştirilmişse kullanılabilir.

Sonuçları, belirtilen uzantıya ait dosyalarla kısıtlar.

Desteklenen uzantılar: jpg, gif, png, bmp, svg, webp, ico, raw.

Hepsi

image_as_oq Dize Yalnızca Programlanabilir Arama Motoru kontrol panelinde görsel arama etkinleştirilmişse kullanılabilir.

Mantıksal VEYA kullanarak arama sonuçlarını filtreleyin.

"terim1" veya "terim2" ifadesini içeren arama sonuçları istiyorsanız örnek kullanım:<div class="gcse-search" data-image_as_oq="term1 term2"></div>

Hepsi

image_as_rights Dize Yalnızca Programlanabilir Arama Motoru kontrol panelinde görsel arama etkinleştirilmişse kullanılabilir.

Lisanslamaya dayalı filtreler.

Desteklenen değerler cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial, cc_nonderived ve bunların kombinasyonlarıdır.

Tipik kombinasyonlar konusuna bakın.

Hepsi

image_as_sitesearch Dize Yalnızca Programlanabilir Arama Motoru kontrol panelinde görsel arama etkinleştirilmişse kullanılabilir.

Sonuçları belirli bir sitedeki sayfalarla sınırlandır.

Örnek kullanım: <div class="gcse-search" data-image_as_sitesearch="example.com"></div>

Hepsi

image_colortype Dize Yalnızca Programlanabilir Arama Motoru kontrol panelinde görsel arama etkinleştirilmişse kullanılabilir.

Aramayı siyah beyaz (mono), gri tonlamalı veya renkli resimlerle kısıtlar. Desteklenen değerler: mono, gray, color.

Hepsi

image_cr Dize Yalnızca Programlanabilir Arama Motoru kontrol panelinde görsel arama etkinleştirilmişse kullanılabilir.

Arama sonuçlarını, belirli bir ülkeden gelen dokümanlarla sınırlar.

Desteklenen değerler

Hepsi

image_dominantcolor Dize Yalnızca Programlanabilir Arama Motoru kontrol panelinde görsel arama etkinleştirilmişse kullanılabilir.

Aramayı belirli bir baskın renkteki resimlerle sınırlar. Desteklenen değerler: red, orange, yellow, green, teal, blue, purple, pink, white, gray, black, brown.

Hepsi

image_filter Dize Yalnızca Programlanabilir Arama Motoru kontrol panelinde görsel arama etkinleştirilmişse kullanılabilir.

Arama sonuçlarını otomatik olarak filtreleme.

Desteklenen değerler: 0/1

Örnek kullanım: <div class="gcse-search" data-image_filter="0"></div>

Hepsi

image_gl Dize Yalnızca Programlanabilir Arama Motoru kontrol panelinde görsel arama etkinleştirilmişse kullanılabilir. Menşe ülkesi, parametre değeriyle eşleşen arama sonuçlarını geliştirir.

Desteklenen değerler

Hepsi

image_size Dize Yalnızca Programlanabilir Arama Motoru kontrol panelinde görsel arama etkinleştirilmişse kullanılabilir.

Belirli bir boyuttaki resimleri döndürür. Boyut şunlardan biri olabilir: icon, small, medium, large, xlarge, xxlarge veya huge.

Hepsi

image_sort_by Dize Yalnızca Programlanabilir Arama Motoru kontrol panelinde görsel arama etkinleştirilmişse kullanılabilir.

Tarih veya başka yapılandırılmış içerik kullanarak sonuçları sıralayın.

Alaka düzeyine göre sıralamak için boş dize kullanın (image_sort_by="").

Örnek kullanım: <div class="gcse-search" data-image_sort_by="date"></div>

Hepsi

image_type Dize Yalnızca Programlanabilir Arama Motoru kontrol panelinde görsel arama etkinleştirilmişse kullanılabilir.

Aramayı, belirli türden resimlerle sınırlar. Desteklenen değerler: clipart (Klip resmi), face (Yüzler), lineart (Çizgi çizim), stock (Stok fotoğraflar), photo (Fotoğraflar) ve animated (Animasyonlu GIF'ler).

Hepsi

Web'de arama
disableWebSearch Boole true ise web aramasını devre dışı bırakır. Genellikle yalnızca Programlanabilir Arama Motoru kontrol panelinde görsel arama etkinleştirilmişse kullanılır.

arama sonuçları

yalnızca arama sonuçları

webSearchQueryAddition Dize Mantıksal VEYA kullanılarak arama sorgusuna fazladan terimler eklendi.

Örnek kullanım: <div class="gcse-search" data-webSearchQueryAddition="term1 term2"></div>

Hepsi
webSearchResultSetSize Tam sayı, Dize Sonuçların maksimum boyutu. Hem görsel arama hem de web araması için geçerlidir. Varsayılan ayar, düzene ve Programlanabilir Arama Motoru'nun web'in tamamında veya yalnızca belirtilen sitelerde arama yapmak üzere yapılandırılıp yapılandırılmadığına bağlıdır. Kabul edilebilir değerler şunlardır:
  • 1-20 arasında bir tam sayı
  • small: Küçük bir sonuç kümesi ister (genellikle sayfa başına 4 sonuç).
  • large: Genelde sayfa başına 8 sonuç olmak üzere büyük bir sonuç kümesi ister.
  • filtered_cse: En fazla 10 sayfa veya 100 sonuç olmak üzere sayfa başına en fazla 10 sonuç isteyebilir.
Hepsi
webSearchSafesearch Dize Güvenli Arama'nın web sonuçları için etkinleştirilip etkinleştirilmediğini belirtir. off ve active değerleri kabul edilir. Hepsi
as_filetype Dize Sonuçları, belirtilen uzantıya ait dosyalarla kısıtlar. Google tarafından dizine eklenebilen dosya türlerinin listesini Search Console Yardım Merkezi'nde bulabilirsiniz.

Hepsi

as_oq Dize Mantıksal VEYA kullanarak arama sonuçlarını filtreleyin.

"terim1" veya "terim2" ifadesini içeren arama sonuçları istiyorsanız örnek kullanım:<div class="gcse-search" data-as_oq="term1 term2"></div>

Hepsi
as_rights Dize Lisanslamaya dayalı filtreler.

Desteklenen değerler cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial, cc_nonderived ve bunların kombinasyonlarıdır.

Tipik kombinasyonlar için https://wiki.creativecommons.org/wiki/CC_Search_integration adresine bakın.

Hepsi

as_sitesearch Dize Sonuçları belirli bir sitedeki sayfalarla sınırlandır.

Örnek kullanım: <div class="gcse-search" data-as_sitesearch="example.com"></div>

Hepsi
cr Dize Arama sonuçlarını, belirli bir ülkeden gelen dokümanlarla sınırlar.

Desteklenen değerler

Örnek kullanım: <div class="gcse-search" data-cr="countryFR"></div>

Hepsi
filter Dize Arama sonuçlarını otomatik olarak filtreleme.

Desteklenen değerler: 0/1

Örnek kullanım: <div class="gcse-search" data-filter="0"></div>

Hepsi
gl Dize Menşe ülkesi, parametre değeriyle eşleşen arama sonuçlarını geliştirir.

Bu özellik yalnızca dil değeri ayarıyla birlikte kullanılabilir.

Desteklenen değerler

Örnek kullanım: <div class="gcse-search" data-gl="fr"></div>

Hepsi
lr Dize Arama sonuçlarını, belirli bir dilde yazılmış dokümanlarla sınırlar.

Desteklenen değerler

Örnek kullanım: <div class="gcse-search" data-lr="lang_fr"></div>

Hepsi
sort_by Dize Tarih veya başka yapılandırılmış içerik kullanarak sonuçları sıralayın. Özellik değeri, programlanabilir aramanın ör. Sonuçları Sıralama ayarlarında sağlanan seçeneklerden biri olmalıdır.

Alaka düzeyine göre sıralamak için boş dize (sort_by=") kullanın.

Örnek kullanım: <div class="gcse-search" data-sort_by="date"></div>

Hepsi
Arama sonuçları
enableOrderBy Boole Sonuçların alaka düzeyi, tarih veya etikete göre sıralanmasını sağlar. Hepsi
linkTarget Dize Bağlantı hedefini ayarlar. Varsayılan: _blank.

arama sonuçları

yalnızca arama sonuçları

noResultsString Dize Sorguyla eşleşen sonuç olmadığında görüntülenecek varsayılan metni belirtir. Yerelleştirilmiş dizeyi desteklenen tüm dillerde görüntülemek için varsayılan sonuç dizesi kullanılabilir. Ancak özelleştirilen dizede bu durum görülmez.

arama sonuçları

yalnızca arama sonuçları

resultSetSize Tam sayı, Dize Sonuçların maksimum boyutu. Örneğin, large, small, filtered_cse, 10. Varsayılan değer, düzene ve motorun web'in tamamında veya yalnızca belirtilen sitelerde arama yapacak şekilde yapılandırılmasına bağlıdır. Hepsi
safeSearch Dize Güvenli Arama'nın hem web hem de görsel arama için etkinleştirilip etkinleştirilmediğini belirtir. off ve active değerleri kabul edilir. Hepsi

Geri çağırmalar

Geri Arama Dizisi Şeması
Search Element JavaScript&#39;teki geri çağırmaların dizi şeması

Geri çağırmalar, arama öğesi başlatma ve arama süreçlerinin ayrıntılı kontrolünü destekler. Bunlar, global __gcse nesnesi aracılığıyla Search Element JavaScript'e kaydedilir. Geri Aramaları Kaydet, desteklenen tüm geri çağırmaların kaydını gösterir.

Geri çağırmaları kaydedin

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

Başlatma Geri çağırması

Arama Öğesi JavaScript'i, DOM'da arama öğeleri oluşturmadan önce başlatma geri çağırması başlatılır. parsetags öğesi __gcse politikasında explicit değerine ayarlanırsa Search Element JavaScript, Search Elements'i ilk kullanıma hazırlama geri çağırmasına bırakır (Geri Aramaları Kaydet bölümünde gösterildiği gibi). Bu, oluşturulacak öğeleri seçmek veya oluşturma öğelerini gerekli olana kadar ertelemek için kullanılabilir. Ayrıca, öğelerin özelliklerini geçersiz kılabilir. Örneğin, Kontrol Paneli veya HTML özellikleri aracılığıyla yapılandırılan bir arama kutusunu web araması için varsayılan olarak bir görsel arama kutusuna dönüştürebilir veya bir Programlanabilir Arama Motoru formu aracılığıyla gönderilen sorguların yalnızca bir arama sonucu öğesinde yürütüldüğünü belirtebilir. Demoya bakın.

Başlatma geri çağırmasının rolü, __gcse özelliğinin parsetags özelliğinin değeriyle kontrol edilir.

  • Değeri onload ise, Search Element JavaScript sayfadaki tüm Search Elements'ı otomatik olarak oluşturur. Başlatma geri çağırması çağrılmaya devam eder, ancak Arama Öğelerinin oluşturulmasından sorumlu değildir.
  • Değeri explicit ise Search Element JavaScript, Search Element'leri oluşturmaz. Geri çağırma, render() işlevini kullanarak seçici bir şekilde bunları oluşturabilir veya go() işleviyle tüm Arama Öğelerini oluşturabilir

Aşağıdaki kod, explicit ayrıştırma etiketi ve ilk kullanıma hazırlama geri çağırması kullanılarak arama sonuçlarında div ile birlikte arama kutusunun nasıl oluşturulacağını gösterir:

Başlatma Geri Arama Örneği

Arama Öğesi kodunu istediğimiz bir kimlik değerine sahip <div> öğesi eklememiz gerekiyor:

    <div id="test"></div>
Bu JavaScript'i <div> öğesinin sonuna ekleyin. Not: <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
};
öğesini tanımlamak için kullandığımız id; test

Arama Öğesini yüklemeye başlamak için bu HTML kodunu ekleyin. src yan tümcesindeki cx değerini kendi cx değerinizle değiştirin.

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

Geri Aramalarda Ara

Search Element JavaScript, arama kontrol akışında çalışan altı geri çağırmayı destekler. Arama geri aramaları çiftler halinde, bir web araması geri çağırması ve eşleşen görsel arama geri çağırması halinde gelir:

  • Arama Başlatılıyor
    • Görsel arama için
    • Web araması için
  • Sonuçlar hazır
    • Görsel arama için
    • Web araması için
  • Sonuçlar oluşturuldu
    • Görsel arama için
    • Web araması için

Başlatma geri çağırması gibi,arama geri çağırmaları da __gcse nesnesindeki girişler kullanılarak yapılandırılır. Bu durum, Search Element JavaScript'i başladığında gerçekleşir. Başlatma sonrasında __gcse üzerinde yapılan değişiklikler yoksayılır.

Bu geri çağırmalardan her biri, Search Element'e bağımsız değişken olarak gName iletilir. gname, bir sayfada birden fazla arama olduğunda yararlıdır. data-gname özelliğini kullanarak arama öğesine gname değerleri verin:

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

HTML bu adı tanımazsa Search Element JavaScript, HTML değiştirilene kadar tutarlı kalacak bir değer oluşturur.

Görsel/Web Araması Başlangıç Geri Araması

Arama öğesi geri çağırmaları, Search Element JavaScript'in sunucusundan arama sonuçları istemesinden hemen önce çağrılır. Örneğin, sorgudaki değişiklikleri kontrol etmek için günün yerel saati kullanılır.

searchStartingCallback(gname, query)
gname
Search Element'in tanımlayıcı dizesi
query
kullanıcı tarafından girilen değer (arama öğesi JavaScript'i tarafından değiştirilmiş olabilir).

Geri çağırma, bu arama için sorgu olarak kullanılması gereken değeri döndürür. Boş dize döndürürse dönüş değeri yoksayılır ve arayan, değiştirilmemiş sorgu kullanılır.

Alternatif olarak, geri çağırma işlevini __gcse nesnesine yerleştirebilir veya geri çağırmayı JavaScript ile nesneye dinamik olarak ekleyebilirsiniz:

window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
Aramayı Tekrar Başlatma Örneği

Örnek Arama geri çağırmayı başlatma bölümündeki geri çağırmayı başlatan örnek arama, sorguya günün saatine bağlı olarak morning veya afternoon ekler.

Arama Başlangıç Geri Arama Örneği
    const myWebSearchStartingCallback = (gname, query) => {
      const hour = new Date().getHours();
      return query + (hour < 12 ? ' morning' : ' afternoon');
    };
    window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;

Bu geri çağırmayı window.__gcse: olarak yükle

  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>

Görsel/Web Araması Sonuçları-Hazır Geri Arama

Bu geri çağırma işlemleri, Search Element JavaScript'in tanıtımları ve sonuçları oluşturmasından hemen önce çağrılır. Örnek bir kullanım alanı, promosyonları oluşturan ve normal özelleştirmeyle belirtilemeyen bir stilde gösterilen bir geri çağırmadır.

resultsReadyCallback(gname, query, promos, results, div)
gname
Search Element'in tanımlayıcı dizesi
query
bu sonuçları oluşturan sorgu
promos
Kullanıcının sorgusu için eşleşen promosyonlara karşılık gelen bir promosyon nesneleri dizisi. Promosyon nesnesi tanımına bakın.
results
bir dizi sonuç nesnesi. Sonuç nesne tanımına bakın.
div
DOM'da konumlandırılan bir HTML div ve Search Element normalde tanıtım ve arama sonuçları yerleştirir. Normalde Search Element JavaScript, bu div'in doldurulmasını işler. Ancak bu geri çağırma, sonuçların otomatik olarak oluşturulmasını durdurmayı ve sonuçları oluşturmak için bu div'i kullanmayı tercih edebilir.

Bu geri çağırma, bir true değeri döndürürse Search Element JavaScript, sayfa alt bilgisi çalışmasına atlar.

Örnek Sonuçlar Hazır Geri Arama

Örnek Sonuçlar İçin Hazır Geri Çağırmadaki resultsReady geri çağırma örneği, tanıtımların ve sonuçların varsayılan sunumunu çok basit bir değiştirmeyle geçersiz kılar.

Sonuç Geri Aramaya Hazır Örneği
    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;
    };

Bu geri çağırmayı window.__gcse: olarak yükle

  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>

Aramayı geri çağırmaya başladığınız gibi yukarıdaki de geri çağırmayı __gcse nesnesine yerleştirmenin birçok yolundan biridir.

Görsel/Web Arama Sonuçlarıyla Oluşturulan Geri Arama

Bu geri çağırma işlemleri, Search Element JavaScript'in sayfa altbilgisini oluşturmasından hemen önce çağrılır. Örnek kullanım alanları arasında, bunu kaydet onay kutusu veya otomatik olarak oluşturulmayan bilgiler gibi, arama öğesinin görüntülemediği bir sonuç içeriği ekleyen bir geri çağırma ya da daha fazla bilgi için düğmeleri ekleyen bir geri çağırma yer alır.

Sonuçlar hazır geri çağırma, sonuçlar için hazır geri çağırmanın promos ve results parametrelerindeki bilgilere ihtiyaç duyarsa bunlar arasında aşağıdaki gibi bilgi aktarabilir:

callback(gname, query, promoElts, resultElts);
gname
Search Element'in tanımlayıcı dizesi
query
arama dizesi.
promoElts
promosyonlar içeren bir DOM öğesi dizisi.
resultElts
Sonuçları içeren DOM öğelerinin bir dizisi.

İade değeri yok.

Örnek Sonuçlarla Geri Çağrı

Örnek Sonuçlarla Oluşturulan Geri Arama'daki resultsRendered geri çağırma örneği, her promosyona ve sonuca sahte bir Keep onay kutusu ekler.

Oluşturulan Sonuçlar İçin Geri Arama Örneği
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);
    }
  };

Bu geri çağırmayı window.__gcse: olarak yükle

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>

Sonuçlar oluşturulan geri çağırma, sonuçlar için hazır geri çağırmaya iletilen bilgilere ihtiyaç duyuyorsa bu verileri geri çağırmalar arasında aktarabilir. Aşağıdaki örnekte, richSnippet ile sonuçlar için hazır geri çağırma aralığından değer oluşturulmuş geri çağırmaya puan değeri iletmenin birçok yolundan biri gösterilmektedir.

Sonuçlarla İlgili Geri Çağrılar İçin Birlikte Çalışabilir Sonuçlar Örneği
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 kurulumu yaparken bu geri çağırma kodunu aşağıdaki gibi bir kod kullanarak yükleyin:
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>

Diğer Geri Arama Örnekleri

Diğer Geri Arama Örnekleri dokümanında ek geri çağırma örnekleri bulabilirsiniz.

Promosyon ve Sonuç Özellikleri

JSDoc gösterimini kullanarak bunlar promosyon ve sonuç nesnelerinin özellikleridir. Burada, bulunabilecek tüm özellikleri listeledik. Tesislerin çoğunun varlığı, promosyonun veya arama sonucunun ayrıntılarına bağlıdır.

Promosyon Özellikleri
{
  content: string,
  image: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  url: string,
  visibleUrl: string,
}
Sonuç Nesnesi Özellikleri
{
  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,
}

Sonuçlardaki richSnippet, bir nesne dizisinin gevşek türünü içerir. Bu dizideki girişlerin değerleri, her bir arama sonucu için web sayfasında bulunan yapılandırılmış veriler tarafından kontrol edilir. Örneğin, bir inceleme web sitesi, bu dizi girişini richSnippet öğesine ekleyen yapılandırılmış veriler içerebilir:

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

Programlanabilir Arama Öğesi Kontrol API'sı (V2)

google.search.cse.element nesnesi aşağıdaki statik işlevleri yayınlar:

İşlev Açıklama
.render(componentConfig, opt_componentConfig) Bir Arama Öğesi oluşturur.

Parametreler

Ad Açıklama
componentConfig Programlanabilir Arama Öğesi bileşeninin yapılandırması. Aşağıdakileri belirtir:
  • div (dize|Öğe): Programlanabilir Arama Öğesi'nin oluşturulacağı <div> veya div öğesinin id öğesi.
  • tag (dize): Oluşturulacak bileşenlerin türü. (opt_componentConfig sağlandığında tag özelliğinin değeri searchbox olmalıdır.) İzin verilen değerler:
    • search: Arama kutusu ve arama sonuçları birlikte gösterilir
    • searchbox: Programlanabilir Arama Öğesinin arama kutusu bileşeni.
    • searchbox-only: opt_componentConfig tarafından iki sütunlu düzende belirtilen bir arama sonuçları bloğuyla eşlenecek bağımsız bir arama kutusu.
    • searchresults-only: Bağımsız bir arama sonuçları bloğudur. Aramalar, bir URL'ye yerleşik bir sorgu parametresi veya programatik yürütme tarafından tetiklenir.
  • gname (dize): (İsteğe bağlı) Bu bileşen için benzersiz bir ad. Sağlanmazsa Programlanabilir Arama Motoru, otomatik olarak bir gname oluşturur.
  • attributes (Nesne): Anahtar:değer çifti biçimindeki isteğe bağlı özellikler. Desteklenen özellikler.
opt_componentConfig İsteğe bağlı. İkinci bileşen yapılandırması bağımsız değişkeni. searchresults bileşenini sağlamak için TWO_COLUMN modunda kullanılır. Aşağıdakileri belirtir:
  • div (dize): Öğenin oluşturulacağı <div> öğesinin veya div öğesinin id öğesi.
  • tag (dize): Oluşturulacak bileşenlerin türü. opt_componentConfig sağlandığında tag özelliğinin değeri searchresults olmalıdır. Ayrıca, componentConfig özelliğinin tag özelliğinin değeri searchbox olmalıdır.
  • gname (dize): (İsteğe bağlı) Bu bileşen için benzersiz bir ad. Sağlanmazsa Programlanabilir Arama Motoru, bu bileşen için otomatik olarak bir gname oluşturur. Bu değer belirtilirse componentConfig içindeki gname ile eşleşmelidir.
  • attributes (Nesne): Anahtar:değer çifti biçiminde isteğe bağlı özellikler. Desteklenen özellikler.
.go(opt_container) Belirtilen kapsayıcıdaki tüm Search Element etiketlerini/sınıflarını oluşturur.

Parametreler

Ad Açıklama
opt_container Oluşturulacak Arama Öğesi bileşenlerini içeren kapsayıcı. Kapsayıcının kimliğini (dize) veya öğenin kendisini belirtin. Atlanırsa sayfanın body etiketindeki tüm Programlanabilir Arama Öğesi bileşenleri oluşturulur.
.getElement(gname) Öğe nesnesini gname tarihine kadar alır. Bulamazsanız boş değeri döndürün.

Döndürülen element nesnesi aşağıdaki özelliklere sahiptir:

  • gname: Öğe nesnesinin adı. Sağlanmazsa Programlanabilir Arama Motoru, nesne için otomatik olarak bir gname oluşturur. Daha fazla bilgi edinin.
  • type: Öğenin türü.
  • uiOptions: Öğeyi oluşturmak için kullanılan son özellikler
  • execute - Functions(string): Programatik sorgu yürütür.
  • prefillQuery - Functions(string): Sorguyu yürütmeden, arama sorgusuyla birlikte bir sorgu dizesi doldurur.
  • getInputQuery - Functions(): Giriş kutusunda görüntülenen geçerli değeri alır.
  • clearAllResults - Functions(): Arama kutusu dışındaki her şeyi gizleyerek denetimi temizler.

Aşağıdaki kod, "element1" Arama Öğesinde "news" sorgusunu yürütür:

var element = google.search.cse.element.getElement('element1');
            element.execute('news');
.getAllElements() gname ile desteklenen, başarıyla oluşturulmuş tüm öğe nesnelerinin haritasını döndürür.