Programmable Search Element Control API

您可以將程式化搜尋引擎元件 (搜尋框和搜尋結果網頁) 嵌入 協助您快速管理網頁和其他網頁應用程式這些程式化搜尋引擎 元素是由元件組成的元件,系統會根據 程式化搜尋伺服器,以及您所做的任何自訂變更。

所有 JavaScript 都會以非同步方式載入,讓網頁 瀏覽器擷取程式化搜尋引擎 JavaScript 時繼續載入。

簡介

本文件提供基本模型,說明如何新增程式化搜尋引擎 這些元素,並附上該元素的 可設定元件和彈性的 JavaScript API。

範圍

本文件說明如何使用特定的函式與屬性 程式化搜尋引擎控制 API

瀏覽器相容性

程式化搜尋引擎支援的瀏覽器清單 請按這裡

觀眾

本文件可協助開發人員新增 Google 程式化功能 網頁搜尋功能。

程式化搜尋元素

您可以使用 HTML 標記將程式化搜尋元素新增至您的網頁。每項 元素至少包含一個元件:搜尋框、搜尋區塊 或兩者皆是搜尋框接受使用者輸入下列任一內容 方式:

  • 在文字輸入欄位中輸入的搜尋查詢
  • 網址內嵌的查詢字串
  • 透過程式執行

此外,搜尋結果區塊接受輸入 方法如下:

  • 網址內嵌的查詢字串
  • 透過程式執行

可用的程式化搜尋元素類型如下:

元素類型 元件 說明
standard <div class="gcse-search"> 搜尋框和搜尋結果 在同一個 <div> 中顯示。
兩欄 <div class="gcse-searchbox">」和「<div class="gcse-searchresults"> 雙欄版面配置,其中一邊顯示搜尋結果和搜尋框 另一個。如果您打算在兩欄模式中插入多個元素 您可以運用 gname 屬性將 內含一個搜尋結果區塊的搜尋框
僅限搜尋框 <div class="gcse-searchbox-only"> 獨立的搜尋框。
searchresults-only <div class="gcse-searchresults-only"> 獨立的搜尋結果區塊,

您可以為網頁新增任意數量的有效搜尋元素。兩欄式 模式,所有必要元件 (搜尋框與搜尋工具) 結果區塊)。

以下是簡易搜尋元素範例:

<!-- Put the following javascript before the closing </head> tag
and replace 123456 with your own Programmable Search Engine ID. -->
<script async src="https://cse.google.com/cse.js?cx=123456"></script>

<!-- Place this tag where you want both of the search box and the search results to render -->
<div class="gcse-search"></div>

使用程式化搜尋元素撰寫不同的版面配置選項

在「程式化搜尋引擎」控制台的「外觀和風格」頁面中,我們提供下列版面配置選項。以下為使用程式化搜尋元素撰寫版面配置選項的一般指南。如想查看這些選項的示範,請按一下連結。

選項 元件
全形 <div class="gcse-search">
小巧 <div class="gcse-search">
雙欄 <div class="gcse-searchbox"><div class="gcse-searchresults">
兩頁 第一頁的 <div class="gcse-searchbox-only">,第二個頁面 <div class="gcse-searchresults-only"> (或其他元件)。
只顯示結果 <div class="gcse-searchresults-only">
Google 代管 <div class="gcse-searchbox-only">

進一步瞭解版面配置選項

自訂程式化搜尋元素

如要自訂顏色、字型或連結樣式,請前往程式化搜尋引擎的「外觀和風格」頁面。

