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-only の gname は「searchbox-only0」、2 番目の searchbox-only の gname は「seachbox-only1」などとなります。2 列レイアウトのコンポーネントに対して自動生成される gname は two-column になります。次の例では、gname storesearch を使用して、searchbox コンポーネントを searchresults コンポーネントにリンクしています。<div class="gcse-searchbox" data-gname="storesearch"></div> <div class="gcse-searchresults" data-gname="storesearch"></div> オブジェクトを取得するときに、複数のコンポーネントに同じ |
すべて |
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 に通知するブール値を指定できます。
デフォルト: 使用例: |
searchresults searchresults-only |
mobileLayout |
文字列 |
モバイル レイアウト スタイルをモバイル デバイスで使用するかどうかを指定します。
デフォルト: 使用例: |
すべて |
| 予測入力 | |||
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 |
ブール値 | プログラム可能な検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。
|
searchresults searchresults-only |
defaultToImageSearch |
ブール値 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。
|
すべて |
imageSearchLayout |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 画像検索結果ページのレイアウトを指定します。指定できる値は |
searchresults searchresults-only |
imageSearchResultSetSize |
Integer、String | プログラム可能な検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 画像検索の検索結果セットの最大サイズを指定します。たとえば、 |
すべて |
image_as_filetype |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 結果を指定した拡張子のファイルに制限します。 サポートされている拡張子は、 | すべて |
image_as_oq |
文字列 | プログラム可能な検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 論理和を使って検索結果を絞り込みます。 「term1」または「term2」を含む検索結果が必要な場合のサンプル使用方法: | すべて |
image_as_rights |
文字列 | プログラム可能な検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 ライセンスに基づくフィルタ。 サポートされている値は、 一般的な組み合わせをご覧ください。 | すべて |
image_as_sitesearch |
文字列 | プログラム可能な検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 検索結果を特定のサイトのページに制限します。 使用例: | すべて |
image_colortype |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 検索を白黒(モノクロ)、グレースケール、カラー画像に制限します。サポートされている値は | すべて |
image_cr |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 特定の国で作成されたドキュメントに検索結果を制限します。 | すべて |
image_dominantcolor |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 検索対象を特定のドミナント カラーの画像に制限します。サポートされている値は、 | すべて |
image_filter |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 検索結果の自動フィルタリングを行います。 サポートされている値: 0/1 使用例: | すべて |
image_gl |
文字列 | プログラム可能検索エンジンのコントロール パネルで 画像検索が有効になっている場合にのみ使用できます。原産国がパラメータ値と一致する検索結果のランキングを上げます。 | すべて |
image_size |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 指定されたサイズの画像を返します。サイズは | すべて |
image_sort_by |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 日付またはその他の構造化コンテンツで検索結果を並べ替えます。 関連性で並べ替えるには、空の文字列(image_sort_by="")を使用します。 使用例: | すべて |
image_type |
文字列 | プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用できます。 検索対象を特定の種類の画像に制限します。サポートされている値は、 | すべて |
| ウェブ検索 | |||
disableWebSearch |
ブール値 | true の場合、ウェブ検索を無効にします。通常は、プログラム可能検索エンジンのコントロール パネルで
画像検索が有効になっている場合にのみ使用されます。 |
searchresults searchresults-only |
webSearchQueryAddition |
文字列 | 論理和を使って検索クエリに追加された別のキーワード。
使用例: |
すべて |
webSearchResultSetSize |
Integer、String | 結果セットの最大サイズ。画像検索とウェブ検索の両方に適用されます。デフォルト値は、レイアウトと、プログラム可能検索エンジンがウェブ全体を検索するように設定されているか、指定されたサイトのみを検索するように設定されているかによって異なります。指定できる値は次のとおりです。
|
すべて |
webSearchSafesearch |
文字列 |
ウェブ検索結果でSafeSearchが有効になっているかどうかを指定します。指定できる値は off と active です。 |
すべて |
as_filetype |
文字列 | 結果を指定した拡張子のファイルに制限します。Google でインデックス登録できるファイル形式のリストについては、Search Console のヘルプセンターをご覧ください。 | すべて |
as_oq |
文字列 | 論理和を使って検索結果を絞り込みます。 「term1」または「term2」を含む検索結果が必要な場合のサンプル使用方法: |
すべて |
as_rights |
文字列 | ライセンスに基づくフィルタ。 サポートされている値は、 一般的な組み合わせについては、https://wiki.creativecommons.org/wiki/CC_Search_integration をご覧ください。 | すべて |
as_sitesearch |
文字列 | 検索結果を特定のサイトのページに制限します。 使用例: |
すべて |
cr |
文字列 | 特定の国で作成されたドキュメントに検索結果を制限します。 使用例: |
すべて |
filter |
文字列 | 検索結果の自動フィルタリングを行います。 サポートされている値: 0/1 使用例: |
すべて |
gl |
文字列 | 原産国がパラメータ値と一致する検索結果のランキングを上げます。 この機能は、言語の値の設定と組み合わせて使用する場合にのみ機能します。 使用例: |
すべて |
lr |
文字列 | 特定の言語で作成されたドキュメントに検索結果を制限します。 使用例: |
すべて |
sort_by |
文字列 | 日付またはその他の構造化コンテンツで検索結果を並べ替えます。属性値は、プログラマブル検索エンジンの [検索結果の並べ替え] 設定で指定されたオプションのいずれかである必要があります。 関連性で並べ替えるには、空の文字列(sort_by="")を使用します。 使用例: |
すべて |
| 検索結果 | |||
enableOrderBy |
ブール値 | 関連性、日付、ラベルで結果を並べ替えることができます。 | すべて |
linkTarget |
文字列 | リンク ターゲットを設定します。デフォルト: _blank。 |
searchresults searchresults-only |
noResultsString |
文字列 | クエリに一致する検索結果がないときに表示するデフォルトのテキストを指定します。デフォルトの結果文字列は、サポートされているすべての言語でローカライズされた文字列を表示するために使用できますが、カスタマイズされた文字列は使用できません。 | searchresults searchresults-only |
resultSetSize |
Integer、String | 結果セットの最大サイズ。たとえば、large、small、filtered_cse、10。デフォルトは、レイアウトと、エンジンがウェブ全体を検索するように設定されているか、特定のサイトのみを検索するように設定されているかによって異なります。 |
すべて |
safeSearch |
文字列 | ウェブ検索と画像検索の両方で
セーフサーチを有効にするかどうかを指定します。指定できる値は off と active です。 |
すべて |
コールバック
コールバックは、検索要素の初期化と検索プロセスの詳細な制御をサポートします。これらは、グローバル __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 に検索要素をレンダリングする前に呼び出されます。__gcse で parsetags が explicit に設定されている場合、検索要素 JavaScript は検索要素のレンダリングを初期化コールバックに任せます(コールバックの登録を参照)。これは、レンダリングする要素を選択したり、要素が必要になるまでレンダリングを遅延させたりするために使用されることがあります。また、要素の属性をオーバーライドすることもできます。たとえば、コントロール パネルまたは HTML 属性で設定された検索ボックスを、デフォルトのウェブ検索から画像検索ボックスに変更したり、プログラム可能検索エンジンのフォームから送信されたクエリを検索結果のみの要素で実行するように指定したりできます。
デモを見る。
初期化コールバックの役割は、__gcse の parsetags プロパティの値によって制御されます。
- 値が
onloadの場合、検索要素 JavaScript はページ上のすべての検索要素を自動的にレンダリングします。初期化コールバックは引き続き呼び出されますが、検索要素のレンダリングは行いません。 - 値が
explicitの場合、検索要素 JavaScript は検索要素をレンダリングしません。コールバックは、render()関数を使用して選択的にレンダリングすることも、go()関数を使用してすべての検索要素をレンダリングすることもできます。
次のコードは、explicit parsetag と初期化コールバックを使用して、div に検索結果とともに検索ボックスをレンダリングする方法を示しています。
検索要素のコードを配置する id 値を持つ <div> を含める必要があります。
<div id="test"></div><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) |
検索要素をレンダリングします。 パラメータ
|
||||||
.go(opt_container) |
指定されたコンテナ内のすべての検索要素タグ/クラスをレンダリングします。 パラメータ
|
||||||
.getElement(gname) |
gname で要素オブジェクトを取得します。見つからない場合は、null を返します。返される
次のコードは、検索要素「element1」でクエリ「news」を実行します。 var element = google.search.cse.element.getElement('element1'); element.execute('news'); |
||||||
.getAllElements() |
gname でキー付けされた、正常に作成されたすべての要素オブジェクトのマップを返します。 |