Вы можете встраивать компоненты программируемой поисковой системы (поля поиска и страницы результатов поиска) в свои веб-страницы и другие веб-приложения, используя разметку 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", второй — "searchbox-only1" и так далее. Обратите внимание, что автоматически сгенерированное gname для компонента в двухколоночной компоновке будет иметь 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 , включается управление историей для кнопок «Назад» и «Вперед» в браузере. Смотрите демонстрацию. | поле поиска только поле поиска |
queryParameterName | Нить | Имя параметра запроса — например, q (по умолчанию) или query . Оно будет встроено в URL (например, http://www.example.com?q=lady+gaga). Обратите внимание, что указание только имени параметра запроса не запускает автоматический поиск при загрузке. Для выполнения автоматического поиска в URL должна присутствовать строка запроса. | Любой |
resultsUrl | URL | URL страницы с результатами поиска. (По умолчанию используется страница, размещенная Google.) | только поле поиска |
newWindow | Логический | Указывает, будет ли страница результатов открываться в новом окне. По умолчанию: false . | только поле поиска |
ivt | Логический | Этот параметр позволяет указать логическое значение, которое сообщает Google о вашем желании разрешить показ рекламы, использующей недействительный cookie-файл, предназначенный только для трафика, и локальное хранилище как для трафика с вашего согласия, так и для трафика без вашего согласия. Если этот параметр отсутствует или вы установите его значение " Если вы установите этот параметр в значение " По умолчанию: Пример использования: | результаты поиска только результаты поиска |
mobileLayout | Нить | Указывает, следует ли использовать стили мобильной компоновки для мобильных устройств. По умолчанию: Пример использования: | Любой |
| Автозаполнение | |||
enableAutoComplete | Логический | Доступно только в том случае, если функция автозаполнения включена в панели управления программируемой поисковой системой. true включает автозаполнение. | Любой |
autoCompleteMaxCompletions | Целое число | Максимальное количество вариантов автозаполнения для отображения. | поле поиска только поле поиска |
autoCompleteMaxPromotions | Целое число | Максимальное количество рекламных акций для отображения в автозаполнении. | поле поиска только поле поиска |
autoCompleteValidLanguages | Нить | Список языков, для которых следует включить автозаполнение, разделенный запятыми. Поддерживаемые языки. | поле поиска только поле поиска |
| Усовершенствования | |||
defaultToRefinement | Нить | Доступно только в том случае, если уточнения были созданы в панели управления программируемой поисковой системой. Задает метку уточнения по умолчанию для отображения. Примечание: Этот атрибут не поддерживается для макета, размещенного Google. | Любой |
refinementStyle | Нить | Допустимые значения: tab (по умолчанию) и link . link поддерживается только в том случае, если поиск изображений отключен или если поиск изображений включен, но поиск в интернете отключен. | результаты поиска только результаты поиска |
| Поиск изображений | |||
enableImageSearch | Логический | Доступно только в том случае, если поиск изображений включен в панели управления программируемой поисковой системой. Если | результаты поиска только результаты поиска |
defaultToImageSearch | Логический | Доступно только в том случае, если поиск изображений включен в панели управления программируемой поисковой системой. Если | Любой |
imageSearchLayout | Нить | Доступно только в том случае, если поиск изображений включен в панели управления программируемой поисковой системой. Задает макет страницы результатов поиска изображений. Допустимые значения: | результаты поиска только результаты поиска |
imageSearchResultSetSize | Целое число, Строка | Доступно только в том случае, если поиск изображений включен в панели управления программируемой поисковой системой. Указывает максимальный размер набора результатов поиска для поиска изображений. Например, | Любой |
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 | Нить | Доступно только в том случае, если поиск изображений включен в панели управления программируемой поисковой системой. Возвращает изображения указанного размера, где size может быть одним из следующих значений: | Любой |
image_sort_by | Нить | Доступно только в том случае, если поиск изображений включен в панели управления программируемой поисковой системой. Отсортируйте результаты по дате или другому структурированному содержимому. Для сортировки по релевантности используйте пустую строку (image_sort_by=""). Пример использования: | Любой |
image_type | Нить | Доступно только в том случае, если поиск изображений включен в панели управления программируемой поисковой системой. Ограничивает поиск изображениями определенного типа. Поддерживаемые значения: | Любой |
| Поиск в интернете | |||
disableWebSearch | Логический | Если true , веб-поиск отключается. Обычно используется только в том случае, если поиск по изображениям включен в панели управления программируемой поисковой системой. | результаты поиска только результаты поиска |
webSearchQueryAddition | Нить | В поисковый запрос добавлены дополнительные термины с использованием логического ИЛИ. Пример использования: | Любой |
webSearchResultSetSize | Целое число, Строка | Максимальный размер набора результатов. Применяется как к поиску изображений, так и к веб-поиску. Значение по умолчанию зависит от структуры и от того, настроена ли программируемая поисковая система на поиск по всему интернету или только по указанным сайтам. Допустимые значения:
| Любой |
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 . | результаты поиска только результаты поиска |
noResultsString | Нить | Указывает текст по умолчанию, отображаемый в случае отсутствия результатов, соответствующих запросу. Строка результата по умолчанию может использоваться для отображения локализованной строки на всех поддерживаемых языках, в то время как настраиваемая строка этого не делает. | результаты поиска только результаты поиска |
resultSetSize | Целое число, Строка | Максимальный размер набора результатов. Например, large , small , filtered_cse , 10 Значение по умолчанию зависит от структуры и от того, настроен ли поисковый движок на поиск по всему интернету или только по указанным сайтам. | Любой |
safeSearch | Нить | Указывает, включен ли SafeSearch как для веб-поиска, так и для поиска изображений. Допустимые значения: off и active . | Любой |
Обратные звонки
Функции обратного вызова обеспечивают детальный контроль над инициализацией элемента поиска и процессами поиска. Они регистрируются в 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. Если parsetags установлен в explicit в __gcse , JavaScript элемента поиска оставляет отрисовку элементов поиска на усмотрение функции обратного вызова инициализации (как показано в разделе «Регистрация функций обратного вызова »). Это может использоваться для выбора элементов для отрисовки или для отсрочки отрисовки элементов до тех пор, пока они не понадобятся. Это также может переопределять атрибуты элементов; например, это может превратить поле поиска, настроенное через панель управления или атрибуты HTML по умолчанию для веб-поиска, в поле поиска изображений или указать, что запросы, отправленные через форму программируемой поисковой системы, выполняются в элементе, содержащем только результаты поиска. См. демонстрацию.
Роль функции обратного вызова инициализации определяется значением свойства parsetags объекта __gcse .
- Если значение параметра равно
onload, JavaScript элемента поиска автоматически отображает все элементы поиска на странице. Колбэк инициализации по-прежнему вызывается, но он не отвечает за отображение элементов поиска. - Если значение параметра
explicit, JavaScript элемента поиска не отображает элементы поиска. Функция обратного вызова может отображать их выборочно с помощью функцииrender()или отображать все элементы поиска с помощью функцииgo()
Приведённый ниже код демонстрирует, как отобразить поле поиска вместе с результатами поиска в div , используя explicit тег parsetag и функцию обратного вызова инициализации:
Нам нужно добавить элемент <div> с идентификатором в том месте, где мы хотим разместить код элемента поиска:
<div id="test"></div><div> . Обратите внимание, что он ссылается на test , id , который мы использовали для идентификации <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-элемент Search поддерживает шесть функций обратного вызова, работающих в потоке управления поиском. Функции обратного вызова поиска поставляются парами: функция обратного вызова для веб-поиска и соответствующая функция обратного вызова для поиска изображений:
- Начало поиска
- Для поиска изображений
- Для веб-поиска
- Результаты готовы
- Для поиска изображений
- Для веб-поиска
- Полученные результаты
- Для поиска изображений
- Для веб-поиска
Подобно функциям обратного вызова инициализации, функции обратного вызова поиска настраиваются с помощью записей в объекте __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 в Example Results Ready Callback заменяет стандартное отображение рекламных акций и результатов очень простой заменой.
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 в Example Results Rendered Callback добавляет фиктивный флажок « Сохранить» к каждому рекламному объявлению и результату.
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>Пример результата, отображаемого в виде обратного вызова: Открытие файлов определенных типов в новой вкладке/окне
Приведенный ниже пример функции обратного вызова может изменять ссылки в результатах поиска после их отображения, чтобы открывать определенный файл в новой вкладке/странице вместо текущего окна (например, PDF, Excel или Word). Это улучшает удобство просмотра, когда пользователи не хотят открывать файл в том же окне и переходить со страницы результатов.
В этом примере функции обратного вызова определяются ссылки на PDF-файлы в результатах поиска и устанавливается атрибут target="_blank" для этих ссылок, чтобы они открывались в новой вкладке. Для динамической обработки новых результатов при обновлении страницы используется объект MutationObserver . Примечание: вы можете заменить .pdf в handleSearchResults на любой другой тип файла в соответствии с вашими потребностями.
Этот пример обратного вызова не работает в макетах 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 это свойства объектов продвижения и результатов поиска . Здесь мы перечислим все возможные свойства. Наличие многих свойств зависит от деталей продвижения или результатов поиска.
{
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 управления элементами поиска (версия 2)
Объект google.search.cse.element публикует следующие статические функции:
| Функция | Описание | ||||||
|---|---|---|---|---|---|---|---|
.render(componentConfig, opt_componentConfig) | Отображает элемент поиска. Параметры
| ||||||
.go(opt_container) | Отображает все теги/классы элементов поиска в указанном контейнере. Параметры
| ||||||
.getElement(gname) | Получает объект элемента по gname . Если элемент не найден, возвращает null. Возвращаемый объект
Следующий код выполняет запрос "news" в элементе поиска "element1": var element = google.search.cse.element.getElement('element1'); element.execute('news'); | ||||||
.getAllElements() | Возвращает карту всех успешно созданных объектов элементов, ключом к которым является gname . |