您可以使用選用屬性覆寫在 程式化搜尋引擎 控制台:可用來打造特定網頁的搜尋體驗。 例如,以下程式碼會建立一個搜尋框,用來開啟結果網頁 (http://www.example.com?search=lady+gaga)。如果 queryParameterName 屬性和使用者查詢字串為 來產生結果網址

請注意,queryParameterName 屬性的前置字元為 data-。 所有屬性都必須使用這個前置字串。

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

如果您已使用程式化搜尋引擎控制台啟用下列功能: 自動完成修正,即可使用屬性來 自訂這些功能您透過這些屬性指定的所有自訂項目 會覆寫您在控制台中所做的設定。以下範例會建立 具有下列功能的兩欄「搜尋元素」:

  • 記錄管理功能已啟用
  • 顯示的自動完成建議數量上限為 5
  • 系統會以連結的形式顯示分類標籤

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

支援的屬性

屬性 類型 說明 元件
一般
gname 字串 (選用) 「搜尋元素」物件的名稱。名稱用於擷取 指定相關聯的元件,或將 searchbox 與 搭配 searchresults 元件使用如果沒有提供 程式化搜尋引擎會根據gname 網頁元件的順序例如 searchbox-only 具有gname「searchbox-only0」 第二個則含有 gname「seachbox-only1」,以此類推 請注意,系統為以下項目自動產生的 gname 元件: 雙欄版面配置將為 two-column。以下範例 使用 Gname storesearch 連結 searchbox 元件為 searchresults 元件:
<div class="gcse-searchbox" data-gname="storesearch"></div>
<div class="gcse-searchresults" data-gname="storesearch"></div>

擷取物件時,如果多個元件具有相同 gname,程式化搜尋引擎會使用 頁面。

不限
autoSearchOnLoad 布林值 指定是否要透過網址內嵌的查詢執行搜尋 載入網頁的路徑請注意,網址必須包含查詢字串 來執行自動搜尋。預設值:true 不限
enableHistory 布林值 如果設為 true,系統就會啟用瀏覽器的「返回」管理功能 以及「前進」按鈕查看示範影片

搜尋框

僅限搜尋框

queryParameterName 字串 查詢參數名稱:例如 q (預設) 或 query。這將嵌入網址中 (例如 http://www.example.com?q=lady+gaga)。請注意,指定 查詢參數名稱並不會在載入時觸發自動搜尋。查詢 字串必須包含才能執行自動搜尋。 不限
resultsUrl 網址 結果網頁的網址。(預設為 Google 代管的網頁)。 僅限搜尋框
newWindow 布林值 指定結果網頁是否在新視窗中開啟。 預設值:false 僅限搜尋框
ivt 布林值

這個參數可讓您提供布林值,告知 Google 您要允許存取 廣告使用僅限無效流量的 Cookie,且本機儲存空間 未同意使用者的流量

true如果這個參數不存在,或是您設為「true」將設定 偵測無效流量專用的 Cookie,並只對同意的流量使用本機儲存空間。

false 如果您將這個參數設為「false」我們要設定 ,針對已同意和未同意的流量,使用本機儲存空間。

預設:false

使用範例:<div class="gcse-search" data-ivt="true"></div>

搜尋結果

searchresults-only

mobileLayout 字串

指定是否應為行動裝置使用行動裝置版面配置樣式。

enabled 只針對行動裝置使用行動裝置版面配置。

disabled 未使用任何裝置的行動裝置版面配置。

forced 為所有裝置採用行動裝置版面配置。

預設:enabled

使用範例:<div class="gcse-search" data-mobileLayout="disabled"></div>

不限
自動完成
enableAutoComplete 布林值 您必須先在「程式化搜尋引擎」控制台中啟用自動完成功能,才能使用這項功能。 true 會啟用自動完成功能。 不限
autoCompleteMaxCompletions 整數 可顯示的自動完成建議數量上限。

搜尋框

僅限搜尋框

autoCompleteMaxPromotions 整數 自動完成中可顯示的促銷活動數量上限。

搜尋框

僅限搜尋框

autoCompleteValidLanguages 字串 應輸入的自動完成語言清單 支援的語言。

搜尋框

僅限搜尋框

分類標籤
defaultToRefinement 字串 只有在 程式化搜尋引擎控制台。將預設修正標籤指定為 display.注意:Google 代管版面配置不支援這個屬性。 不限
refinementStyle 字串 可接受的值為 tab (預設) 和 link。 只有在停用圖片搜尋功能或圖片搜尋功能停用的情況下,系統才會支援「link」 已啟用圖片搜尋功能,但網路搜尋已停用。

搜尋結果

searchresults-only

圖片搜尋
enableImageSearch 布林值 僅適用於 已在「程式化搜尋引擎」控制台中啟用圖片搜尋

如果設為 true,則啟用圖片搜尋功能。圖片搜尋結果會顯示在 。

搜尋結果

searchresults-only

defaultToImageSearch 布林值 僅適用於 已在「程式化搜尋引擎」控制台中啟用圖片搜尋

如果設為 true,搜尋結果網頁會顯示圖片搜尋結果 根據預設。網頁搜尋結果會在另一個分頁中顯示。

不限
imageSearchLayout 字串 僅適用於 已在「程式化搜尋引擎」控制台中啟用圖片搜尋

指定圖片搜尋結果網頁的版面配置。可接受的值 為 classiccolumnpopup

搜尋結果

searchresults-only

imageSearchResultSetSize 整數、字串 僅適用於 已在「程式化搜尋引擎」控制台中啟用圖片搜尋

指定圖片搜尋的搜尋結果組大小上限。 例如 largesmallfiltered_cse10

不限
image_as_filetype 字串 僅適用於 已在「程式化搜尋引擎」控制台中啟用圖片搜尋

限制系統顯示特定擴充功能檔案的結果。

支援的擴充功能包括 jpggifpngbmpsvgwebpicoraw

不限

image_as_oq 字串 僅適用於 已在「程式化搜尋引擎」控制台中啟用圖片搜尋

使用邏輯 OR 篩選搜尋結果。

希望搜尋結果包含「term1」的使用情況範例或「term2」:<div class="gcse-search" data-image_as_oq="term1 term2"></div>

不限

image_as_rights 字串 僅適用於 已在「程式化搜尋引擎」控制台中啟用圖片搜尋

依授權篩選。

支援的值為 cc_publicdomaincc_attributecc_sharealikecc_noncommercialcc_nonderived,以及這些項目的組合。

請參閱一般組合的相關說明。

不限

image_as_sitesearch 字串 僅適用於 已在「程式化搜尋引擎」控制台中啟用圖片搜尋

將搜尋結果限制為特定網站的網頁。

使用範例:<div class="gcse-search" data-image_as_sitesearch="example.com"></div>

不限

image_colortype 字串 僅適用於 已在「程式化搜尋引擎」控制台中啟用圖片搜尋

限制搜尋範圍為黑白 (單聲道)、灰階或彩色圖片。支援的值為 monograycolor

不限

image_cr 字串 僅適用於 已在「程式化搜尋引擎」控制台中啟用圖片搜尋

限制只顯示來自特定國家/地區的文件搜尋結果。

支援的值

不限

image_dominantcolor 字串 僅適用於 已在「程式化搜尋引擎」控制台中啟用圖片搜尋

限制搜尋特定主要顏色的圖片。 支援的值為 redorangeyellowgreentealbluepurplepinkwhitegrayblackbrown

不限

image_filter 字串 僅適用於 已在「程式化搜尋引擎」控制台中啟用圖片搜尋

自動篩選搜尋結果。

支援的值:0/1

使用範例:<div class="gcse-search" data-image_filter="0"></div>

不限

image_gl 字串 僅適用於 已在「程式化搜尋引擎」控制台中啟用圖片搜尋。 提升來源國家/地區與參數值相符的搜尋結果。

支援的值

不限

image_size 字串 僅適用於 已在「程式化搜尋引擎」控制台中啟用圖片搜尋

傳回指定大小的圖片,其中大小可以是下列任一值:iconsmallmediumlargexlargexxlargehuge.

不限

image_sort_by 字串 僅適用於 已在「程式化搜尋引擎」控制台中啟用圖片搜尋

使用日期或其他結構化內容將搜尋結果排序。

如要按關聯性排序,請使用空白字串 (image_sort_by=")。

使用範例:<div class="gcse-search" data-image_sort_by="date"></div>

不限

image_type 字串 僅適用於 已在「程式化搜尋引擎」控制台中啟用圖片搜尋

限制搜尋特定類型的圖片。 支援的值為 clipart (插圖)、face (人物臉孔)、lineart (線條繪圖)、stock (圖庫相片)、photo (相片) 和 animated (GIF 動畫)。

不限

網頁搜尋
disableWebSearch 布林值 如果設為 true,系統會停用網頁搜尋。通常僅適用於 已在「程式化搜尋引擎」控制台中啟用圖片搜尋

搜尋結果

searchresults-only

webSearchQueryAddition 字串 使用邏輯「OR」在搜尋查詢中加入額外字詞。

使用範例:<div class="gcse-search" data-webSearchQueryAddition="term1 term2"></div>

不限
webSearchResultSetSize 整數、字串 結果集的大小上限。套用至: 包括圖片搜尋和網頁搜尋預設值取決於版面配置和 程式化搜尋引擎是設為搜尋整個網路 。可接受的值包括:
  • 介於 1 至 20 的整數
  • small:要求較小的結果集,通常有 4 個結果 每頁。
  • large:要求大型結果集 (通常為 8 個) 筆結果。
  • filtered_cse:要求每頁最多 10 筆結果, 最多 10 頁或 100 筆結果。
不限
webSearchSafesearch 字串 說明是否 SafeSearch為 啟用網頁搜尋結果的功能。可接受的值為 offactive 不限
as_filetype 字串 限制系統顯示特定擴充功能檔案的結果。如要查看 Google 可建立索引的檔案類型清單,請前往 Search Console 說明中心

不限

as_oq 字串 使用邏輯 OR 篩選搜尋結果。

希望搜尋結果包含「term1」的使用情況範例或「term2」:<div class="gcse-search" data-as_oq="term1 term2"></div>

不限
as_rights 字串 依授權篩選。

支援的值為 cc_publicdomaincc_attributecc_sharealikecc_noncommercialcc_nonderived,以及這些項目的組合。

如要瞭解典型組合,請參閱 https://wiki.creativecommons.org/wiki/CC_Search_integration

不限

as_sitesearch 字串 將搜尋結果限制為特定網站的網頁。

使用範例:<div class="gcse-search" data-as_sitesearch="example.com"></div>

不限
cr 字串 限制只顯示來自特定國家/地區的文件搜尋結果。

支援的值

使用範例:<div class="gcse-search" data-cr="countryFR"></div>

不限
filter 字串 自動篩選搜尋結果。

支援的值:0/1

使用範例:<div class="gcse-search" data-filter="0"></div>

不限
gl 字串 提升來源國家/地區與參數值相符的搜尋結果。

這個屬性僅適用於語言值設定。

支援的值

使用範例:<div class="gcse-search" data-gl="fr"></div>

不限
lr 字串 限制顯示特定語言的文件搜尋結果。

支援的值

使用範例:<div class="gcse-search" data-lr="lang_fr"></div>

不限
sort_by 字串 使用日期或其他結構化內容將搜尋結果排序。在程式化搜尋等程式化的搜尋介面中,屬性值必須是「結果排序」設定中提供的其中一個選項。

如要按關聯性排序,請使用空白字串 (sort_by=")。

使用範例:<div class="gcse-search" data-sort_by="date"></div>

不限
搜尋結果
enableOrderBy 布林值 啟用可按照關聯性、日期或標籤排序結果的功能。 不限
linkTarget 字串 設定連結目標。預設值:_blank

搜尋結果

searchresults-only

noResultsString 字串 指定沒有與查詢相符的結果時顯示的預設文字。 預設結果字串可用來在 而自訂語言則不會。

搜尋結果

searchresults-only

resultSetSize 整數、字串 結果集的大小上限。例如 large smallfiltered_cse10。 預設選項取決於版面配置,以及引擎是否設為搜尋 整個網路或僅限指定的網站 不限
safeSearch 字串 指定是否 網頁和圖片搜尋皆已啟用安全搜尋。可接受的值為 offactive 不限

回呼

回呼序列圖表
搜尋元素 JavaScript 的回呼序列圖表

回呼支援詳細控制搜尋元素初始化和搜尋程序。 已透過全域 __gcse 向搜尋元素 JavaScript 註冊 物件。註冊回呼會列出所有 支援的回呼。

註冊回呼

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

初始化回呼

系統會在 Search Element JavaScript 轉譯搜尋之前叫用初始化回呼 元素。如果將 parsetags 設為 explicit __gcse,則搜尋元素 JavaScript 會將搜尋元素保留在 初始化回呼 (如「註冊回呼」中所示)。 這可用於選取要算繪的元素,或延後算繪元素至 。也可以覆寫元素的屬性;舉例來說,它可以 透過「控制台」或「HTML 屬性」設定的搜尋框預設為網路 搜尋圖片搜尋框,或是指定透過程式化搜尋引擎表單提交的查詢, 此物件會在僅限搜尋結果的元素中執行。 查看示範影片。

初始化回呼的角色是由 parsetags 的值控管 是 __gcse 之屬性。

  • 如果值為 onload,則搜尋元素 JavaScript 會自動轉譯網頁上的所有搜尋元素。初始化回呼是 ,但無法算繪搜尋元素。
  • 如果值為 explicit,則搜尋元素 JavaScript 不會轉譯。 搜尋元素。回呼可以使用 render() 函式, 或使用 go() 函式呈現所有搜尋元素

下列程式碼示範瞭如何在 div,使用 explicit 剖析標記和初始化回呼:

,瞭解如何調查及移除這項存取權。
初始化回呼範例

我們需要加入具有 ID 值的 <div> 請填入「搜尋元素」程式碼的位置:

    <div id="test"></div>
<div> 後方加上此 JavaScript。請注意 參照testid我們用來識別 <div>
const myInitCallback = function() {
  if (document.readyState == 'complete') {
    // Document is ready when Search Element is initialized.
    // Render an element with both search box and search results in div with id 'test'.
    google.search.cse.element.render(
        {
          div: "test",
          tag: 'search'
         });
  } else {
    // Document is not ready yet, when Search Element is initialized.
    google.setOnLoadCallback(function() {
       // Render an element with both search box and search results in div with id 'test'.
        google.search.cse.element.render(
            {
              div: "test",
              tag: 'search'
            });
    }, true);
  }
};

// Insert it before the Search Element code snippet so the global properties like parsetags and callback
// are available when cse.js runs.
window.__gcse = {
  parsetags: 'explicit',
  initializationCallback: myInitCallback
};

加入此 HTML 以開始載入搜尋元素。替換範本中的 cx 值, src 子句搭配您自己的 cx

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

搜尋回呼

搜尋元素 JavaScript 支援六個在 搜尋控制流程 搜尋回呼分為兩組,網頁搜尋回呼和相符的圖片搜尋回呼:

  • 正在開始搜尋
    • 圖片搜尋
    • 網頁搜尋
  • 結果已出爐
    • 圖片搜尋
    • 網頁搜尋
  • 已轉譯結果
    • 圖片搜尋
    • 網頁搜尋

初始化回呼一樣,搜尋回呼會 使用 __gcse 物件中的項目進行設定。這會以 Search Element 形式呈現 JavaScript 會開始。系統會忽略啟動後對 __gcse 的修改。

每個回呼都會傳遞 gName 做為引數 如果網頁含有多筆搜尋,gname 就非常實用。搜尋一下 使用 data-gname 屬性建立 gname 值的元素:

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

如果 HTML 沒有識別 gname,搜尋元素 JavaScript 就會產生一個 直到 HTML 修改過為止。

圖片/網頁搜尋 - 啟動回呼

搜尋起始回呼會在 Search Element JavaScript 要求之前立即叫用 傳回的結果。我們舉例是採用 當地時間 對查詢所做的變更。

searchStartingCallback(gname, query)
gname
搜尋元素的識別字串
query
使用者輸入的值 (可透過搜尋修改) 元素 JavaScript)。

回呼會傳回應做為此搜尋查詢的值。如果傳回 空白字串,系統會忽略傳回值,而呼叫端會使用未修改的查詢。

或者,您也可以將回呼函式放入 __gcse 物件,或 使用 JavaScript 動態新增回呼至物件:

window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
搜尋啟動回呼的範例

以下搜尋啟動回呼範例: 範例搜尋起始回呼會新增 morningafternoon 觸發查詢。

搜尋起始回呼範例
    const myWebSearchStartingCallback = (gname, query) => {
      const hour = new Date().getHours();
      return query + (hour < 12 ? ' morning' : ' afternoon');
    };
    window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;

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>

圖片/網頁搜尋結果-準備回呼

這些回呼會在 Search Element JavaScript 轉譯置頂查詢與 也就是預測結果用途範例中的回呼會轉譯促銷活動,並使樣式呈現在 無法以一般自訂方式指定。

resultsReadyCallback(gname, query, promos, results, div)
gname
搜尋元素的識別字串
query
會產生這些結果的查詢
promos
促銷物件的陣列,這些物件會對應到相符的結果 促銷活動 使用者查詢的內容請參閱促銷活動物件定義
results
結果物件的陣列。詳情請參閱 結果物件定義
div
在 DOM 中放置搜尋元素一般的 HTML div 刊登促銷活動和搜尋結果。一般來說,搜尋元素 JavaScript 會處理 填入這個 div,但這個回呼可能會選擇停止自動顯示結果 然後使用這個 div 轉譯結果。
,瞭解如何調查及移除這項存取權。

如果這個回呼傳回 true 值,Search Element JavaScript 會略過該值 頁尾就是這樣

結果可回撥的回呼範例

resultsReady 回呼範例 Results Ready 回呼會覆寫預設呈現方式 透過非常簡單的取代方式,找出宣傳和結果。

結果就緒的回呼範例
    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 = {});
    window.__gcse.searchCallbacks = {
      web: {
        ready: myResultsReadyCallback,
      },
    };
  <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

與搜尋起始回呼一樣,上述是將回呼加入回呼的多種方式之一 __gcse 物件。

圖片/網頁搜尋結果-顯示的回呼

系統會在搜尋元素 JavaScript 轉譯網頁前,立即叫用這些回呼 頁尾。用途範例包括回呼,將結果內容新增 元素不會顯示,例如 [儲存此核取方塊] 核取方塊或 ,或是加入更多資訊按鈕的回呼。

如果結果轉譯的回呼需要 promos 中的資訊 results 結果準備就緒回呼參數,即可在這些回呼之間傳遞,如下所示:

callback(gname, query, promoElts, resultElts);
gname
搜尋元素的識別字串
query
搜尋字串。
promoElts
包含促銷活動的 DOM 元素陣列。
resultElts
包含結果的 DOM 元素陣列。

無傳回值。

轉譯回呼的範例

resultsRendered 回呼範例 「算繪回呼範例」新增了虛擬 Keep 核取方塊。

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

window.__gcse: 中安裝這個回呼

window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    rendered: 'myWebResultsRenderedCallback',
  },
};
  <script async
    src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

