API управления программируемым поисковым элементом

Вы можете встраивать компоненты программируемой поисковой системы (поля поиска и страницы результатов поиска) в свои веб-страницы и другие веб-приложения с помощью разметки HTML. Эти элементы программируемой поисковой системы состоят из компонентов, которые отображаются на основе настроек, хранящихся на сервере программируемого поиска, а также любых внесенных вами настроек.

Весь код JavaScript загружается асинхронно, что позволяет вашей веб-странице продолжать загрузку, пока браузер получает код JavaScript программируемой поисковой системы.

Введение

В этом документе представлена ​​базовая модель добавления элементов программируемой поисковой системы на вашу веб-страницу, а также пояснения настраиваемых компонентов элемента и гибкого API JavaScript.

Объем

В этом документе описывается, как использовать функции и свойства, специфичные для API управления программируемой поисковой системой.

Совместимость с браузером

Список браузеров, поддерживаемых Программируемой поисковой системой, можно найти здесь .

Аудитория

Эта документация предназначена для разработчиков, желающих добавить на свои страницы функции программируемого поиска Google.

Программируемые поисковые элементы

Вы можете использовать HTML-разметку, чтобы добавить на свою страницу элемент программируемого поиска. Каждый элемент состоит как минимум из одного компонента: поля поиска, блока результатов поиска или того и другого. Поле поиска принимает ввод пользователя любым из следующих способов:

  • Поисковый запрос, введенный в поле ввода текста
  • Строка запроса, встроенная в URL-адрес.
  • Программное исполнение

Кроме того, блок результатов поиска принимает ввод следующими способами:

  • Строка запроса, встроенная в URL-адрес.
  • Программное исполнение

Доступны следующие типы программируемых поисковых элементов:

Тип элемента Компонент(ы) Описание
стандартный <div class="gcse-search"> Поле поиска и результаты поиска отображаются в одном <div> .
двухколоночный <div class="gcse-searchbox"> и <div class="gcse-searchresults"> Макет из двух столбцов с результатами поиска с одной стороны и полем поиска с другой. Если вы планируете вставить на свою веб-страницу несколько элементов в режиме двух столбцов, вы можете использовать атрибут gname , чтобы соединить поле поиска с блоком результатов поиска.
только для окна поиска <div class="gcse-searchbox-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 вместе со строкой пользовательского запроса используется для создания URL-адреса результатов.

Обратите внимание, что атрибут 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 логическое значение Указывает, выполнять ли поиск по запросу, встроенному в URL-адрес загружаемой страницы. Обратите внимание, что для выполнения автоматического поиска в URL-адресе должна присутствовать строка запроса. По умолчанию: true . Любой
enableHistory логическое значение Если true , включает управление историей для кнопок браузера «Назад» и «Вперед». Посмотрите демо.

окно поиска

только для окна поиска

