Programmable Search Element Control API

HTML マークアップを使用すると、プログラム可能な検索エンジンのコンポーネント(検索ボックスと検索結果ページ)をウェブページや他のウェブ アプリケーションに埋め込むことができます。プログラム可能検索エンジンの要素は、プログラム可能検索サーバーに保存された設定と、ユーザーが行ったカスタマイズに基づいてレンダリングされるコンポーネントで構成されています。

すべての JavaScript は非同期で読み込まれるため、ブラウザがプログラム可能検索エンジンの JavaScript を取得している間も、ウェブページの読み込みを続行できます。

はじめに

このドキュメントでは、プログラム可能検索エンジンの要素をウェブページに追加するための基本的なモデルと、要素の構成可能なコンポーネントと柔軟な JavaScript API の説明を提供します。

スコープ

このドキュメントでは、プログラマブル検索エンジン コントロール API に固有の関数とプロパティの使用方法について説明します。

ブラウザの互換性

プログラム可能な検索エンジンでサポートされているブラウザの一覧については、こちらをご覧ください。

視聴者

このドキュメントは、Google プログラマブル検索の機能をページに追加したいデベロッパーを対象としています。

Programmable Search の要素

HTML マークアップを使用して、プログラム可能な検索要素をページに追加できます。各要素は、検索ボックス、検索結果のブロック、またはその両方の少なくとも 1 つのコンポーネントで構成されます。検索ボックスでは、ユーザー入力は次のいずれかの方法で受け付けられます。

  • テキスト入力フィールドに入力された検索クエリ
  • URL に埋め込まれたクエリ文字列
  • プログラマティックな実行

また、検索結果のブロックは、次の方法で入力を受け付けます。

  • URL に埋め込まれたクエリ文字列
  • プログラマティックな実行

次のタイプのプログラマブル検索要素を使用できます。

要素の種類 コンポーネント 説明
standard <div class="gcse-search"> 検索ボックスと検索結果が同じ <div> に表示されている。
two-column <div class="gcse-searchbox"><div class="gcse-searchresults"> 検索結果と検索ボックスが左右に配置された 2 列レイアウト。ウェブページに 2 列モードで複数の要素を挿入する場合は、gname 属性を使用して検索ボックスと検索結果のブロックをペアにできます。
searchbox-only <div class="gcse-searchbox-only"> スタンドアロンの検索ボックス。
searchresults-only <div class="gcse-searchresults-only"> 検索結果のスタンドアロン ブロック。

有効な検索要素は、ウェブページにいくつでも追加できます。2 列モードでは、必要なコンポーネント(検索ボックスと検索結果ブロック)がすべて存在している必要があります。

シンプルな検索要素の例を次に示します。

<!-- 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">
2 列 <div class="gcse-searchbox"><div class="gcse-searchresults">
2 ページ 1 ページ目に <div class="gcse-searchbox-only">、2 ページ目に <div class="gcse-searchresults-only">(または他のコンポーネント)。
結果のみ <div class="gcse-searchresults-only">
Google ホスト型 <div class="gcse-searchbox-only">

レイアウト オプションの詳細

Programmable Search の要素をカスタマイズする

色、フォント、リンクのスタイルをカスタマイズするには、プログラム可能検索エンジンの [ルック アンド フィール] ページに移動します。