如果結果轉譯回呼需要 傳遞至結果就緒回呼的資訊,便可在 回呼。以下範例說明傳送評分值的多種方式之一 來自結果準備就緒回呼richSnippet已轉譯的結果 回呼。

,瞭解如何調查及移除這項存取權。
具備顯示結果回呼的結果準備回呼範例
const makeTwoPartCallback = () => {
  let saveForRenderCallback;
  const readyCallback = (name, q, promos, results, resultsDiv) =>
  {
    saveForRenderCallback = [];
    for (const result of results) {
      const {
        richSnippet: {
          answer = []
        } = {},
      } = result;
      const firstAnswer = answer[0];
      if (firstAnswer) {
        const upVotes = firstAnswer['upvotecount'];
        if (upVotes) {
          saveForRenderCallback.push(
            {upvotes: parseInt(upVotes, 10)}
          );
          continue;
        }
      }
      saveForRenderCallback.push({});
    }
  };
  const renderedCallback = (name, q, promos, results) => {
    for (let i = 0; i < results.length; ++i) {
      const div = results[i];
      const votes = saveForRenderCallback[i]['upvotes'];
      if (votes) {
        const innerDiv = document.createElement('div');
        innerDiv.innerHTML = '<b>Upvotes: ' + votes + '</b>';
         div.insertAdjacentElement('afterbegin', innerDiv);
      }
    }
  };
  return {readyCallback, renderedCallback};
};
設定 __gcse 時,請使用如下所示的程式碼安裝此回呼:
const {
  readyCallback: webResultsReadyCallback,
  renderedCallback: webResultsRenderedCallback,
} = makeTwoPartCallback();
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    ready: webResultsReadyCallback,
    rendered: webResultsRenderedCallback,
  },
};
  <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:kdroeu4mwju"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

