Programmable Search Element Control API

Programlanabilir Arama Motoru bileşenlerini (arama kutuları ve arama sonuçları sayfaları) ve diğer web uygulamalarınızda HTML biçimlendirmesini kullanarak değişiklikler yapabilirsiniz. Bu Programlanabilir Arama Motorları öğeleri, kullanıcı tarafından depolanan ayarlara dayalı olarak oluşturulan bileşenlerden oluşur. programlanabilir Arama sunucusu bilgilerini de görürsünüz.

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

Giriş

Bu belgede, Programlanabilir Arama Motoru eklemek için temel bir model sunulmaktadır öğelerinin açıklamalarıyla birlikte, açıklama yapılandırılabilir bileşenler ve esnek JavaScript API'si ile sunulur.

Kapsam

Bu dokümanda Programmable Search Engine Control API.

Tarayıcı uyumluluğu

Programlanabilir Arama Motoru tarafından desteklenen tarayıcıların listesi şurada bulunabilir: burada bulabilirsiniz.

Kitle

Bu doküman, Programlanabilir Google API'sini eklemek isteyen geliştiricilere yöneliktir. Sayfalarında arama işlevi.

Programlanabilir Arama Öğeleri

Sayfanıza Programlanabilir Arama Öğesi eklemek için HTML işaretlemesini kullanabilirsiniz. Her biri öğesi, en az bir bileşenden oluşur: bir arama kutusu, arama bloğu ya da her ikisini de seçebilirsiniz. Arama kutusu, aşağıdakilerden herhangi birinde kullanıcı girişini kabul eder yöntemler:

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

Ayrıca, arama sonucu bloku şu yöntemleri kullanabilirsiniz:

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

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

Web sayfanıza istediğiniz sayıda geçerli Arama Öğesi ekleyebilirsiniz. İki sütun için tüm gerekli bileşenleri (arama kutusu ve arama sonuç bloğu) mevcut olmalı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 Öğeleri'ni kullanarak farklı düzen seçenekleri oluşturun

Programlanabilir Arama Motoru kontrol panelinin Görünüm ve İzlenim sayfasında aşağıdaki düzen seçenekleri kullanılabilir. Programlanabilir Arama Öğeleri'ni kullanarak düzen seçenekleri oluşturma ile ilgili bazı genel yönergeleri burada bulabilirsiniz. Bu seçeneklerden herhangi birinin demosunu görmek için bağlantıyı tıklayın.

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 İzlenim sayfasına gidin.

Şurada oluşturulan yapılandırmaların üzerine yazmak için isteğe bağlı özellikleri kullanabilirsiniz: Programlanabilir Arama Motoru Kontrol panelinde oturum açın. Bu sayede, sayfaya özel arama deneyimi oluşturabilirsiniz. Örneğin, aşağıdaki kod, bir sonuç sayfası açan bir arama kutusu oluşturur (http://www.example.com?search=lady+gaga) bağlantısını tıklayarak yeni bir pencerede açabilirsiniz. The value of queryParameterName özelliği, kullanıcı sorgu dizesiyle birlikte için kullanılır.

queryParameterName özelliğinin data- önekine sahip olduğuna dikkat edin. Bu ön ek tüm özellikler için gereklidir.

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

Aşağıdaki gibi özellikleri etkinleştirmek için Programlanabilir Arama Motoru denetim masasını kullandıysanız otomatik tamamlama veya hassaslaştırmalar için özellikleri kullanabilirsiniz. bu özellikleri özelleştirebilirsiniz. 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:

• Geçmiş yönetimi etkin
• Görüntülenen maksimum otomatik tamamlama sayısı 5 olarak ayarlandı
• 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

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

Geri çağırma işlevleri

Geri çağırma işlevleri, arama öğesi başlatma ve arama işlemlerinin ayrıntılı kontrolünü destekler. Search Element JavaScript'e genel __gcse üzerinden kaydedilmişler. nesnesini tanımlayın. Geri Aramaları Kaydet, tüm geri çağırmaların kaydını kullanılabilir.

  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ı

İlk kullanıma hazırlama geri çağırması, Search Element JavaScript'i aramayı oluşturmadan önce çağrılır öğelerini DOM'de bulabilirsiniz. parsetags, şu aralıkta explicit değerine ayarlanırsa: __gcse için Arama Öğesi JavaScript'i, Arama Öğelerini oluşturmayı ilk kullanıma hazırlama geri çağırması (Geri Çağırmaları Kaydet'te gösterildiği gibi). Bu, oluşturulacak öğeleri seçmek veya oluşturma öğelerini, öğeler hazırlana kadar ertelemek için kullanılabilir. gerekir. Ayrıca, öğelerin özelliklerini geçersiz kılabilir; bir Kontrol Paneli veya HTML özellikleri aracılığıyla varsayılan olarak web'e ayarlanacak şekilde yapılandırılan arama kutusu arama kutusuna yazabilirsiniz veya Programlanabilir Arama Motoru formu aracılığıyla gönderilen sorguların bir arama sonuçları öğesi içinde yürütüldüğünden emin olun. Demoyu izleyin.

