Halaman ini diterjemahkan oleh Cloud Translation API.

Programmable Search Element Control API

Anda dapat menyematkan komponen Programmable Search Engine (kotak penelusuran dan halaman hasil penelusuran) di halaman web Anda dan aplikasi web lainnya menggunakan markup HTML. Elemen Programmable Search Engine ini terdiri dari komponen yang dirender berdasarkan setelan yang disimpan oleh server Programmable Search, beserta setiap penyesuaian yang Anda buat.

Semua JavaScript dimuat secara asinkron, yang memungkinkan halaman Anda terus dimuat saat browser mengambil JavaScript Programmable Search Engine.

Pengantar

Dokumen ini menyediakan model dasar untuk menambahkan elemen Programmable Search Engine ke halaman web Anda, beserta penjelasan tentang komponen elemen yang dapat dikonfigurasi dan JavaScript API yang fleksibel.

Cakupan

Dokumen ini menjelaskan cara menggunakan fungsi dan properti khusus untuk Programmable Search Engine Control API.

Kompatibilitas browser

Daftar browser yang didukung oleh Programmable Search Engine dapat dilihat di sini.

Penonton

Dokumentasi ini ditujukan bagi developer yang ingin menambahkan fungsi Programmable Search Google ke halaman mereka.

Elemen Penelusuran yang Dapat Diprogram

Anda dapat menggunakan markup HTML untuk menambahkan Elemen Penelusuran yang Dapat Diprogram ke halaman Anda. Setiap elemen terdiri dari setidaknya satu komponen: kotak penelusuran, blok hasil penelusuran, atau keduanya. Kotak penelusuran menerima input pengguna dengan salah satu cara berikut:

Kueri penelusuran yang diketik di kolom input teks
String kueri yang disematkan di URL
Eksekusi terprogram

Selain itu, blok hasil penelusuran menerima input dengan cara berikut:

String kueri yang disematkan di URL
Eksekusi terprogram

Jenis Elemen Penelusuran yang Dapat Diprogram berikut tersedia:

Jenis elemen	Komponen	Deskripsi
standard	`<div class="gcse-search">`	Kotak penelusuran dan hasil penelusuran, yang ditampilkan dalam `<div>` yang sama.
dua kolom	`<div class="gcse-searchbox">` dan `<div class="gcse-searchresults">`	Tata letak dua kolom dengan hasil penelusuran di satu sisi dan kotak penelusuran di sisi lainnya. Jika berencana menyisipkan beberapa elemen dalam mode dua kolom di halaman web, Anda dapat menggunakan atribut `gname` untuk menyambungkan kotak penelusuran dengan blok hasil penelusuran.
khusus kotak penelusuran	`<div class="gcse-searchbox-only">`	Kotak penelusuran mandiri.
searchresults-saja	`<div class="gcse-searchresults-only">`	Blok hasil penelusuran yang berdiri sendiri.

Anda dapat menambahkan berapa pun Elemen Penelusuran yang valid ke halaman web. Untuk mode dua kolom, semua komponen yang diperlukan (kotak penelusuran dan blok hasil penelusuran) harus ada.

Berikut adalah contoh Elemen Penelusuran sederhana:

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

Buat opsi tata letak yang berbeda menggunakan Programmable Search Elements

Opsi tata letak berikut tersedia di halaman Tampilan dan Nuansa pada panel kontrol Programmable Search Engine. Berikut adalah beberapa panduan umum tentang cara menyusun opsi tata letak menggunakan Elemen Penelusuran yang Dapat Diprogram. Untuk melihat demo salah satu opsi tersebut, klik link.

Opsi	Komponen
Lebar penuh	`<div class="gcse-search">`
Rapat	`<div class="gcse-search">`
Dua kolom	`<div class="gcse-searchbox">`, `<div class="gcse-searchresults">`
Dua halaman Simpel Beberapa kotak penelusuran dan bagian hasil	`<div class="gcse-searchbox-only">` pada halaman pertama, `<div class="gcse-searchresults-only">` (atau komponen lainnya) pada halaman kedua.
Hasil saja Telusuri melalui URL Menelusuri melalui kotak penelusuran	`<div class="gcse-searchresults-only">`
Dihosting Google Hasil terbuka di jendela yang sama Hasil terbuka di jendela baru	`<div class="gcse-searchbox-only">`