更多回呼範例

如需其他回呼範例,請前往 更多回呼範例文件。

宣傳活動與結果屬性

使用 JSDoc 標記法,這些是用於 promotionresult 物件。 這裡會列出可能出現的所有屬性。其中有許多屬性 視促銷活動或搜尋結果的細節而定。

宣傳屬性
{
  content: string,
  image: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  url: string,
  visibleUrl: string,
}
結果物件屬性
{
  content: string,
  contentNoFormatting: string,
  contextUrl: string, // For image search results only
  fileFormat: string,
  image: { // For image search reseults only
    height: number,
    url: string,
    width: number,
  },
  perResultLabels: !Array<{
    anchor: string,
    label: string,
    labelWithOp: string,
  }>,
  richSnippet: !Array<!Object>, // For web search results only
  thumbnailImage: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  titleNoFormatting: string,
  url: string,
  visibleUrl: string,
}

結果中的 richSnippet 具有一系列類型的 如需儲存大量結構化物件 建議使用 Cloud Bigtable此陣列中的項目值是由 結構化資料 。舉例來說,評論網站可能包含 可將此陣列項目新增至 richSnippet 的結構化資料:

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

Programmable Search Element Control API (第 2 版)

google.search.cse.element 物件會發布以下項目 靜態函式:

