您可以使用 HTML 标记将可编程搜索引擎组件(搜索框和搜索结果页)嵌入到您的网页和其他 Web 应用中。这些可编程搜索引擎元素由根据可编程搜索服务器存储的设置呈现的组件以及您进行的任何自定义组成。
所有 JavaScript 都是异步加载的,因此网页可以在浏览器提取可编程搜索引擎 JavaScript 时继续加载。
简介
本文档提供了一个用于将可编程搜索引擎元素添加到网页的基本模型,并介绍了该元素的可配置组件和灵活的 JavaScript API。
范围
本文档介绍了如何使用 Programmable Search Engine Control API 的专用功能和属性。
浏览器兼容性
如需查看可编程搜索引擎支持的浏览器的列表,请点击此处。
观众
本文档适用于希望向其网页添加 Google 可编程搜索功能的开发者。
可编程搜索元素
您可以使用 HTML 标记向自己的网页添加可编程搜索元素。每个元素至少包含一个组件:搜索框和/或搜索结果块。搜索框可采用以下任一方式接受用户输入:
- 在文本输入字段中输入了搜索查询
- 嵌入到网址中的查询字符串
- 程序化执行
此外,搜索结果块通过以下方式接受输入:
- 嵌入到网址中的查询字符串
- 程序化执行
可以使用以下类型的可编程搜索元素:
元素类型 | 组成部分 | 说明 |
---|---|---|
standard | <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
属性的值和用户查询字符串将用于创建结果网址。
请注意,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> 在检索对象时,如果多个组件具有相同的 |
不限 |
autoSearchOnLoad |
布尔值 | 指定是否按正在加载的网页的网址中嵌入的查询来执行搜索。请注意,网址中必须包含查询字符串才能执行自动搜索。默认值:true 。 |
不限 |
enableHistory |
布尔值 | 如果为 true ,则为浏览器后退按钮和前进按钮启用历史记录管理。观看演示。 |
searchbox 仅限搜索框 |
queryParameterName |
字符串 | 查询参数名称,例如 q (默认)或 query 。该标识符将嵌入到网址中(例如 http://www.example.com?q=lady+gaga)。请注意,仅指定查询参数名称不会在加载时触发自动搜索。网址中必须包含查询字符串才能执行自动搜索。 |
不限 |
resultsUrl |
网址 | 结果页的网址。(默认值为 Google 托管的网页。) | 仅限搜索框 |
newWindow |
布尔值 | 指定是否在新窗口中打开结果页面。
默认值:false 。 |
仅限搜索框 |
ivt |
布尔值 |
利用此参数,您可以提供一个布尔值,告知 Google 您希望允许针对已同意和未同意的流量使用仅流量无效 Cookie 和本地存储的广告。
默认值: 用法示例: |
搜索结果 仅限搜索结果 |
mobileLayout |
字符串 |
指定是否应针对移动设备使用移动设备布局样式。
默认值: 用法示例: |
不限 |
自动补全 | |||
enableAutoComplete |
布尔值 | 仅当在“可编程搜索引擎”控制面板中启用了自动补全功能后,该功能才可用。
true 可启用自动补全功能。 |
不限 |
autoCompleteMaxCompletions |
整数 | 要显示的自动补全查询的数量上限。 | searchbox 仅限搜索框 |
autoCompleteMaxPromotions |
整数 | 自动补全中显示的促销活动数量上限。 | searchbox 仅限搜索框 |
autoCompleteValidLanguages |
字符串 | 应启用自动补全功能的语言的逗号分隔列表。 支持的语言。 | searchbox 仅限搜索框 |
优化条件 | |||
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 |
字符串 | 仅当在“可编程搜索引擎”控制面板中启用
图片搜索后,此选项才可用。
返回指定尺寸的图片,其尺寸可以是 | 不限 |
image_sort_by |
字符串 | 仅当在“可编程搜索引擎”控制面板中启用
图片搜索后,此选项才可用。
使用日期或其他结构化内容对结果进行排序。 如需按相关性排序,请使用空字符串 (image_sort_by=")。 用法示例: | 不限 |
image_type |
字符串 | 仅当在“可编程搜索引擎”控制面板中启用
图片搜索后,此选项才可用。
将搜索范围限制为特定类型的图片。
支持的值包括 | 不限 |
网页搜索 | |||
disableWebSearch |
布尔值 | 如果为 true ,则停用网页搜索。通常仅当已在“可编程搜索引擎”控制面板中启用
图片搜索后,才会使用此类型。 |
搜索结果 仅限搜索结果 |
webSearchQueryAddition |
字符串 | 使用逻辑 OR 向搜索查询添加了额外字词。
用法示例: |
不限 |
webSearchResultSetSize |
整数、字符串 | 结果集的大小上限。适用于图片搜索和网页搜索。默认值取决于布局以及可编程搜索引擎是配置为搜索整个网络还是仅搜索指定的网站。可接受的值包括:
|
不限 |
webSearchSafesearch |
字符串 |
指定是否为网页搜索结果启用SafeSearch。接受的值为 off 和 active 。 |
不限 |
as_filetype |
字符串 | 将结果限制为指定扩展名的文件。您可以在 Search Console 帮助中心内找到 Google 可编入索引的文件类型列表。 | 不限 |
as_oq |
字符串 | 使用逻辑“或”过滤搜索结果。
如果您想要获得包含“term1”或“term2”的搜索结果,请使用以下示例: |
不限 |
as_rights |
字符串 | 基于许可的过滤条件。
支持的值包括 如需了解典型组合,请参阅 https://wiki.creativecommons.org/wiki/CC_Search_integration。 | 不限 |
as_sitesearch |
字符串 | 将结果限制为特定网站的网页。
用法示例: |
不限 |
cr |
字符串 | 将搜索结果限制为来自特定国家/地区的文档。
用法示例: |
不限 |
filter |
字符串 | 自动过滤搜索结果。
支持的值:0/1 用法示例: |
不限 |
gl |
字符串 | 提升来源国家/地区与参数值相匹配的搜索结果的排名。
此选项只能与语言值设置结合使用。 用法示例: |
不限 |
lr |
字符串 | 将搜索结果限制为以特定语言编写的文档。
用法示例: |
不限 |
sort_by |
字符串 | 使用日期或其他结构化内容对结果进行排序。属性值必须是可编程搜索 egnine 的结果排序设置中提供的选项之一。
要按相关性排序,请使用空字符串 (sort_by=")。 用法示例: |
不限 |
搜索结果 | |||
enableOrderBy |
布尔值 | 启用按相关性、日期或标签对结果进行排序。 | 不限 |
linkTarget |
字符串 | 设置链接目标。默认值:_blank 。 |
搜索结果 仅限搜索结果 |
noResultsString |
字符串 | 指定没有与查询匹配的结果时显示的默认文本。 默认结果字符串可用于以所有受支持的语言显示本地化字符串,而自定义结果字符串则不然。 | 搜索结果 仅限搜索结果 |
resultSetSize |
整数、字符串 | 结果集的大小上限。例如,large 、small 、filtered_cse 、10 。默认值取决于布局以及引擎是配置为搜索整个网络还是仅搜索指定的网站。 |
不限 |
safeSearch |
字符串 | 指定是否为网页搜索和图片搜索启用
安全搜索。接受的值为 off 和 active 。 |
不限 |
回调
回调支持详细控制搜索元素初始化和搜索过程。它们通过全局 __gcse
对象注册到搜索元素 JavaScript 中。注册回调说明了如何注册所有受支持的回调。
初始化回调
搜索元素 JavaScript 在 DOM 中渲染搜索元素之前,系统会调用初始化回调函数。如果在 __gcse
中将 parsetags
设置为 explicit
,搜索元素 JavaScript 会将搜索元素渲染留给初始化回调(如注册回调中所示)。
它可用于选择要渲染的元素,或将渲染元素推迟到需要用到时。它还可以替换这些元素的属性;例如,它可将通过控制台或 HTML 属性配置的搜索框改为默认使用网页搜索作为图片搜索框,或者指定通过可编程搜索引擎表单提交的查询在仅限搜索结果的元素中执行。
观看演示。
初始化回调的作用由 __gcse
的 parsetags
属性的值控制。
- 如果此参数的值为
onload
,则搜索元素 JavaScript 会自动在网页上呈现所有搜索元素。系统仍会调用初始化回调,但它不负责呈现搜索元素。 - 如果其值为
explicit
,则搜索元素 JavaScript 不会呈现搜索元素。回调可能会使用render()
函数选择性地呈现这些元素,或使用go()
函数呈现所有搜索元素
以下代码演示了如何使用 explicit
解析标记和初始化回调在 div
中呈现搜索框以及搜索结果:
搜索回调
搜索元素 JavaScript 支持 6 个在搜索控制流中运行的回调。 搜索回调成对出现,即网页搜索回调和匹配的图片搜索回调:
- 开始搜索
- 图片搜索用
- 网页搜索
- 已有结果
- 图片搜索用
- 网页搜索
- 结果已呈现
- 图片搜索用
- 网页搜索
与初始化回调一样,搜索回调也是使用 __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
添加到查询中,具体取决于当前时间。
在 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,搜索元素通常用于放置促销信息和搜索结果的位置。通常,搜索元素 JavaScript 会处理此 div 的填充操作,但此回调可能会选择停止自动呈现结果,并使用此
div
来呈现结果本身。
如果此回调返回 true
值,则搜索元素 JavaScript 会跳至其页面页脚。
结果就绪回调示例
示例结果就绪回调中的示例 resultsReady
回调通过一个非常简单的替换替换了置顶和结果的默认呈现方式。
图片/网页搜索结果呈现的回调
系统会在搜索元素 JavaScript 呈现页脚之前立即调用这些回调。示例用例包括添加搜索元素未显示的结果内容的回调(如“保存此”复选框或未自动呈现的信息),或者添加“获取更多信息”按钮的回调。
如果结果渲染的回调需要 results ready callback 的 promos
和 results
参数中包含的信息,它可以在两者之间传递该信息,如下所示:
callback(gname, query, promoElts, resultElts);
gname
- 搜索元素的标识字符串
query
- 搜索字符串。
promoElts
- 一个包含促销信息的 DOM 元素的数组。
resultElts
- 一个包含结果的 DOM 元素的数组。
没有返回值。
呈现的回调的结果示例
结果呈现回调示例中的示例 resultsRendered
回调为每个置顶结果和结果添加了一个虚拟的 Keep 复选框。
如果呈现的结果回调需要传递给 results ready callback 的信息,那么可以在回调之间传递这些数据。以下示例展示了将 richSnippet
中的评分值从 results ready callback 传递给结果呈现回调函数的多种方式之一。
更多回调示例
如需查看其他回调示例,请参阅更多回调示例文档。
置顶和结果属性
使用 JSDoc 表示法,这些是 promotion 和 result 对象的属性。 我们在这里列出可能存在的所有属性。其中许多属性的存在取决于宣传或搜索结果的详细信息。
results 中的 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 进行键控。 |