オプションの属性を使用して、プログラム可能検索エンジンのコントロール パネルで作成された構成を上書きできます。これにより、ページ固有の検索エクスペリエンスを作成できます。たとえば、次のコードは、新しいウィンドウで結果ページ(http://www.example.com?search=lady+gaga)を開く検索ボックスを作成します。queryParameterName 属性の値とユーザーのクエリ文字列を使用して、検索結果の URL が作成されます。

queryParameterName 属性には接頭辞 data- が付いています。この接頭辞はすべての属性で必須です。

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

プログラム可能な検索エンジンのコントロール パネルを使用して、オートコンプリート絞り込みなどの機能を有効にしている場合は、属性を使用してこれらの機能をカスタマイズできます。これらの属性を使用して指定したカスタマイズは、コントロール パネルで行われた設定をオーバーライドします。次の例では、次の機能を備えた 2 列の検索要素を作成します。

  • 履歴管理が有効になっている
  • 表示される予測入力の最大数が 5 に設定されている
  • 絞り込み条件はリンクとして表示されます。

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

サポートされている属性

属性 説明 コンポーネント
全般
gname 文字列 (省略可)Search Element オブジェクトの名前。名前は、名前で関連付けられたコンポーネントを取得したり、searchbox コンポーネントを searchresults コンポーネントとペア設定したりするために使用されます。指定しない場合、プログラム可能検索エンジンはウェブページのコンポーネントの順序に基づいて gname を自動的に生成します。たとえば、最初の名前のない searchbox-onlygname は「searchbox-only0」、2 番目の searchbox-onlygname は「seachbox-only1」などとなります。2 列レイアウトのコンポーネントに対して自動生成される gnametwo-column になります。次の例では、gname storesearch を使用して、searchbox コンポーネントを searchresults コンポーネントにリンクしています。
<div class="gcse-searchbox" data-gname="storesearch"></div>
<div class="gcse-searchresults" data-gname="storesearch"></div>

オブジェクトを取得するときに、複数のコンポーネントに同じ gname がある場合、プログラム可能検索エンジンはページ上の最後のコンポーネントを使用します。

すべて
autoSearchOnLoad ブール値 読み込み中のページの URL に埋め込まれたクエリで検索を実行するかどうかを指定します。自動検索を実行するには、URL にクエリ文字列が存在する必要があります。デフォルト: true すべて
enableHistory ブール値 true の場合、ブラウザの [戻る] ボタンと [進む] ボタンの履歴管理を有効にします。デモをご覧ください。

searchbox

searchbox-only

queryParameterName 文字列 クエリ パラメータ名(q(デフォルト)や query など)。これは URL に埋め込まれます(例: http://www.example.com?q=lady+gaga)。クエリ パラメータ名のみを指定しても、読み込み時に自動検索はトリガーされません。自動検索を実行するには、URL にクエリ文字列が存在する必要があります。 すべて
resultsUrl URL 結果ページの URL。(デフォルトは Google ホストのページです)。 searchbox-only
newWindow ブール値 検索結果ページを新しいウィンドウで開くかどうかを指定します。デフォルト: false searchbox-only
ivt ブール値

このパラメータを使用すると、同意済みのトラフィックと同意のないトラフィックの両方で、無効なトラフィック検出専用 Cookie とローカル ストレージを使用する広告を許可するよう Google に通知するブール値を指定できます。

true このパラメータが存在しない場合、または「true」に設定されている場合、Google は無効なトラフィック検出専用の Cookie を設定し、同意済みのトラフィックでのみローカル ストレージを使用します。

false このパラメータを「false」に設定すると、同意済みのトラフィックと同意のないトラフィックの両方で、無効なトラフィック検出専用 Cookie が設定され、ローカル ストレージが使用されます。

デフォルト: false

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

searchresults

searchresults-only

mobileLayout 文字列

モバイル レイアウト スタイルをモバイル デバイスで使用するかどうかを指定します。

enabled モバイル デバイスでのみモバイル レイアウトを使用します。

disabled どのデバイスでもモバイル レイアウトを使用しません。

forced すべてのデバイスでモバイル レイアウトを使用します。

デフォルト: enabled

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

すべて
予測入力
enableAutoComplete ブール値 プログラム可能検索エンジンのコントロール パネルで自動補完が有効になっている場合にのみ使用できます。true は予測入力を有効にします。 すべて
autoCompleteMaxCompletions 整数 表示する自動補完の最大数。

searchbox

searchbox-only

autoCompleteMaxPromotions 整数 予測入力に表示するプロモーションの最大数。

searchbox

searchbox-only

autoCompleteValidLanguages 文字列 自動補完を有効にする言語のカンマ区切りのリスト。 サポートされている言語。

searchbox

searchbox-only

改善点
defaultToRefinement 文字列 プログラム可能な検索エンジンのコントロール パネルで絞り込みが作成されている場合にのみ使用できます。表示するデフォルトの絞り込みラベルを指定します。注: この属性は Google Hosted レイアウトではサポートされていません。 すべて
refinementStyle 文字列 指定できる値は tab(デフォルト)と link です。link は、画像検索が無効になっている場合、または画像検索は有効になっているがウェブ検索が無効になっている場合にのみサポートされます。

searchresults

searchresults-only

画像検索
enableImageSearch ブール値 プログラム可能な検索エンジンのコントロール パネルで 画像検索が有効になっている場合にのみ使用できます。

true の場合、画像検索を有効にします。画像検索の結果は別のタブに表示されます。

searchresults

searchresults-only

defaultToImageSearch ブール値 プログラム可能検索エンジンのコントロール パネルで 画像検索が有効になっている場合にのみ使用できます。

true の場合、検索結果ページにはデフォルトで画像検索結果が表示されます。ウェブ検索の結果は別のタブで確認できます。

すべて
imageSearchLayout 文字列 プログラム可能検索エンジンのコントロール パネルで 画像検索が有効になっている場合にのみ使用できます。

画像検索結果ページのレイアウトを指定します。指定できる値は classiccolumnpopup です。

searchresults

searchresults-only

imageSearchResultSetSize Integer、String プログラム可能な検索エンジンのコントロール パネルで 画像検索が有効になっている場合にのみ使用できます。

画像検索の検索結果セットの最大サイズを指定します。たとえば、largesmallfiltered_cse10

すべて
image_as_filetype 文字列 プログラム可能検索エンジンのコントロール パネルで 画像検索が有効になっている場合にのみ使用できます。

結果を指定した拡張子のファイルに制限します。

サポートされている拡張子は、jpggifpngbmpsvgwebpicoraw です。

すべて

image_as_oq 文字列 プログラム可能な検索エンジンのコントロール パネルで 画像検索が有効になっている場合にのみ使用できます。

論理和を使って検索結果を絞り込みます。

「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

searchresults-only

webSearchQueryAddition 文字列 論理和を使って検索クエリに追加された別のキーワード。

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

すべて
webSearchResultSetSize Integer、String 結果セットの最大サイズ。画像検索とウェブ検索の両方に適用されます。デフォルト値は、レイアウトと、プログラム可能検索エンジンがウェブ全体を検索するように設定されているか、指定されたサイトのみを検索するように設定されているかによって異なります。指定できる値は次のとおりです。
  • 1 ~ 20 の整数
  • small: 通常はページあたり 4 件の結果という、小さな結果セットをリクエストします。
  • large: 通常はページあたり 8 件の結果という、大きな結果セットをリクエストします。
  • filtered_cse: 1 ページあたり最大 10 件の結果をリクエストします。最大 10 ページまたは 100 件の結果が返されます。
すべて
webSearchSafesearch 文字列 ウェブ検索結果でSafeSearchが有効になっているかどうかを指定します。指定できる値は offactive です。 すべて
as_filetype 文字列 結果を指定した拡張子のファイルに制限します。Google でインデックス登録できるファイル形式のリストについては、Search Console のヘルプセンターをご覧ください。

すべて

as_oq 文字列 論理和を使って検索結果を絞り込みます。

「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

searchresults-only

noResultsString 文字列 クエリに一致する検索結果がないときに表示するデフォルトのテキストを指定します。デフォルトの結果文字列は、サポートされているすべての言語でローカライズされた文字列を表示するために使用できますが、カスタマイズされた文字列は使用できません。

searchresults

searchresults-only

resultSetSize Integer、String 結果セットの最大サイズ。たとえば、largesmallfiltered_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 が DOM に検索要素をレンダリングする前に呼び出されます。__gcseparsetagsexplicit に設定されている場合、検索要素 JavaScript は検索要素のレンダリングを初期化コールバックに任せます(コールバックの登録を参照)。これは、レンダリングする要素を選択したり、要素が必要になるまでレンダリングを遅延させたりするために使用されることがあります。また、要素の属性をオーバーライドすることもできます。たとえば、コントロール パネルまたは HTML 属性で設定された検索ボックスを、デフォルトのウェブ検索から画像検索ボックスに変更したり、プログラム可能検索エンジンのフォームから送信されたクエリを検索結果のみの要素で実行するように指定したりできます。 デモを見る。

初期化コールバックの役割は、__gcseparsetags プロパティの値によって制御されます。

  • 値が onload の場合、検索要素 JavaScript はページ上のすべての検索要素を自動的にレンダリングします。初期化コールバックは引き続き呼び出されますが、検索要素のレンダリングは行いません。
  • 値が explicit の場合、検索要素 JavaScript は検索要素をレンダリングしません。コールバックは、render() 関数を使用して選択的にレンダリングすることも、go() 関数を使用してすべての検索要素をレンダリングすることもできます。

次のコードは、explicit parsetag と初期化コールバックを使用して、div に検索結果とともに検索ボックスをレンダリングする方法を示しています。

初期化コールバックの例

検索要素のコードを配置する id 値を持つ <div> を含める必要があります。

    <div id="test"></div>
この JavaScript を <div> の後に追加します。これは、<div> の識別に使用した id である test を参照していることに注意してください。
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 を含めて、検索要素の読み込みを開始します。src 句の cx 値を独自の cx に置き換えます。

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

コールバックを検索する

検索要素 JavaScript は、検索制御フローで動作する 6 つのコールバックをサポートしています。検索コールバックは、ウェブ検索コールバックと一致する画像検索コールバックのペアで返されます。

  • 検索の開始
    • 画像検索の場合
    • ウェブ検索の場合
  • 結果あり
    • 画像検索の場合
    • ウェブ検索の場合
  • レンダリングされた結果
    • 画像検索の場合
    • ウェブ検索の場合

初期化コールバックと同様に、検索コールバックは __gcse オブジェクトのエントリを使用して構成されます。これは、検索要素の 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) {...};
検索開始コールバックの例

検索開始コールバックの例の検索開始コールバックの例では、時刻に応じて morning または afternoon をクエリに追加します。

検索開始コールバックの例
    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>

画像/ウェブ検索結果の準備完了コールバック

これらのコールバックは、検索要素の JavaScript がプロモーションと結果をレンダリングする直前に呼び出されます。使用例としては、プロモーションをレンダリングし、通常のカスタマイズでは指定できないスタイルで結果を表示するコールバックがあります。

resultsReadyCallback(gname, query, promos, results, div)
gname
検索要素の識別文字列
query
これらの結果を生成したクエリ
promos
: ユーザーのクエリに一致したプロモーションに対応するプロモーション オブジェクトの配列。プロモーション オブジェクトの定義をご覧ください。
results
結果オブジェクトの配列。結果オブジェクトの定義をご覧ください。
div
: 検索要素が通常プロモーションと検索結果を配置する DOM に配置された HTML div。通常、この div の入力は検索要素の JavaScript によって処理されますが、このコールバックで結果の自動レンダリングを停止し、この div を使用して結果をレンダリングすることもできます。

このコールバックが true 値を返すと、検索要素 JavaScript はページフッターの処理をスキップします。

結果準備完了コールバックの例

結果準備完了コールバックの例resultsReady コールバックの例では、プロモーションと結果のデフォルトのプレゼンテーションを非常にシンプルな置換でオーバーライドしています。

結果準備完了コールバックの例
    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 オブジェクトに配置する多くの方法の 1 つです。

画像/ウェブ検索結果 - レンダリングされたコールバック

これらのコールバックは、Search Element 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 から評価値を渡す方法の 1 つを示しています。

結果準備完了コールバックと結果レンダリング完了コールバックが連携する例
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>
結果レンダリング コールバックの例: 特定のファイル形式を新しいタブ/ウィンドウで開く

次のコールバックの例では、検索結果のリンクがレンダリングされた後に、現在のウィンドウではなく新しいタブ/ページで特定のファイル(PDF、Excel、Word など)を開くように変更できます。これにより、ユーザーが同じウィンドウでファイルを開いて検索結果ページから移動したくない場合に、ブラウジング エクスペリエンスが向上します。

このコールバックの例では、検索結果内の PDF リンクを特定し、PDF リンクに target="_blank" 属性を設定して、新しいタブで開くようにしています。ページが更新された場合に新しい結果を動的に処理するために、MutationObserver が使用されます。注: handleSearchResults.pdf は、要件に応じて他のファイル形式に置き換えることができます。

このコールバックの例は、Google Hosted レイアウトと Overlay レイアウトでは機能しません。

特定のファイルタイプを新しいタブ/ウィンドウで開く
function handleSearchResults() {
  const links = document.querySelectorAll('.gsc-results .gs-title');
  links.forEach(link => {
    const url = link.href;
    if (url?.toLowerCase().endsWith('.pdf')) {
      link.setAttribute('target', '_blank');
    }
  });
}

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

このコールバックを window.__gcse: にインストールします。

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

コールバックのその他の例

コールバックのその他の例については、コールバックのその他の例をご覧ください。

プロモーションと結果のプロパティ

JSDoc 表記を使用すると、これらは promotion オブジェクトと result オブジェクトのプロパティになります。ここでは、存在する可能性のあるすべてのプロパティを一覧表示します。プロパティの多くは、プロモーションや検索結果の詳細によって存在するかどうかが決まります。

プロモーションのプロパティ
{
  content: string,
  image: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  url: string,
  visibleUrl: string,
}
結果オブジェクトのプロパティ
{
  content: string,
  contentNoFormatting: string,
  contextUrl: string, // For image search results only
  fileFormat: string,
  image: { // For image search reseults only
    height: number,
    url: string,
    width: number,
  },
  perResultLabels: !Array<{
    anchor: string,
    label: string,
    labelWithOp: string,
  }>,
  richSnippet: !Array<!Object>, // For web search results only
  thumbnailImage: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  titleNoFormatting: string,
  url: string,
  visibleUrl: string,
}

結果richSnippet は、オブジェクトの配列の緩い型です。この配列のエントリの値は、各検索結果のウェブページで見つかった構造化データによって制御されます。たとえば、レビュー ウェブサイトでは、この配列エントリを richSnippet に追加する構造化データを含めることができます。

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

Programmable Search Element Control API(V2)

google.search.cse.element オブジェクトは、次の静的関数を公開します。

関数 説明
.render(componentConfig, opt_componentConfig) 検索要素をレンダリングします。

パラメータ

名前 説明
componentConfig プログラム可能な検索要素コンポーネントの構成。次の項目を指定します。
  • div(文字列|要素): プログラム可能検索要素をレンダリングする <div>id または div 要素。
  • tag(文字列): レンダリングするコンポーネントのタイプ。(opt_componentConfig が指定されている場合、tag 属性の値は searchbox である必要があります)。指定できる値は次のとおりです。
    • search: 検索ボックスと検索結果が一緒に表示されている
    • searchbox: プログラマブル検索要素の検索ボックス コンポーネント。
    • searchbox-only: スタンドアロンの検索ボックス。2 列レイアウトで opt_componentConfig で指定された検索結果のブロックとペア設定されます。
    • searchresults-only: 検索結果のスタンドアロン ブロック。検索は、URL に埋め込まれたクエリ パラメータまたはプログラムによる実行によってトリガーされます。
  • gname(文字列):(省略可)このコンポーネントの一意の名前。指定されていない場合、プログラム可能検索エンジンは gname を自動的に生成します。
  • attributes(オブジェクト): Key-Value ペアの形式の省略可能な属性。サポートされている属性。
opt_componentConfig 省略可。2 番目のコンポーネント構成引数。TWO_COLUMN モードで searchresults コンポーネントを提供するために使用されます。次の項目を指定します。
  • div(文字列): 要素がレンダリングされる <div> または div 要素の id
  • tag(文字列): レンダリングするコンポーネントのタイプ。opt_componentConfig を指定する場合は、tag 属性の値を searchresults にする必要があります。また、componentConfig tag 属性の値は searchbox にする必要があります。
  • gname(文字列):(省略可)このコンポーネントの一意の名前。指定しない場合、プログラム可能検索エンジンはこのコンポーネントの gname を自動的に生成します。指定する場合は、componentConfiggname と一致する必要があります。
  • attributes(オブジェクト): Key-Value ペアの形式の省略可能な属性。 サポートされている属性。
.go(opt_container) 指定されたコンテナ内のすべての検索要素タグ/クラスをレンダリングします。

パラメータ

名前 説明
opt_container レンダリングする検索要素コンポーネントを含むコンテナ。コンテナの ID(文字列)または要素自体を指定します。省略すると、ページの body タグ内のすべてのプログラマブル検索要素コンポーネントがレンダリングされます。
.getElement(gname) gname で要素オブジェクトを取得します。見つからない場合は、null を返します。

返される element オブジェクトには次の属性があります。

  • gname: 要素オブジェクトの名前。指定しない場合、プログラム可能検索エンジンはオブジェクトの gname を自動的に生成します。詳細
  • type: 要素のタイプ。
  • uiOptions: 要素のレンダリングに使用される最終的な属性。
  • execute - function(string): プログラマティック クエリを実行します。
  • prefillQuery - function(string): クエリを実行せずに、検索ボックスにクエリ文字列を事前入力します。
  • getInputQuery - function(): 入力ボックスに表示されている現在の値を取得します。
  • clearAllResults - function(): 検索ボックス(存在する場合)以外のすべてを非表示にして、コントロールをクリアします。

次のコードは、検索要素「element1」でクエリ「news」を実行します。

var element = google.search.cse.element.getElement('element1');
            element.execute('news');
.getAllElements() gname でキー付けされた、正常に作成されたすべての要素オブジェクトのマップを返します。