Başlatma geri çağırmasının rolü, parsetags değeri ile kontrol edilir. __gcse mülküdür.

• Değeri onload ise Arama Öğesi JavaScript, sayfadaki tüm Arama Öğelerini otomatik olarak oluşturur. İlk kullanıma hazırlama geri çağırması yine de çağrılır, ancak Arama Öğeleri'nin oluşturulmasından sorumlu değildir.
• Değeri explicit ise Arama Öğesi JavaScript'i oluşturulmaz Arama Öğeleri. Geri çağırma, bunları render() işlevi, veya tüm Arama Öğelerini go() işleviyle oluşturun

Aşağıdaki kodda, bir arama kutusunun, arama sonuçlarıyla birlikte div, explicit ayrıştırma geri çağırması ve ilk kullanıma hazırlama geri çağırması ile:

    <div id="test"></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
};

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

Geri Aramalarda Ara

Search Element JavaScript, JavaScript'te çalışan altı geri çağırmayı destekler. anlatacağım. Arama geri çağırmaları çiftler, bir web araması geri çağırma ve eşleşen resim arama geri çağırması gelir:

• Arama Başlıyor
  • Resim arama için
  • Web araması için
• Sonuçlar hazır
  • Resim arama için
  • Web araması için
• Sonuçlar oluşturuldu
  • Resim arama için
  • Web araması için

İlk kullanıma hazırlama geri çağırması gibi arama geri çağırmaları da __gcse nesnesindeki girişler kullanılarak yapılandırıldı. Bu işlem, Arama Öğesi JavaScript başlar. Başlatmadan sonra __gcse üzerinde yapılan değişiklikler yoksayılır.

Bu geri çağırmaların her biri gName Search Element'i (Arama Öğesi) bağımsız değişken olarak kullanın. gname, bir sayfada birden fazla arama olduğunda kullanışlıdır. Arama yapma öğesi, data-gname özelliğini kullanan bir gname değeri olarak değiştirilmelidir:

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

HTML, gname adını tanımlamazsa, Search Element JavaScript'i benzersiz bir tutarlılığını korur.

Görsel/Web Arama Başlangıcı Geri Çağırma

Arama başlatma geri çağırmaları, Search Element JavaScript isteklerinden hemen önce çağrılır sunucusundan gelen arama sonuçlarını gösterir. Örneğin, Arkadaş Bitkiler hizmetine örnek olarak günün yerel saatini sorgudaki değişiklikleri kontrol etmek için kullanılır.

searchStartingCallback(gname, query)

gname

Search Element'in tanımlayıcı dizesi

query

kullanıcı tarafından girilen değer (büyük olasılıkla arama tarafından değiştirilmiştir) öğesinin JavaScript'idir.)

Geri çağırma, bu arama için sorgu olarak kullanılması gereken değeri döndürür. Bir dize boşsa döndürülen değer yoksayılır ve çağrı yapan, değiştirilmemiş sorguyu kullanır.

Alternatif olarak, geri çağırma işlevini __gcse nesnesine veya geri çağırmayı JavaScript ile nesneye dinamik bir şekilde ekleyin:

window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};

Geri Çağırma Başlayan Örnek Arama

Şu süre içinde geri çağırma başlatan örnek arama: Geri Çağırma Başlayan Örnek Arama, morninglardan birini ekler veya günün saatine bağlı olarak sorguya afternoon ekleyin.

    const myWebSearchStartingCallback = (gname, query) => {
      const hour = new Date().getHours();
      return query + (hour < 12 ? ' morning' : ' afternoon');
    };
    window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;

Bu geri çağırmayı window.__gcse: uygulamasında yükleyin

  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 Arama Sonuçları-Hazır Geri Arama

Bu geri çağırma işlevleri, Search Element JavaScript'in tanıtımları oluşturmadan ve sonuç. Tanıtımlar oluşturan ve normal özelleştirmeyle belirtilemez.

resultsReadyCallback(gname, query, promos, results, div)

gname

Search Element'in tanımlayıcı dizesi

query

bu sonuçları üreten sorgu

promos

eşleşenlere karşılık gelen promosyon nesneleri dizisi promosyon kullanır. Promosyon nesnesi tanımına bakın.

results

sonuç nesneleri dizisidir. Bkz. sonuç nesnesi tanımı.

div