Informasi selengkapnya tentang opsi tata letak.

Menyesuaikan Elemen Penelusuran yang Dapat Diprogram

Untuk menyesuaikan warna, font, atau gaya link, buka halaman Tampilan dan Nuansa pada mesin telusur yang dapat diprogram.

Anda dapat menggunakan atribut opsional untuk menimpa konfigurasi yang dibuat di panel kontrol Programmable Search Engine. Tindakan ini memungkinkan Anda membuat pengalaman penelusuran khusus halaman. Misalnya, kode berikut membuat kotak penelusuran yang membuka halaman hasil (http://www.example.com?search=lady+gaga) di jendela baru. Nilai atribut queryParameterName, beserta string kueri pengguna, digunakan untuk membuat URL hasil.

Perlu diperhatikan bahwa atribut queryParameterName diawali dengan data-. Awalan ini wajib diisi untuk semua atribut.

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

Jika telah menggunakan panel kontrol Programmable Search Engine untuk mengaktifkan fitur seperti pelengkapan otomatis atau penyempurnaan, Anda dapat menggunakan atribut untuk menyesuaikan fitur tersebut. Setiap penyesuaian yang Anda tentukan menggunakan atribut ini akan menggantikan setelan yang dibuat di panel kontrol. Contoh berikut membuat Elemen Penelusuran dua kolom dengan fitur berikut:

Pengelolaan histori diaktifkan
Jumlah maksimum pelengkapan otomatis yang ditampilkan ditetapkan ke 5
Penajaman ditampilkan sebagai link.

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

Atribut yang didukung

Atribut	Jenis	Deskripsi	Komponen
Umum
`gname`	String	(Opsional) Nama untuk objek Elemen Penelusuran. Nama digunakan untuk mengambil komponen terkait menurut nama, atau untuk menyambungkan komponen `searchbox` dengan komponen `searchresults`. Jika tidak disediakan, Programmable Search Engine akan otomatis membuat `gname`, berdasarkan urutan komponen di halaman web. Misalnya, `searchbox-only` tanpa nama pertama memiliki `gname` "searchbox-only0" dan yang kedua memiliki `gname` "seachbox-only1", dan seterusnya. Perhatikan bahwa `gname` yang dibuat secara otomatis untuk komponen dalam tata letak dua kolom akan menjadi `two-column`. Contoh berikut menggunakan gname `storesearch` untuk menautkan komponen `searchbox` dengan komponen `searchresults`: <div class="gcse-searchbox" data-gname="storesearch"></div> <div class="gcse-searchresults" data-gname="storesearch"></div> Saat mengambil objek, jika lebih dari satu komponen memiliki `gname` yang sama, Programmable Search Engine akan menggunakan komponen terakhir di halaman.	Mana saja
`autoSearchOnLoad`	Boolean	Menentukan apakah akan menjalankan penelusuran dengan kueri yang disematkan di URL halaman yang sedang dimuat atau tidak. Perhatikan bahwa string kueri harus ada di URL untuk menjalankan penelusuran otomatis. Default: `true`.	Mana saja
`enableHistory`	Boolean	Jika `true`, mengaktifkan pengelolaan histori untuk tombol Kembali dan Teruskan browser. Lihat demo.	searchbox khusus kotak penelusuran
`queryParameterName`	String	Nama parameter kueri—misalnya, `q` (default) atau `query`. URL ini akan disematkan di URL (misalnya, http://www.example.com?q=lady+gaga). Perhatikan bahwa menetapkan nama parameter kueri saja tidak akan memicu penelusuran otomatis saat dimuat. String kueri harus ada di URL untuk menjalankan penelusuran otomatis.	Mana saja
`resultsUrl`	URL	URL halaman hasil. (Defaultnya adalah halaman yang dihosting Google.)	khusus kotak penelusuran
`newWindow`	Boolean	Menentukan apakah halaman hasil dibuka di jendela baru. Default: `false`.	khusus kotak penelusuran
`ivt`	Boolean	Parameter ini memungkinkan Anda memberikan boolean yang memberi tahu Google bahwa Anda ingin mengizinkan iklan yang menggunakan penyimpanan lokal & cookie khusus traffic yang tidak valid pada traffic yang diberi izin dan tidak diberi izin. `true` Jika parameter ini tidak ada atau Anda menetapkannya ke "true", kami akan menetapkan cookie khusus traffic yang tidak valid dan menggunakan penyimpanan lokal hanya pada traffic yang diizinkan. `false` Jika Anda menetapkan parameter ini ke "false", kami akan menetapkan cookie khusus traffic yang tidak valid dan menggunakan penyimpanan lokal pada traffic yang diizinkan dan tidak diberi izin. Default: `false` Contoh penggunaan: `<div class="gcse-search" data-ivt="true"></div>`	hasil penelusuran searchresults-saja
`mobileLayout`	String	Menentukan apakah gaya tata letak seluler harus digunakan untuk perangkat seluler. `enabled` Hanya menggunakan tata letak seluler untuk perangkat seluler. `disabled` Tidak menggunakan tata letak seluler untuk perangkat apa pun. `forced` Menggunakan tata letak seluler untuk semua perangkat. Default: `enabled` Contoh penggunaan: `<div class="gcse-search" data-mobileLayout="disabled"></div>`	Mana saja
Pelengkapan Otomatis
`enableAutoComplete`	Boolean	Hanya tersedia jika pelengkapan otomatis telah diaktifkan di panel kontrol Programmable Search Engine. `true` mengaktifkan pelengkapan otomatis.	Mana saja
`autoCompleteMaxCompletions`	Bilangan Bulat	Jumlah maksimum pelengkapan otomatis yang akan ditampilkan.	searchbox khusus kotak penelusuran
`autoCompleteMaxPromotions`	Bilangan Bulat	Jumlah maksimum promosi yang akan ditampilkan di pelengkapan otomatis.	searchbox khusus kotak penelusuran
`autoCompleteValidLanguages`	String	Daftar bahasa yang dipisahkan koma yang pelengkapan otomatisnya harus diaktifkan. Bahasa yang didukung.	searchbox khusus kotak penelusuran
Penajaman
`defaultToRefinement`	String	Hanya tersedia jika penajaman telah dibuat di panel kontrol Programmable Search Engine. Menentukan label penajaman default yang akan ditampilkan.Catatan: Atribut ini tidak didukung untuk tata letak yang Dihosting Google.	Mana saja
`refinementStyle`	String	Nilai yang dapat diterima adalah `tab` (default) dan `link`. `link` hanya didukung jika penelusuran gambar dinonaktifkan, atau jika penelusuran gambar diaktifkan tetapi penelusuran web dinonaktifkan.	hasil penelusuran searchresults-saja
Penelusuran gambar
`enableImageSearch`	Boolean	Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine. Jika `true`, penelusuran gambar diaktifkan. Hasil gambar akan ditampilkan di tab terpisah.	hasil penelusuran searchresults-saja
`defaultToImageSearch`	Boolean	Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine. Jika `true`, halaman hasil penelusuran akan menampilkan hasil penelusuran gambar secara default. Hasil web akan tersedia di tab terpisah.	Mana saja
`imageSearchLayout`	String	Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine. Menentukan tata letak halaman hasil penelusuran gambar. Nilai yang dapat diterima adalah `classic`, `column`, atau `popup`.	hasil penelusuran searchresults-saja
`imageSearchResultSetSize`	Bilangan bulat, String	Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine. Menentukan ukuran maksimum hasil penelusuran yang disetel untuk penelusuran gambar. Misalnya, `large`, `small`, `filtered_cse`, `10`.	Mana saja
`image_as_filetype`	String	Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine. Membatasi hasil ke file dengan ekstensi tertentu. Ekstensi yang didukung adalah `jpg`, `gif`, `png`, `bmp`, `svg`, `webp`, `ico`, `raw`.	Mana saja
`image_as_oq`	String	Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine. Memfilter hasil penelusuran menggunakan Logika OR. Contoh penggunaan jika Anda menginginkan hasil penelusuran yang menyertakan "term1" atau "term2":`<div class="gcse-search" data-image_as_oq="term1 term2"></div>`	Mana saja
`image_as_rights`	String	Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine. Filter berdasarkan pemberian lisensi. Nilai yang didukung adalah `cc_publicdomain`, `cc_attribute`, `cc_sharealike`, `cc_noncommercial`, `cc_nonderived`, dan kombinasi keduanya. Lihat kombinasi standar.	Mana saja
`image_as_sitesearch`	String	Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine. Membatasi hasil pada halaman dari situs tertentu. Contoh penggunaan: `<div class="gcse-search" data-image_as_sitesearch="example.com"></div>`	Mana saja
`image_colortype`	String	Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine. Membatasi penelusuran pada gambar hitam dan putih (mono), hitam putih, atau berwarna. Nilai yang didukung adalah `mono`, `gray`, `color`.	Mana saja
`image_cr`	String	Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine. Membatasi hasil penelusuran pada dokumen yang berasal dari negara tertentu. Nilai yang didukung	Mana saja
`image_dominantcolor`	String	Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine. Membatasi penelusuran pada gambar dengan warna dominan tertentu. Nilai yang didukung adalah `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `purple`, `pink`, `white`, `gray`, `black`, `brown`.	Mana saja
`image_filter`	String	Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine. Pemfilteran otomatis hasil penelusuran. Nilai yang didukung: 0/1 Contoh penggunaan: `<div class="gcse-search" data-image_filter="0"></div>`	Mana saja
`image_gl`	String	Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine. Tingkatkan hasil penelusuran yang negara asalnya cocok dengan nilai parameter. Nilai yang didukung	Mana saja
`image_size`	String	Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine. Menampilkan gambar dengan ukuran tertentu, dengan ukuran dapat berupa salah satu dari: `icon`, `small`, `medium`, `large`, `xlarge`, `xxlarge`, atau `huge.`	Mana saja
`image_sort_by`	String	Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine. Urutkan hasil menggunakan tanggal atau konten terstruktur lainnya. Untuk mengurutkan berdasarkan relevansi, gunakan string kosong (image_sort_by=""). Contoh penggunaan: `<div class="gcse-search" data-image_sort_by="date"></div>`	Mana saja
`image_type`	String	Hanya tersedia jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine. Membatasi penelusuran ke gambar jenis tertentu. Nilai yang didukung adalah `clipart` (Gambar klip), `face` (Wajah orang), `lineart` (Gambar garis), `stock` (Foto stok), `photo` (Foto), dan `animated` (GIF Animasi).	Mana saja
Penelusuran web
`disableWebSearch`	Boolean	Jika `true`, akan menonaktifkan penelusuran web. Biasanya hanya digunakan jika penelusuran gambar telah diaktifkan di panel kontrol Programmable Search Engine.	hasil penelusuran searchresults-saja
`webSearchQueryAddition`	String	Istilah tambahan yang ditambahkan ke kueri penelusuran menggunakan logika OR. Contoh penggunaan: `<div class="gcse-search" data-webSearchQueryAddition="term1 term2"></div>`	Mana saja
`webSearchResultSetSize`	Bilangan bulat, String	Ukuran maksimum hasil yang ditetapkan. Berlaku untuk penelusuran gambar dan penelusuran web. Setelan defaultnya bergantung pada tata letak dan apakah Programmable Search Engine dikonfigurasi untuk menelusuri seluruh web atau hanya situs yang ditentukan. Nilai yang dapat diterima mencakup: Bilangan bulat dari 1-20 `small`: meminta kumpulan hasil kecil, biasanya 4 hasil per halaman. `large`: meminta kumpulan hasil besar, biasanya 8 hasil per halaman. `filtered_cse`: meminta maksimal 10 hasil per halaman, untuk maksimum 10 halaman atau 100 hasil.	Mana saja
`webSearchSafesearch`	String	Menentukan apakah SafeSearch diaktifkan untuk hasil penelusuran web. Nilai yang diterima adalah `off` dan `active`.	Mana saja
`as_filetype`	String	Membatasi hasil ke file dengan ekstensi tertentu. Daftar jenis file yang dapat diindeks oleh Google dapat ditemukan di Pusat Bantuan Search Console.	Mana saja
`as_oq`	String	Memfilter hasil penelusuran menggunakan Logika OR. Contoh penggunaan jika Anda menginginkan hasil penelusuran yang menyertakan "term1" atau "term2":`<div class="gcse-search" data-as_oq="term1 term2"></div>`	Mana saja
`as_rights`	String	Filter berdasarkan pemberian lisensi. Nilai yang didukung adalah `cc_publicdomain`, `cc_attribute`, `cc_sharealike`, `cc_noncommercial`, `cc_nonderived`, dan kombinasi keduanya. Lihat https://wiki.creativecommons.org/wiki/CC_Search_integration untuk mengetahui kombinasi standar.	Mana saja
`as_sitesearch`	String	Membatasi hasil pada halaman dari situs tertentu. Contoh penggunaan: `<div class="gcse-search" data-as_sitesearch="example.com"></div>`	Mana saja
`cr`	String	Membatasi hasil penelusuran pada dokumen yang berasal dari negara tertentu. Nilai yang didukung Contoh penggunaan: `<div class="gcse-search" data-cr="countryFR"></div>`	Mana saja
`filter`	String	Pemfilteran otomatis hasil penelusuran. Nilai yang didukung: 0/1 Contoh penggunaan: `<div class="gcse-search" data-filter="0"></div>`	Mana saja
`gl`	String	Tingkatkan hasil penelusuran yang negara asalnya cocok dengan nilai parameter. Ini hanya akan berfungsi bersama dengan setelan nilai bahasa. Nilai yang didukung Contoh penggunaan: `<div class="gcse-search" data-gl="fr"></div>`	Mana saja
`lr`	String	Membatasi hasil penelusuran pada dokumen yang ditulis dalam bahasa tertentu. Nilai yang didukung Contoh penggunaan: `<div class="gcse-search" data-lr="lang_fr"></div>`	Mana saja
`sort_by`	String	Urutkan hasil menggunakan tanggal atau konten terstruktur lainnya. Nilai atribut harus berupa salah satu opsi yang diberikan dalam setelan Pengurutan Hasil dari instance penelusuran yang dapat diprogram. Untuk mengurutkan berdasarkan relevansi, gunakan string kosong (sort_by=""). Contoh penggunaan: `<div class="gcse-search" data-sort_by="date"></div>`	Mana saja
Hasil penelusuran
`enableOrderBy`	Boolean	Memungkinkan pengurutan hasil menurut relevansi, tanggal, atau label.	Mana saja
`linkTarget`	String	Menetapkan target link. Default: `_blank`.	hasil penelusuran searchresults-saja
`noResultsString`	String	Menentukan teks default yang akan ditampilkan saat tidak ada hasil yang cocok dengan kueri. String hasil default dapat digunakan untuk menampilkan string yang dilokalkan dalam semua bahasa yang didukung, sedangkan string yang disesuaikan tidak.	hasil penelusuran searchresults-saja
`resultSetSize`	Bilangan bulat, String	Ukuran maksimum hasil yang ditetapkan. Misalnya, `large`, `small`, `filtered_cse`, `10`. Defaultnya bergantung pada tata letak dan apakah mesin dikonfigurasi untuk menelusuri seluruh web atau hanya situs yang ditentukan.	Mana saja
`safeSearch`	String	Menentukan apakah SafeSearch diaktifkan untuk penelusuran web dan gambar. Nilai yang diterima adalah `off` dan `active`.	Mana saja

Callback

Callback mendukung kontrol terperinci atas inisialisasi elemen penelusuran dan proses penelusuran. Objek tersebut terdaftar dengan JavaScript Elemen Penelusuran melalui objek __gcse global. Register Callback mengilustrasikan pendaftaran semua callback yang didukung.

Mendaftarkan Callback


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

Callback Inisialisasi

Callback inisialisasi dipanggil sebelum JavaScript Elemen Penelusuran merender elemen penelusuran di DOM. Jika parsetags ditetapkan ke explicit di __gcse, JavaScript Elemen Penelusuran akan meninggalkan rendering Elemen Penelusuran ke callback inisialisasi (seperti yang ditunjukkan di Callback Pendaftaran). Atribut ini dapat digunakan untuk memilih elemen yang akan dirender, atau untuk menunda elemen rendering hingga diperlukan. Atribut ini juga dapat mengganti atribut elemen. Misalnya, dapat mengubah kotak penelusuran yang dikonfigurasi melalui Panel Kontrol atau atribut HTML agar ditetapkan secara default ke penelusuran web ke kotak penelusuran gambar, atau menentukan bahwa kueri yang dikirim melalui formulir Programmable Search Engine dijalankan di elemen khusus searchresults. Lihat demo.

Peran callback inisialisasi dikontrol oleh nilai properti parsetags dari __gcse.

Jika nilainya onload, JavaScript Elemen Penelusuran akan otomatis merender semua Elemen Penelusuran di halaman. Callback inisialisasi tetap dipanggil, tetapi tidak bertanggung jawab untuk merender Elemen Penelusuran.
Jika nilainya adalah explicit, JavaScript Elemen Penelusuran tidak akan merender Elemen Penelusuran. Callback dapat merendernya secara selektif menggunakan fungsi render(), atau merender semua Elemen Penelusuran dengan fungsi go()

Kode berikut menunjukkan cara merender kotak penelusuran, bersama dengan hasil penelusuran, di div, menggunakan parameter penguraian explicit dan callback inisialisasi:

Catatan: Contoh yang dapat dieksekusi di halaman ini dijalankan di situs JSFiddle. Cari tombol jsfiddle,

, di kanan atas blok kode. Menekannya akan membuka halaman JSFiddle dengan contoh yang ditampilkan di panel HTML, JavaScript, css, dan run. Jendela akan dimulai dengan status "aktif", jadi cukup masukkan kueri di kotak penelusuran yang ditampilkan di panel run dan callback akan berjalan.

Contoh dalam dokumen ini dibagi menjadi beberapa bagian sesuai dengan jenis dan fungsinya, tetapi:

Semua bagian dari contoh dikirim ke JSFiddle bersama-sama
Setiap bagian dari contoh ini memiliki tombol JSFiddle. Mereka semua melakukan hal yang sama.

Karena ini adalah JSFiddle, Anda dapat bermain dengan kodenya. Perubahan yang dibuat di JSFiddle tidak disebarkan kembali ke dokumen ini.

Contoh Callback Inisialisasi

Kita perlu menyertakan <div> dengan nilai ID tempat kita ingin menggunakan kode Elemen Penelusuran:

    <div id="test"></div>

Tambahkan JavaScript ini setelah <div>. Perhatikan bahwa kode ini merujuk ke test, id yang kita gunakan untuk mengidentifikasi <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
};

Sertakan HTML ini untuk mulai memuat Elemen Penelusuran. Ganti nilai cx dalam klausa src dengan cx Anda sendiri.

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

Telusuri Callback

JavaScript Elemen Penelusuran mendukung enam callback yang beroperasi di alur kontrol penelusuran. Callback penelusuran tersedia secara berpasangan, callback penelusuran web dan callback penelusuran gambar yang cocok:

Mulai Penelusuran
- Untuk penelusuran gambar
- Untuk penelusuran web
Hasil siap
- Untuk penelusuran gambar
- Untuk penelusuran web
Hasil dirender
- Untuk penelusuran gambar
- Untuk penelusuran web

Seperti callback inisialisasi,callback penelusuran dikonfigurasi menggunakan entri dalam objek __gcse. Hal ini terjadi saat JavaScript Elemen Penelusuran dimulai. Modifikasi __gcse setelah startup akan diabaikan.

Masing-masing callback ini akan menerima gName untuk Elemen Penelusuran sebagai argumen. gname berguna saat halaman berisi lebih dari satu penelusuran. Berikan nilai gname pada elemen penelusuran menggunakan atribut data-gname:

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

Jika HTML tidak mengidentifikasi gname, JavaScript Elemen Penelusuran akan menghasilkan nilai yang akan tetap konsisten hingga HTML diubah.

Callback Memulai Penelusuran Gambar/Web

Callback awal penelusuran dipanggil tepat sebelum JavaScript Elemen Penelusuran meminta hasil penelusuran dari servernya. Contoh kasus penggunaan akan menggunakan waktu lokal untuk mengontrol perubahan pada kueri.

searchStartingCallback(gname, query)

gname: String identifikasi Elemen Penelusuran
query: nilai yang dimasukkan oleh pengguna (mungkin dimodifikasi oleh JavaScript elemen penelusuran.)

Callback menampilkan nilai yang harus digunakan sebagai kueri untuk penelusuran ini. Jika metode menampilkan string kosong, nilai yang ditampilkan akan diabaikan dan pemanggil menggunakan kueri yang tidak dimodifikasi.

Atau, Anda dapat menempatkan fungsi callback di objek __gcse atau secara dinamis menambahkan callback ke objek dengan JavaScript:

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

Contoh Callback Awal Penelusuran

Contoh callback awal penelusuran di Contoh Callback Awal Penelusuran menambahkan morning atau afternoon ke kueri, bergantung pada waktu.

Contoh Callback Awal Penelusuran

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

Instal callback ini di window.__gcse:

  window.__gcse || (window.__gcse = {});
    window.__gcse.searchCallbacks = {
      image: {
        starting: 'myImageSearchStartingCallbackName',
      },
      web: {
        starting: myWebSearchStartingCallback,
      },
    };

  <script
  async src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

Callback Siap Pakai Hasil Penelusuran Gambar/Web

Callback ini dipanggil tepat sebelum JavaScript Elemen Penelusuran merender promosi dan hasil. Contoh kasus penggunaan adalah callback yang merender promosi dan menghasilkan gaya yang tidak dapat ditentukan dengan penyesuaian normal.

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

gname: String identifikasi Elemen Penelusuran
query: yang menghasilkan hasil ini
promos: array objek promosi, yang sesuai dengan promosi yang cocok untuk kueri pengguna. Lihat definisi objek promosi.
results: array objek hasil. Lihat definisi objek hasil.
div: div HTML yang diposisikan di DOM tempat Elemen Penelusuran biasanya menempatkan promosi dan hasil penelusuran. Biasanya, JavaScript Elemen Penelusuran akan menangani pengisian div ini, tetapi callback ini dapat memilih untuk menghentikan rendering hasil otomatis dan menggunakan div ini untuk merender hasilnya sendiri.

Catatan: Callback dapat bebas mengubah nilai parameter. Perubahan pada gname, query, promos, dan results tidak memengaruhi perilaku JavaScript Elemen Penelusuran, tetapi jika callback menampilkan nilai benar (true), hierarki DOM yang di-root pada div akan ditampilkan.

Jika callback ini menampilkan nilai true, JavaScript Elemen Penelusuran akan melewati tugas footer halamannya.

Contoh Callback Siap Hasil

Contoh callback resultsReady di Example Results Ready Callback mengganti presentasi default promosi dan hasil dengan penggantian yang sangat sederhana.

Contoh Callback Siap Hasil

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

Instal callback ini di 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>

Seperti halnya callback awal penelusuran, hal di atas adalah salah satu dari banyak cara untuk menempatkan callback dalam objek __gcse.

Callback yang Dirender Hasil Penelusuran Gambar/Web

Callback ini dipanggil tepat sebelum JavaScript Elemen Penelusuran merender footer halaman. Contoh kasus penggunaan akan menyertakan callback yang menambahkan konten hasil yang tidak ditampilkan elemen penelusuran, seperti kotak centang simpan ini, atau informasi yang tidak otomatis dirender, atau callback yang menambahkan tombol untuk informasi selengkapnya.

Jika callback hasil yang dirender memerlukan informasi yang ada di parameter promos dan results dari callback hasil siap, callback dapat meneruskannya di antara keduanya, seperti ini:

callback(gname, query, promoElts, resultElts);

gname: String identifikasi Elemen Penelusuran
query: string penelusuran.
promoElts: array elemen DOM yang berisi promosi.
resultElts: array elemen DOM yang berisi hasil.

Tidak ada nilai yang ditampilkan.

Catatan: Mengubah nilai gname dan query tidak mengubah perilaku JavaScript Elemen Penelusuran, tetapi perubahan pada entri di promoElts dan resultElts merupakan perubahan pada DOM.

Catatan: Hanya elemen DOM yang dirender oleh JavaScript Elemen Penelusuran itu sendiri yang diteruskan ke callback resultsRendered.

Contoh Callback yang Dirender

Contoh callback resultsRendered di Example Results Rendered Callback menambahkan kotak centang Keep dummy ke setiap promosi dan hasil.

Contoh Callback yang Dirender Hasil

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

Instal callback ini di 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>

Jika callback hasil yang dirender memerlukan informasi yang diteruskan ke callback hasil siap, callback dapat meneruskan data tersebut di antara callback. Contoh berikut menunjukkan salah satu dari banyak cara untuk meneruskan nilai rating dari richSnippet dari callback hasil siap ke callback hasil yang dirender.

Contoh Callback Siap Hasil yang Bekerja sama dengan Callback yang Dirender Hasil

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

Instal callback ini menggunakan kode seperti ini saat menyiapkan __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>

Contoh Callback Lainnya

Contoh callback tambahan dapat ditemukan di dokumen Contoh Callback Lainnya.

Properti Promosi dan Hasil

Dengan menggunakan notasi JSDoc, ini adalah properti objek promotion dan result. Di sini, kita mencantumkan semua properti yang mungkin ada. Keberadaan banyak properti bergantung pada detail promosi atau hasil penelusuran.

Properti Promosi

{
  content: string,
  image: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  url: string,
  visibleUrl: string,
}

Properti Objek Hasil

{
  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 dalam hasil memiliki jenis array objek yang longgar. Nilai entri dalam array ini dikontrol oleh data terstruktur yang ditemukan di halaman web untuk setiap hasil penelusuran. Misalnya, situs ulasan mungkin menyertakan data terstruktur yang menambahkan entri array ini ke richSnippet:

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

Programmable Search Element Control API (V2)

Objek google.search.cse.element memublikasikan fungsi statis berikut:

Fungsi Deskripsi

.render(componentConfig, opt_componentConfig)

Merender Elemen Penelusuran.

Parameter

Nama Deskripsi

componentConfig

Konfigurasi untuk komponen Elemen Penelusuran yang Dapat Diprogram. Menentukan hal berikut:

div (string|Element): id dari elemen <div> atau div tempat Programmable Search Element akan dirender.
tag (string): Jenis komponen yang akan dirender. (Saat opt_componentConfig diberikan, nilai atribut tag harus searchbox.) Nilai yang diizinkan adalah:
- search: Kotak penelusuran dan hasil penelusuran, ditampilkan bersamaan
- searchbox: Komponen kotak penelusuran dari Elemen Penelusuran yang Dapat Diprogram.
- searchbox-only: Kotak penelusuran mandiri, yang akan disambungkan dengan blok hasil penelusuran yang ditentukan oleh opt_componentConfig dalam tata letak dua kolom.
- searchresults-only: Blok hasil penelusuran yang berdiri sendiri. Penelusuran dipicu oleh parameter kueri yang disematkan di URL, atau oleh eksekusi terprogram.
gname (string): (Opsional) Nama unik untuk komponen ini. Jika tidak disediakan, Programmable Search Engine akan otomatis membuat gname.
attributes (Objek): Atribut opsional dalam bentuk key:value pair. Atribut yang didukung.

opt_componentConfig

Opsional. Argumen konfigurasi komponen kedua. Digunakan dalam mode TWO_COLUMN untuk menyediakan komponen searchresults. Menentukan hal berikut:

div (string): id dari <div> atau elemen div tempat elemen akan dirender.
tag (string): Jenis komponen yang akan dirender. Jika opt_componentConfig diberikan, nilai atribut tag harus searchresults. Selain itu, nilai atribut tag dari componentConfig harus searchbox.
gname (string): (Opsional) Nama unik untuk komponen ini. Jika tidak disediakan, Programmable Search Engine akan otomatis membuat gname untuk komponen ini. Jika disediakan, nilai tersebut harus cocok dengan gname di componentConfig.
attributes (Objek): Atribut opsional dalam bentuk pasangan nilai kunci. Atribut yang didukung.

.go(opt_container)

Merender semua tag/class Elemen Penelusuran dalam penampung yang ditentukan.

Parameter

Nama	Deskripsi
`opt_container`	Penampung yang berisi komponen Elemen Penelusuran yang akan dirender. Tentukan ID penampung (string) atau elemen itu sendiri. Jika dihilangkan, semua komponen Elemen Penelusuran yang Dapat Diprogram di dalam tag `body` halaman akan dirender.

.getElement(gname)

Mendapatkan objek elemen sebesar gname. Jika tidak ditemukan, tampilkan null.

Objek element yang ditampilkan memiliki atribut berikut:

gname: Nama objek elemen. Jika tidak disediakan, Programmable Search Engine akan otomatis membuat gname untuk objek ini. Informasi selengkapnya.
type: Jenis elemen.
uiOptions: Atribut akhir yang digunakan untuk merender elemen.
execute - fungsi(string): Menjalankan kueri terprogram.
prefillQuery - function(string): Mengisi kotak penelusuran dengan string kueri tanpa mengeksekusi kueri.
getInputQuery - function(): Mendapatkan nilai saat ini yang ditampilkan di kotak input.
clearAllResults - function(): Menghapus kontrol dengan menyembunyikan semua, kecuali kotak penelusuran, jika ada.

Kode berikut mengeksekusi kueri "news" dalam Elemen Penelusuran "element1":

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

.getAllElements() Menampilkan peta semua objek elemen yang berhasil dibuat, dengan kunci gname.