您可以使用 HTML 标记将可编程搜索引擎组件(搜索框和搜索结果页)嵌入到网页和其他 Web 应用中。这些可编程搜索引擎元素由根据可编程搜索服务器存储的设置以及您所做的任何自定义设置呈现的组件组成。
所有 JavaScript 均以异步方式加载,这使得网页在浏览器提取可编程搜索引擎 JavaScript 时能够继续加载。
简介
本文档提供了一个基本模型,用于向网页添加可编程搜索引擎元素,并说明了该元素的可配置组件和灵活的 JavaScript API。
范围
本文档介绍了如何使用可编程搜索引擎控制 API 特有的函数和属性。
浏览器兼容性
如需查看可编程搜索引擎支持的浏览器列表,请点击此处。
观众
本文档适用于希望在其网页中添加 Google 可编程搜索功能的开发者。
可编程搜索元素
您可以使用 HTML 标记向网页添加可编程搜索元素。每个元素至少包含一个组件:搜索框、搜索结果块或两者兼有。搜索框接受用户以以下任意方式输入的内容:
- 在文本输入字段中输入的搜索查询
- 嵌入在网址中的查询字符串
- 程序化执行
此外,搜索结果块还接受以下输入:
- 嵌入在网址中的查询字符串
- 程序化执行
可用的可编程搜索元素类型如下:
| 元素类型 | 组件 | 说明 |
|---|---|---|
| standard | <div class="gcse-search"> |
搜索框和搜索结果显示在同一 <div> 中。 |
| 双列 | <div class="gcse-searchbox"> 和 <div class="gcse-searchresults"> |
双列布局,一侧显示搜索结果,另一侧显示搜索框。如果您打算在网页中以双列模式插入多个元素,可以使用 gname 属性将搜索框与搜索结果块配对。 |
| 仅限搜索框 | <div class="gcse-searchbox-only"> |
独立搜索框。 |
| searchresults-only | <div class="gcse-searchresults-only"> |
一个独立的搜索结果块。 |
您可以向网页添加任意数量的有效搜索元素。对于双列模式,必须包含所有必需的组件(搜索框和搜索结果块)。
下面是一个简单的搜索元素示例:
<!-- Put the following javascript before the closing </head> tag and replace 123456 with your own Programmable Search Engine ID. --> <script async src="https://cse.google.com/cse.js?cx=123456"></script> <!-- Place this tag where you want both of the search box and the search results to render --> <div class="gcse-search"></div>
使用可编程搜索元素组合不同的布局选项
在可编程搜索引擎控制面板的“外观”页面上,您可以选择以下布局选项。以下是有关使用可编程搜索元素组合布局选项的一些一般准则。如需查看其中任一选项的演示,请点击相应链接。
| 选项 | 组件 |
|---|---|
| 全宽度 | <div class="gcse-search"> |
| 紧凑 | <div class="gcse-search"> |
| 双列 | <div class="gcse-searchbox">、<div class="gcse-searchresults"> |
| 双页 | <div class="gcse-searchbox-only">位于第一页,<div class="gcse-searchresults-only">(或其他组件)位于第二页。 |
| 仅限结果 | <div class="gcse-searchresults-only"> |
| Google 托管 | <div class="gcse-searchbox-only"> |
自定义可编程搜索元素
如需自定义颜色、字体或链接样式,请前往可编程搜索引擎的“外观”页面。
您可以使用可选属性覆盖在可编程搜索引擎控制面板中创建的配置。这样一来,您就可以打造特定于页面的搜索体验。
例如,以下代码会创建一个搜索框,该搜索框会在新窗口中打开结果页面 (http://www.example.com?search=lady+gaga)。queryParameterName 属性的值以及用户查询字符串用于创建结果网址。
请注意,queryParameterName 属性带有 data- 前缀。所有属性都必须包含此前缀。
<div class="gcse-searchbox-only" data-resultsUrl="http://www.example.com" data-newWindow="true" data-queryParameterName="search">
如果您已使用可编程搜索引擎控制面板启用自动补全或优化等功能,则可以使用属性自定义这些功能。您使用这些属性指定的任何自定义设置都会替换控制面板中的设置。以下示例创建了一个双列搜索元素,具有以下功能:
- 已启用历史记录管理
- 显示的自动补全建议数量上限设置为 5
- 优化条件以链接的形式显示。
<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5"> <div class="gcse-searchresults" data-refinementStyle="link">
支持的属性
| 属性 | 类型 | 说明 | 组件 |
|---|---|---|---|
| 常规 | |||
gname |
字符串 | (可选)搜索元素对象的名称。名称用于按名称检索关联的组件,或将 searchbox 组件与 searchresults 组件配对。如果未提供,可编程搜索引擎将根据网页上组件的顺序自动生成 gname。例如,第一个未命名的 searchbox-only 具有 gname“searchbox-only0”,第二个具有 gname“searchbox-only1”,依此类推。
请注意,对于双列布局中的组件,自动生成的 gname 将为 two-column。以下示例使用 gname storesearch 将 searchbox 组件与 searchresults 组件相关联:
<div class="gcse-searchbox" data-gname="storesearch"></div> <div class="gcse-searchresults" data-gname="storesearch"></div> 检索对象时,如果多个组件具有相同的 |
不限 |
autoSearchOnLoad |
布尔值 | 指定是否根据正在加载的网页的网址中嵌入的查询执行搜索。请注意,网址中必须包含查询字符串才能执行自动搜索。默认值:true。 |
不限 |
enableHistory |
布尔值 | 如果为 true,则为浏览器“后退”和“前进”按钮启用历史记录管理。观看演示。 |
搜索框 仅限搜索框 |
queryParameterName |
字符串 | 查询参数名称,例如 q(默认)或 query。该参数将嵌入到网址中(例如,http://www.example.com?q=lady+gaga)。请注意,仅指定查询参数名称不会在加载时触发自动搜索。网址中必须包含查询字符串才能执行自动搜索。 |
不限 |
resultsUrl |
网址 | 结果页面的网址。(默认值为 Google 托管的网页。) | 仅限搜索框 |
newWindow |
布尔值 | 指定结果页面是否在新窗口中打开。
默认值:false。 |
仅限搜索框 |
ivt |
布尔值 |
您可以使用此参数提供一个布尔值,告知 Google 您希望允许广告在已征得用户同意和未征得用户同意的流量中使用仅用于检测无效流量的 Cookie 和本地存储。
默认值: 用法示例: |
searchresults searchresults-only |
mobileLayout |
字符串 |
指定是否应将移动布局样式用于移动设备。
默认值: 用法示例: |
不限 |
| 自动补全 | |||
enableAutoComplete |
布尔值 | 仅当在可编程搜索引擎控制台中启用了自动补全功能时才可用。
true 用于启用自动补全功能。 |
不限 |
autoCompleteMaxCompletions |
整数 | 要显示的最大自动补全数量。 | 搜索框 仅限搜索框 |
autoCompleteMaxPromotions |
整数 | 自动补全中显示的最大促销数量。 | 搜索框 仅限搜索框 |
autoCompleteValidLanguages |
字符串 | 以英文逗号分隔的语言列表,用于指定应为哪些语言启用自动补全功能。 支持的语言。 | 搜索框 仅限搜索框 |
| 优化 | |||
defaultToRefinement |
字符串 | 仅当在可编程搜索引擎控制台中创建了优化条件时才可用。指定要显示的默认细化标签。注意:Google 托管布局不支持此属性。 | 不限 |
refinementStyle |
字符串 | 可接受的值为 tab(默认值)和 link。
仅当图片搜索已停用,或者图片搜索已启用但网页搜索已停用时,才支持 link。 |
searchresults searchresults-only |
| 图片搜索 | |||
enableImageSearch |
布尔值 | 仅当在可编程搜索引擎控制台中启用了
图片搜索时才可用。
如果为 |
searchresults searchresults-only |
defaultToImageSearch |
布尔值 | 仅当在可编程搜索引擎控制台中启用了
图片搜索时才可用。
如果值为 |
不限 |
imageSearchLayout |
字符串 | 仅当在可编程搜索引擎控制台中启用了
图片搜索时才可用。
指定图片搜索结果页面的布局。可接受的值包括 |
searchresults searchresults-only |
imageSearchResultSetSize |
整数、字符串 | 仅当在可编程搜索引擎控制台中启用了
图片搜索时才可用。
指定图片搜索的搜索结果集的最大大小。
例如, |
不限 |
image_as_filetype |
字符串 | 仅当在可编程搜索引擎控制台中启用了
图片搜索时才可用。
将结果限制为具有指定扩展名的文件。 支持的扩展名包括 | 不限 |
image_as_oq |
字符串 | 仅当在可编程搜索引擎控制台中启用了
图片搜索时才可用。
使用逻辑 OR 过滤搜索结果。 如果您希望搜索结果包含“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 |
字符串 | 使用逻辑运算符“OR”添加到搜索查询中的额外字词。
用法示例: |
不限 |
webSearchResultSetSize |
整数、字符串 | 结果集的最大规模。适用于图片搜索和网页搜索。默认值取决于布局以及可编程搜索引擎是配置为搜索整个网络还是仅搜索指定网站。可接受的值包括:
|
不限 |
webSearchSafesearch |
字符串 |
指定是否为网页搜索结果启用SafeSearch。可接受的值为 off 和 active。
|
不限 |
as_filetype |
字符串 | 将结果限制为具有指定扩展名的文件。如需查看 Google 可编入索引的文件类型列表,请访问 Search Console 帮助中心。 | 不限 |
as_oq |
字符串 | 使用逻辑 OR 过滤搜索结果。
如果您希望搜索结果包含“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 |
整数、字符串 | 结果集的最大规模。例如,large、small、filtered_cse、10。 默认值取决于布局以及引擎是配置为搜索整个网络还是仅搜索指定网站。 |
不限 |
safeSearch |
字符串 | 指定是否为网页搜索和图片搜索启用
安全搜索。可接受的值为 off 和 active。 |
不限 |
回调
回调支持对搜索元素初始化和搜索过程进行详细控制。
它们通过全局 __gcse 对象向 Search Element 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,
},
},
};
初始化回调
初始化回调会在搜索元素 JavaScript 在 DOM 中渲染搜索元素之前调用。如果 __gcse 中的 parsetags 设置为 explicit,则搜索元素 JavaScript 会将渲染搜索元素的工作交给初始化回调(如注册回调中所述)。
这可能用于选择要渲染的元素,或延迟渲染元素,直到需要时才渲染。它还可以替换元素的属性;例如,它可以将通过控制面板或 HTML 属性配置为默认进行网络搜索的搜索框转换为图片搜索框,或者指定通过可编程搜索引擎表单提交的查询在仅显示搜索结果的元素中执行。
观看演示。
初始化回调的角色由 __gcse 的 parsetags 属性的值控制。
- 如果其值为
onload,则搜索元素 JavaScript 会自动呈现网页上的所有搜索元素。初始化回调仍会被调用,但它不负责渲染搜索元素。 - 如果其值为
explicit,则搜索元素 JavaScript 不会呈现搜索元素。回调可以使用render()函数选择性地呈现它们,也可以使用go()函数呈现所有搜索元素
以下代码演示了如何使用 explicit 解析标记和初始化回调在 div 中呈现搜索框以及搜索结果:
我们需要包含一个具有 ID 值的 <div>,我们希望在其中放置搜索元素代码:
<div id="test"></div><div> 之后。请注意,它引用了 test,即我们用于标识 <div> 的 idconst 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 支持在搜索控制流中运行的六个回调。 搜索回调成对出现,一个用于网页搜索,另一个用于匹配的图片搜索:
- 搜索入门
- 对于图片搜索
- 对于网络搜索
- 结果已准备就绪
- 对于图片搜索
- 对于网络搜索
- 渲染结果
- 对于图片搜索
- 对于网络搜索
与初始化回调类似,搜索回调也是使用 __gcse 对象中的条目进行配置的。这种情况发生在搜索元素 JavaScript 启动时。启动后对 __gcse 的修改会被忽略。
每个回调都会将搜索元素的 gName 作为实参传递。
当网页包含多次搜索时,gname 会很有用。使用 data-gname 属性为搜索元素提供 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- 一个位于 DOM 中的 HTML div,搜索元素通常会将促销信息和搜索结果放置在该 div 中。通常,搜索元素 JavaScript 会处理填充此 div 的操作,但此回调可以选择停止自动呈现结果,并使用此
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 对象中的众多方法之一。
图片/网页搜索结果呈现回调
这些回调会在搜索元素 JavaScript 呈现网页页脚之前立即调用。用例示例包括:添加搜索元素未显示的搜索结果内容(例如“保存此内容”复选框或未自动呈现的信息)的回调,或添加“了解详情”按钮的回调。
如果渲染结果回调需要结果就绪回调的 promos 和 results 参数中的信息,则可以在它们之间传递该信息,如下所示:
callback(gname, query, promoElts, resultElts);
gname- 搜索元素的标识字符串
query- 搜索字符串。
promoElts- 包含促销信息的 DOM 元素数组。
resultElts- 包含结果的 DOM 元素数组。
没有返回值。
示例结果呈现回调
示例结果呈现回调中的示例 resultsRendered 回调会向每个宣传广告和结果添加一个虚拟的保留复选框。
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 链接,并为 PDF 链接设置 target="_blank" 属性,以便在新标签页中打开这些链接。如果网页更新,MutationObserver 可用于动态处理新结果。注意:您可以根据自己的需求,将 handleSearchResults 中的 .pdf 替换为任何其他文件类型。
此回调示例不适用于 Google 托管布局和叠加布局。
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 键控。 |