DOM'de, normal koşullarda Arama Öğesi'nin ve arama sonuçlarına yer verebilirsiniz. Normalde, Search Element JavaScript'in bu div öğesi dolduruluyor, ancak bu geri çağırma, sonuçların otomatik olarak oluşturulmasını durdurabilir. ve sonuçları oluşturmak için bu div öğesini kullanın.

ziyaret edin.

Bu geri çağırma bir true değeri döndürürse Arama Öğesi JavaScript'i kendi sayfa altbilgisi üzerinde çalışır.

Örnek Sonuçlar Hazır Geri Çağırma

Şu zaman dilimi içinde resultsReady geri çağırması: Örnek Sonuçlar Hazır Geri Çağırma, varsayılan sunuyu geçersiz kılar promosyonları ve sonuçları çok basit bir şekilde değiştirebilirsiniz.

    const myResultsReadyCallback = function(name, q, promos, results, resultsDiv) {
      const makePromoElt = (promo) => {
        const anchor = document.createElement('a');
        anchor.href = promo['url'];
        anchor.target = '_blank';
        anchor.classList.add('gs-title');
        const span = document.createElement('span');
        span.innerHTML = 'Promo: ' + promo['title'];
        anchor.appendChild(span);
        return anchor;
      };
      const makeResultParts = (result) => {
        const anchor = document.createElement('a');
        anchor.href = result['url'];
        anchor.target = '_blank';
        anchor.classList.add('gs_title');
        anchor.appendChild(document.createTextNode(result['visibleUrl']));
        const span = document.createElement('span');
        span.innerHTML = ' ' + result['title'];
        return [anchor, span];
      };

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

  window.__gcse || (window.__gcse = {});
    window.__gcse.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>

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

Bu geri çağırma işlevleri, Search Element JavaScript'in sayfayı oluşturmadan hemen önce çağrılır altbilgisi) ekleyin. Örnek kullanım alanları, arama sorgusunun öğesi, bunu kaydet onay kutusu veya yanlış olmayan bir bilgi gibi otomatik olarak oluşturulan veya daha fazla bilgi düğmeleri ekleyen bir geri çağırma türü olabilir.

Sonuçlar oluşturulan geri çağırma için promos ve results sonuçlar hazır geri çağırma parametrelerini ararsa bu ayar, ikisi arasında aşağıdaki gibi iletilebilir:

callback(gname, query, promoElts, resultElts);

gname

Search Element'in tanımlayıcı dizesi

query

arama dizesi

promoElts

promosyon içeren DOM öğeleri dizisi.

resultElts

sonuçları içeren DOM öğeleri dizisi.

Döndürülen değer yok.

Örnek Sonuçlar Oluşturulan Geri Çağırma

Şu zaman dilimi içinde resultsRendered geri çağırması: Örnek Sonuçlar Oluşturulan Geri Çağırma, sahte bir Keep ekler onay kutusunu işaretleyin.

myWebResultsRenderedCallback = function(name, q, promos, results) {
    for (const div of promos.concat(results)) {
      const innerDiv = document.createElement('div');
      innerDiv.appendChild(document.createTextNode('Keep: '));
      const checkBox = document.createElement('input');
      checkBox.type = 'checkbox';
      checkBox.name = 'save';
      innerDiv.appendChild(checkBox);
      div.insertAdjacentElement('afterbegin', innerDiv);
    }
  };

window.__gcse || (window.__gcse = {});
window.__gcse.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>

Geri çağırma oluşturulan sonuçlar için sonuçlara hazır geri çağırmaya iletilen bilgileri, bu verileri yardımcı olabilir. Aşağıdaki örnekte, Sonuçlar hazır geri çağrısından oluşturulan sonuçlara yapılan richSnippet geri arama.

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};
};

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>

Daha Fazla Geri Arama Örneği

Daha fazla geri çağırma örneği şurada bulunabilir: Diğer Geri Arama Örnekleri dokümanı.

Tanıtım ve Sonuç Özellikleri

JSDoc gösterimini kullanarak promotion ve sonuç nesneleri. Burada, mevcut olabilecek tüm özellikler listelenir. Çoğu özelliğin varlığı promosyonun veya arama sonucunun ayrıntılarına bağlıdır.

{
  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,
}

Sonuçlardaki richSnippet, serbest türde bir dizidir nesneler'i tıklayın. Bu dizideki girişlerin değerleri yapılandırılmış veri bulunur. Örneğin, bir inceleme web sitesi şu dizi girişini richSnippet konumuna ekleyen yapılandırılmış veriler:

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

Programmable Search Element Control API (V2)

google.search.cse.element nesnesi şunları yayınlar: statik işlevler:

var element = google.search.cse.element.getElement('element1');
            element.execute('news');