queryParameterName Нить Имя параметра запроса, например q (по умолчанию) или query . Он будет встроен в URL-адрес (например, http://www.example.com?q=lady+gaga). Обратите внимание, что указание только имени параметра запроса не запускает автоматический поиск при загрузке. Для выполнения автоматического поиска в URL-адресе должна присутствовать строка запроса. Любой
resultsUrl URL-адрес URL-адрес страницы результатов. (По умолчанию используется страница, размещенная на Google.) только для окна поиска
newWindow логическое значение Указывает, открывается ли страница результатов в новом окне. По умолчанию: false . только для окна поиска
ivt логическое значение

Этот параметр позволяет вам указать логическое значение, сообщающее Google о том, что вы хотите разрешить рекламу, использующую недействительные файлы cookie только для трафика и локальное хранилище, как для согласованного, так и для несогласованного трафика.

true Если этот параметр отсутствует или вы установили для него значение «истина», мы установим недействительный файл cookie только для трафика и будем использовать локальное хранилище только для согласованного трафика.

false Если вы установите для этого параметра значение «false», мы установим недействительный файл cookie только для трафика и будем использовать локальное хранилище как для согласованного, так и для несогласованного трафика.

По умолчанию: false

Пример использования: <div class="gcse-search" data-ivt="true"></div>

результаты поиска

только результаты поиска

mobileLayout Нить

Указывает, следует ли использовать стили макета для мобильных устройств для мобильных устройств.

enabled Использует мобильную раскладку только для мобильных устройств.

disabled Не использует мобильную раскладку ни для каких устройств.

forced Использует мобильную раскладку для всех устройств.

По умолчанию: enabled

Пример использования: <div class="gcse-search" data-mobileLayout="disabled"></div>

Любой
Автозаполнение
enableAutoComplete логическое значение Доступно только в том случае, если автозаполнение включено на панели управления Программируемой поисковой системы. true включает автозаполнение. Любой
autoCompleteMaxCompletions Целое число Максимальное количество отображаемых автозаполнений.

окно поиска

только для окна поиска

autoCompleteMaxPromotions Целое число Максимальное количество рекламных акций, отображаемых в автозаполнении.

окно поиска

только для окна поиска

autoCompleteValidLanguages Нить Список языков, разделенных запятыми, для которых следует включить автозаполнение. Поддерживаемые языки.

окно поиска

только для окна поиска

Уточнения
defaultToRefinement Нить Доступно только в том случае, если уточнения были созданы на панели управления Программируемой поисковой системы. Указывает отображаемую метку уточнения по умолчанию. Примечание. Этот атрибут не поддерживается для макета, размещенного в Google. Любой
refinementStyle Нить Допустимые значения: tab (по умолчанию) и link . link поддерживается только в том случае, если поиск изображений отключен или если поиск изображений включен, но поиск в Интернете отключен.

результаты поиска

только результаты поиска

Поиск изображений
enableImageSearch логическое значение Доступно только в том случае, если поиск изображений включен на панели управления программируемой поисковой системой.

Если true , включает поиск изображений. Результаты изображений будут показаны на отдельной вкладке.

результаты поиска

только результаты поиска

defaultToImageSearch логическое значение Доступно только в том случае, если поиск изображений включен на панели управления программируемой поисковой системой.

Если true , на странице результатов поиска по умолчанию будут отображаться результаты поиска изображений. Веб-результаты будут доступны на отдельной вкладке.

Любой
imageSearchLayout Нить Доступно только в том случае, если поиск изображений включен на панели управления программируемой поисковой системой.

Задает макет страницы результатов поиска изображений. Допустимые значения: classic , column или popup .

результаты поиска

только результаты поиска

imageSearchResultSetSize Целое число, строка Доступно только в том случае, если поиск изображений включен на панели управления программируемой поисковой системой.

Указывает максимальный размер набора результатов поиска для поиска изображений. Например, large , small , filtered_cse , 10 .

Любой
image_as_filetype Нить Доступно только в том случае, если поиск изображений включен на панели управления программируемой поисковой системой.

Ограничивает результаты файлами указанного расширения.

Поддерживаемые расширения: jpg , gif , png , bmp , svg , webp , ico , raw .

Любой

image_as_oq Нить Доступно только в том случае, если поиск изображений включен на панели управления программируемой поисковой системой.

Фильтрация результатов поиска с помощью логического ИЛИ.

Пример использования, если вам нужны результаты поиска, включающие «term1» или «term2»: <div class="gcse-search" data-image_as_oq="term1 term2"></div>

Любой

image_as_rights Нить Доступно только в том случае, если поиск изображений включен на панели управления программируемой поисковой системой.

Фильтры на основе лицензирования.

Поддерживаемые значения: cc_publicdomain , cc_attribute , cc_sharealike , cc_noncommercial , cc_nonderived и их комбинации.

См. типичные комбинации .

Любой

image_as_sitesearch Нить Доступно только в том случае, если поиск изображений включен на панели управления программируемой поисковой системой.

Ограничьте результаты страницами с определенного сайта.

Пример использования: <div class="gcse-search" data-image_as_sitesearch="example.com"></div>

Любой

image_colortype Нить Доступно только в том случае, если поиск изображений включен на панели управления программируемой поисковой системой.

Ограничивает поиск черно-белыми (монохромными), полутоновыми или цветными изображениями. Поддерживаемые значения: mono , gray , color .

Любой

image_cr Нить Доступно только в том случае, если поиск изображений включен на панели управления программируемой поисковой системой.

Ограничивает результаты поиска документами, происходящими из определенной страны.

Поддерживаемые значения

Любой

image_dominantcolor Нить Доступно только в том случае, если поиск изображений включен на панели управления программируемой поисковой системой.

Ограничивает поиск изображениями определенного доминирующего цвета. Поддерживаемые значения brown red , orange , yellow , green , teal , blue , purple , pink , white , серый, gray , black .

Любой

image_filter Нить Доступно только в том случае, если поиск изображений включен на панели управления программируемой поисковой системой.

Автоматическая фильтрация результатов поиска.

Поддерживаемые значения: 0/1

Пример использования: <div class="gcse-search" data-image_filter="0"></div>

Любой

image_gl Нить Доступно только в том случае, если поиск изображений включен на панели управления программируемой поисковой системой. Увеличьте результаты поиска, страна происхождения которых соответствует значению параметра.

Поддерживаемые значения

Любой

image_size Нить Доступно только в том случае, если поиск изображений включен на панели управления программируемой поисковой системой.

Возвращает изображения указанного размера, где размер может быть одним из следующих: icon , small , medium , large , xlarge , xxlarge или huge.

Любой

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 , отключает веб-поиск. Обычно используется только в том случае, если поиск изображений включен на панели управления программируемой поисковой системой.

результаты поиска

только результаты поиска

webSearchQueryAddition Нить Дополнительные термины добавляются в поисковый запрос с помощью логического ИЛИ.

Пример использования: <div class="gcse-search" data-webSearchQueryAddition="term1 term2"></div>

Любой
webSearchResultSetSize Целое число, строка Максимальный размер набора результатов. Применяется как к поиску изображений, так и к веб-поиску. Значение по умолчанию зависит от макета и от того, настроена ли программируемая поисковая система на поиск по всей сети или только по определенным сайтам. Приемлемые значения включают в себя:
  • Целое число от 1 до 20
  • small : запрашивает небольшой набор результатов, обычно 4 результата на страницу.
  • large : запрашивает большой набор результатов, обычно 8 результатов на страницу.
  • filtered_cse : запрашивает до 10 результатов на страницу, максимум 10 страниц или 100 результатов.
Любой
webSearchSafesearch Нить Указывает, включен ли безопасный поиск для результатов веб-поиска. Принятые значения off и active . Любой
as_filetype Нить Ограничивает результаты файлами указанного расширения. Список типов файлов, индексируемых Google, можно найти в Справочном центре Search Console.

Любой

as_oq Нить Фильтрация результатов поиска с помощью логического ИЛИ.

Пример использования, если вам нужны результаты поиска, включающие «term1» или «term2»: <div class="gcse-search" data-as_oq="term1 term2"></div>

Любой
as_rights Нить Фильтры на основе лицензирования.

Поддерживаемые значения: cc_publicdomain , cc_attribute , cc_sharealike , cc_noncommercial , cc_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 .

результаты поиска

только результаты поиска

noResultsString Нить Указывает текст по умолчанию, который будет отображаться, если нет результатов, соответствующих запросу. Строку результата по умолчанию можно использовать для отображения локализованной строки на всех поддерживаемых языках, а настроенную — нет.

результаты поиска

только результаты поиска

resultSetSize Целое число, строка Максимальный размер набора результатов. Например, large , small , filtered_cse , 10 . Значение по умолчанию зависит от макета и от того, настроен ли движок для поиска по всей сети или только по определенным сайтам. Любой
safeSearch Нить Указывает, включен ли безопасный поиск как для поиска в Интернете, так и для поиска изображений. Принятые значения off и active . Любой

Обратные вызовы

Диаграмма последовательности обратного вызова
диаграмма последовательности обратных вызовов из JavaScript элемента поиска

Обратные вызовы поддерживают детальный контроль над инициализацией поисковых элементов и процессами поиска. Они регистрируются в JavaScript элемента поиска через глобальный объект __gcse . Регистрация обратных вызовов иллюстрирует регистрацию всех поддерживаемых обратных вызовов.

Регистрация обратных вызовов

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

Обратный вызов инициализации

Обратный вызов инициализации вызывается до того, как JavaScript элемента поиска отобразит элементы поиска в DOM. Если в __gcse для parsetags установлено explicit , JavaScript элемента поиска оставляет рендеринг элементов поиска обратному вызову инициализации (как показано в разделе «Регистрация обратных вызовов »). Это можно использовать для выбора элементов для рендеринга или для отсрочки рендеринга элементов до тех пор, пока они не потребуются. Он также может переопределять атрибуты элементов; например, он может превратить окно поиска, настроенное с помощью панели управления или атрибутов HTML по умолчанию для веб-поиска, в окно поиска изображений или указать, что запросы, отправленные через форму программируемой поисковой системы, выполняются в элементе только для результатов поиска. Посмотрите демо.

Роль обратного вызова инициализации контролируется значением свойства parsetags __gcse .

  • Если его значение — onload , JavaScript элемента поиска автоматически отображает все элементы поиска на странице. Обратный вызов инициализации по-прежнему вызывается, но он не отвечает за отображение элементов поиска.
  • Если его значение explicit , JavaScript элемента поиска не отображает элементы поиска. Обратный вызов может отображать их выборочно с помощью функции render() или отображать все элементы поиска с помощью функции go()

Следующий код демонстрирует, как визуализировать поле поиска вместе с результатами поиска в div с использованием explicit тега синтаксического анализа и обратного вызова инициализации:

Пример обратного вызова инициализации

Нам нужно включить <div> со значением id там, где нам нужен код элемента поиска:

    <div id="test"></div>
Добавьте этот JavaScript после <div> . Обратите внимание, что он ссылается на 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 . Это происходит при запуске JavaScript элемента поиска. Изменения в __gcse после запуска игнорируются.

Каждому из этих обратных вызовов в качестве аргумента передается gName для элемента поиска. gname полезно, когда страница содержит более одного поиска. Присвойте элементу поиска значения gname используя атрибут data-gname :

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

Если HTML не идентифицирует имя gname, JavaScript элемента поиска генерирует значение, которое будет оставаться неизменным до тех пор, пока HTML не будет изменен.

Обратный вызов при запуске изображения/веб-поиска

Обратные вызовы, запускающие поиск, вызываются непосредственно перед тем, как 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
HTML-элемент div, расположенный в DOM, где элемент поиска обычно размещает рекламные акции и результаты поиска. Обычно JavaScript элемента поиска обрабатывает заполнение этого div, но этот обратный вызов может остановить автоматическую визуализацию результатов и использовать этот div для самой визуализации результатов.

Если этот обратный вызов возвращает true значение, 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 обратного вызова с готовыми результатами results он может передать ее между ними, например:

callback(gname, query, promoElts, resultElts);
gname
Идентифицирующая строка элемента поиска
query
строка поиска.
promoElts
массив элементов DOM, содержащих рекламные акции.
resultElts
массив элементов DOM, содержащих результаты.

Возвращаемого значения нет.

Пример результатов, отображаемых обратного вызова

В примере обратного вызова resultsRendered в разделе «Пример результатов Rendered обратного вызова» добавляется фиктивный флажок «Сохранить » для каждого продвижения и результата.

Результаты. Пример обратного вызова
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 , это свойства объектов продвижения и результата . Здесь мы перечисляем все свойства, которые могут присутствовать. Наличие многих свойств зависит от деталей акции или результатов поиска.

Свойства продвижения
{
  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',
},

API управления программируемым поисковым элементом (V2)

Объект google.search.cse.element публикует следующие статические функции:

Функция Описание
.render(componentConfig, opt_componentConfig) Отображает элемент поиска.

Параметры

Имя Описание
componentConfig Конфигурация компонента «Программируемый поисковый элемент». Указывает следующее:
  • div (string|Element): id <div> или элемента div , в котором должен отображаться программируемый элемент поиска.
  • tag (строка): тип компонента(ов), который будет отображаться. (Если указан opt_componentConfig , значение атрибута tag должно быть searchbox .) Допустимые значения:
    • search : окно поиска и результаты поиска, отображаемые вместе.
    • searchbox : компонент поля поиска программируемого поискового элемента.
    • searchbox-only : отдельное окно поиска, которое будет соединено с блоком результатов поиска, указанным в opt_componentConfig , в макете из двух столбцов.
    • searchresults-only : отдельный блок результатов поиска. Поиск инициируется параметром запроса, встроенным в URL-адрес, или программным выполнением.
  • gname (строка): (Необязательно) Уникальное имя для этого компонента. Если он не указан, Программируемая поисковая система автоматически сгенерирует gname .
  • attributes (Объект): необязательные атрибуты в форме пары ключ:значение. Поддерживаемые атрибуты.
opt_componentConfig Необязательный. Аргумент конфигурации второго компонента. Используется в режиме TWO_COLUMN для предоставления компонента searchresults . Указывает следующее:
  • div (строка): id <div> или элемента div , в котором элемент должен отображаться.
  • tag (строка): тип компонента(ов), который будет отображаться. Если указан opt_componentConfig , значение атрибута tag должно быть searchresults . Кроме того, значением атрибута tag componentConfig должно быть searchbox .
  • gname (строка): (Необязательно) Уникальное имя для этого компонента. Если он не указан, Программируемая поисковая система автоматически сгенерирует gname для этого компонента. Если оно указано, оно должно соответствовать gname в componentConfig .
  • attributes (Объект): необязательные атрибуты в форме пары ключ:значение. Поддерживаемые атрибуты.
.go(opt_container) Отображает все теги/классы элементов поиска в указанном контейнере.

Параметры

Имя Описание
opt_container Контейнер, содержащий компоненты элемента поиска для визуализации. Укажите либо идентификатор контейнера (строку), либо сам элемент. Если этот параметр опущен, будут отображаться все компоненты программируемого элемента поиска внутри тега body страницы.
.getElement(gname) Получает объект элемента по gname . Если не найден, верните ноль.

Возвращенный объект element имеет следующие атрибуты:

  • gname : имя объекта элемента. Если этот параметр не указан, Программируемая поисковая система автоматически сгенерирует gname для объекта. Дополнительная информация.
  • type : Тип элемента.
  • uiOptions : окончательные атрибуты, используемые для визуализации элемента.
  • execute — функция (строка): выполняет программный запрос.
  • prefillQuery — функция(строка): предварительно заполняет поле поиска строкой запроса без выполнения запроса.
  • getInputQuery — function(): получает текущее значение, отображаемое в поле ввода.
  • clearAllResults — функция(): очищает элемент управления, скрывая все, кроме поля поиска, если оно есть.

Следующий код выполняет запрос «news» в элементе поиска «element1»:

var element = google.search.cse.element.getElement('element1');
            element.execute('news');
.getAllElements() Возвращает карту всех успешно созданных объектов-элементов с ключом gname .