功能 說明
.render(componentConfig, opt_componentConfig) 呈現搜尋元素。

參數

名稱 說明
componentConfig 程式化搜尋元素元件的設定。請指定以下內容:
  • div (string|元素):<div>id,或要算繪程式化搜尋元素的 div 元素。
  • tag (字串):要算繪的元件類型。(如果提供 opt_componentConfigtag 屬性的值必須為 searchbox)。允許的值如下:
    • search:搜尋框與搜尋結果並列顯示
    • searchbox:程式化搜尋元素的搜尋框元件。
    • searchbox-only:獨立的搜尋框,與 opt_componentConfig 以雙欄版面配置指定的搜尋結果區塊配對。
    • searchresults-only:搜尋結果的獨立區塊。搜尋是由網址內嵌的查詢參數,或由程式輔助執行所觸發。
  • gname (字串):(選填) 此元件的專屬名稱。如未提供,程式化搜尋引擎會自動產生 gname
  • attributes (物件):採用鍵/值組合形式的選用屬性。支援的屬性
opt_componentConfig 選用設定。第二個元件設定引數。用於「TWO_COLUMN」 模式提供 searchresults 元件。請指定以下內容:
  • div (字串):<div>id,或 要算繪元素的位置 div 元素。
  • tag (字串):要算繪的元件類型。時間 提供 opt_componentConfig,也就是 tag 的值 屬性必須為 searchresults。此外, componentConfigtag 屬性 必須設為 searchbox
  • gname (字串):(選填) 此元件的專屬名稱。如果不是 此時程式化搜尋引擎會自動產生 gname 元件。如果提供,必須與 gnamecomponentConfig
  • attributes (物件):採用鍵/值格式的選用屬性 配對。 支援的屬性。
.go(opt_container) 呈現指定容器中的所有搜尋元素標記/類別。

參數

名稱 說明
opt_container 包含要算繪的搜尋元素元件的容器。請說明 容器 (字串) 或元素本身的 ID。如果 網頁 將顯示 body 標記。
.getElement(gname) 透過 gname 取得元素物件。如果找不到,則傳回空值。

傳回的 element 物件包含下列屬性:

  • gname:元素物件的名稱。如未提供,程式化搜尋引擎 會自動為物件產生 gname瞭解詳情
  • type:元素的類型。
  • uiOptions:用於算繪元素的最終屬性。
  • execute - function(字串):執行程式輔助查詢。
  • prefillQuery - function(string):在搜尋框中預先填入查詢 字串,而不執行查詢。
  • getInputQuery - function():取得輸入內容中顯示的目前值 方塊。
  • clearAllResults - function():除了隱藏所有項目, 搜尋框 (如果有的話)

下列程式碼會執行查詢「news」在搜尋元素「element1」中:

var element = google.search.cse.element.getElement('element1');
            element.execute('news');
.getAllElements() 傳回所有成功建立元素物件的對應,其鍵為 gname