Programmable Search Element Control API

您可以使用 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-onlygname 为“searchbox-only0”,第二个的 gname 为“seachbox-only1”,依此类推。 请注意,为两列布局中的组件自动生成的 gname 将为 two-column。以下示例使用 gname storesearchsearchbox 组件与 searchresults 组件相关联:
<div class="gcse-searchbox" data-gname="storesearch"></div>
<div class="gcse-searchresults" data-gname="storesearch"></div>

在检索对象时,如果多个组件具有相同的 gname,则可编程搜索引擎会使用网页上的最后一个组件。

不限
autoSearchOnLoad 布尔值 指定是否按正在加载的网页的网址中嵌入的查询来执行搜索。请注意,网址中必须包含查询字符串才能执行自动搜索。默认值:true 不限
enableHistory 布尔值 如果为 true,则为浏览器后退按钮和前进按钮启用历史记录管理。观看演示

searchbox

仅限搜索框

queryParameterName 字符串 查询参数名称,例如 q(默认)或 query。该标识符将嵌入到网址中(例如 http://www.example.com?q=lady+gaga)。请注意,仅指定查询参数名称不会在加载时触发自动搜索。网址中必须包含查询字符串才能执行自动搜索。 不限
resultsUrl 网址 结果页的网址。(默认值为 Google 托管的网页。) 仅限搜索框
newWindow 布尔值 指定是否在新窗口中打开结果页面。 默认值:false 仅限搜索框
ivt 布尔值

利用此参数,您可以提供一个布尔值,告知 Google 您希望允许针对已同意和未同意的流量使用仅流量无效 Cookie 和本地存储的广告。

true如果此参数不存在或您设置为“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 整数 要显示的自动补全查询的数量上限。

searchbox

仅限搜索框

autoCompleteMaxPromotions 整数 自动补全中显示的促销活动数量上限。

searchbox

仅限搜索框

autoCompleteValidLanguages 字符串 应启用自动补全功能的语言的逗号分隔列表。 支持的语言。

searchbox

仅限搜索框

优化条件
defaultToRefinement 字符串 只有在“可编程搜索引擎”控制面板中创建了优化后,才能使用该选项。指定要显示的默认优化标签。注意:Google 托管的布局不支持此属性。 不限
refinementStyle 字符串 可接受的值包括 tab(默认值)和 link。 仅当图片搜索被停用,或者图片搜索已启用但网页搜索处于停用状态时,link 才受支持。

搜索结果

仅限搜索结果

图片搜索
enableImageSearch 布尔值 仅当在“可编程搜索引擎”控制面板中启用 图片搜索后,此选项才可用。

如果为 true,则启用图片搜索。图片结果将显示在单独的标签页中。

搜索结果

仅限搜索结果

defaultToImageSearch 布尔值 仅当在“可编程搜索引擎”控制面板中启用 图片搜索后,此选项才可用。

如果为 true,则默认情况下,搜索结果页会显示图片搜索结果。网页搜索结果将在单独的标签页上显示。

不限
imageSearchLayout 字符串 仅当在“可编程搜索引擎”控制面板中启用 图片搜索后,此选项才可用。

指定图片搜索结果页的布局。可接受的值包括 classiccolumnpopup

搜索结果

仅限搜索结果

imageSearchResultSetSize 整数、字符串 仅当在“可编程搜索引擎”控制面板中启用 图片搜索后,此选项才可用。

指定图片搜索的搜索结果集的大小上限。例如,largesmallfiltered_cse10

不限
image_as_filetype 字符串 仅当在“可编程搜索引擎”控制面板中启用 图片搜索后,此选项才可用。

将结果限制为指定扩展名的文件。

支持的扩展项包括 jpggifpngbmpsvgwebpicoraw

不限

image_as_oq 字符串 仅当在“可编程搜索引擎”控制面板中启用 图片搜索后,此选项才可用。

使用逻辑“或”过滤搜索结果。

如果您想要获得包含“term1”或“term2”的搜索结果,请使用以下示例:<div class="gcse-search" data-image_as_oq="term1 term2"></div>

不限

image_as_rights 字符串 仅当在“可编程搜索引擎”控制面板中启用 图片搜索后,此选项才可用。

基于许可的过滤条件。

支持的值包括 cc_publicdomaincc_attributecc_sharealikecc_noncommercialcc_nonderived 以及这些项的组合。

请参阅典型组合

不限

image_as_sitesearch 字符串 仅当在“可编程搜索引擎”控制面板中启用 图片搜索后,此选项才可用。

将结果限制为特定网站的网页。

用法示例:<div class="gcse-search" data-image_as_sitesearch="example.com"></div>

不限

image_colortype 字符串 仅当在“可编程搜索引擎”控制面板中启用 图片搜索后,此选项才可用。

将搜索范围限制为黑白图片(单色)、灰度图片或彩色图片。支持的值包括 monograycolor

不限

image_cr 字符串 仅当在“可编程搜索引擎”控制面板中启用 图片搜索后,此选项才可用。

将搜索结果限制为来自特定国家/地区的文档。

支持的值

不限

image_dominantcolor 字符串 仅当在“可编程搜索引擎”控制面板中启用 图片搜索后,此选项才可用。

将搜索范围限制为特定主色的图片。 支持的值包括 redorangeyellowgreentealbluepurplepinkwhitegrayblackbrown

不限

image_filter 字符串 仅当在“可编程搜索引擎”控制面板中启用 图片搜索后,此选项才可用。

自动过滤搜索结果。

支持的值:0/1

用法示例:<div class="gcse-search" data-image_filter="0"></div>

不限

image_gl 字符串 仅当在“可编程搜索引擎”控制面板中启用 图片搜索后,此选项才可用。 提升来源国家/地区与参数值相匹配的搜索结果的排名。

支持的值

不限

image_size 字符串 仅当在“可编程搜索引擎”控制面板中启用 图片搜索后,此选项才可用。

返回指定尺寸的图片,其尺寸可以是 iconsmallmediumlargexlargexxlargehuge.

不限

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 字符串 使用逻辑 OR 向搜索查询添加了额外字词。

用法示例:<div class="gcse-search" data-webSearchQueryAddition="term1 term2"></div>

不限
webSearchResultSetSize 整数、字符串 结果集的大小上限。适用于图片搜索和网页搜索。默认值取决于布局以及可编程搜索引擎是配置为搜索整个网络还是仅搜索指定的网站。可接受的值包括:
  • 1 到 20 之间的整数
  • small:请求较小的结果集,通常每页 4 个结果。
  • large:请求大型结果集,通常为每页 8 个结果。
  • filtered_cse:每页最多请求 10 个结果,最多 10 个页面或 100 个结果。
不限
webSearchSafesearch 字符串 指定是否为网页搜索结果启用SafeSearch。接受的值为 offactive 不限
as_filetype 字符串 将结果限制为指定扩展名的文件。您可以在 Search Console 帮助中心内找到 Google 可编入索引的文件类型列表。

不限

as_oq 字符串 使用逻辑“或”过滤搜索结果。

如果您想要获得包含“term1”或“term2”的搜索结果,请使用以下示例:<div class="gcse-search" data-as_oq="term1 term2"></div>

不限
as_rights 字符串 基于许可的过滤条件。

支持的值包括 cc_publicdomaincc_attributecc_sharealikecc_noncommercialcc_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 字符串 使用日期或其他结构化内容对结果进行排序。属性值必须是可编程搜索 egnine 的结果排序设置中提供的选项之一。

要按相关性排序,请使用空字符串 (sort_by=")。

用法示例:<div class="gcse-search" data-sort_by="date"></div>

不限
搜索结果
enableOrderBy 布尔值 启用按相关性、日期或标签对结果进行排序。 不限
linkTarget 字符串 设置链接目标。默认值:_blank

搜索结果

仅限搜索结果

noResultsString 字符串 指定没有与查询匹配的结果时显示的默认文本。 默认结果字符串可用于以所有受支持的语言显示本地化字符串,而自定义结果字符串则不然。

搜索结果

仅限搜索结果

resultSetSize 整数、字符串 结果集的大小上限。例如,largesmallfiltered_cse10。默认值取决于布局以及引擎是配置为搜索整个网络还是仅搜索指定的网站。 不限
safeSearch 字符串 指定是否为网页搜索和图片搜索启用 安全搜索。接受的值为 offactive 不限

回调

回调序列图
搜索元素 JavaScript 中的回调序列图

回调支持详细控制搜索元素初始化和搜索过程。它们通过全局 __gcse 对象注册到搜索元素 JavaScript 中。注册回调说明了如何注册所有受支持的回调。

注册回调

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

初始化回调

搜索元素 JavaScript 在 DOM 中渲染搜索元素之前,系统会调用初始化回调函数。如果在 __gcse 中将 parsetags 设置为 explicit,搜索元素 JavaScript 会将搜索元素渲染留给初始化回调(如注册回调中所示)。 它可用于选择要渲染的元素,或将渲染元素推迟到需要用到时。它还可以替换这些元素的属性;例如,它可将通过控制台或 HTML 属性配置的搜索框改为默认使用网页搜索作为图片搜索框,或者指定通过可编程搜索引擎表单提交的查询在仅限搜索结果的元素中执行。 观看演示。

初始化回调的作用由 __gcseparsetags 属性的值控制。

  • 如果此参数的值为 onload,则搜索元素 JavaScript 会自动在网页上呈现所有搜索元素。系统仍会调用初始化回调,但它不负责呈现搜索元素。
  • 如果其值为 explicit,则搜索元素 JavaScript 不会呈现搜索元素。回调可能会使用 render() 函数选择性地呈现这些元素,或使用 go() 函数呈现所有搜索元素

以下代码演示了如何使用 explicit 解析标记和初始化回调在 div 中呈现搜索框以及搜索结果:

初始化回调示例

我们需要添加一个具有 ID 值的 <div>,以便在其中放置搜索元素代码:

    <div id="test"></div>
将此 JavaScript 添加到 <div> 之后。请注意,它引用了 test,即我们用于标识 <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
};
id

添加此 HTML 以开始加载搜索元素。将 src 子句中的 cx 值替换为您自己的 cx

<script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>

搜索回调

搜索元素 JavaScript 支持 6 个在搜索控制流中运行的回调。 搜索回调成对出现,即网页搜索回调和匹配的图片搜索回调:

  • 开始搜索
    • 图片搜索用
    • 网页搜索
  • 已有结果
    • 图片搜索用
    • 网页搜索
  • 结果已呈现
    • 图片搜索用
    • 网页搜索

初始化回调一样,搜索回调也是使用 __gcse 对象中的条目进行配置的。搜索元素 JavaScript 启动时会发生这种情况。系统会忽略启动后对 __gcse 的修改。

系统会向每个回调传递搜索元素的 gName 作为参数。 当一个网页中包含多项搜索时,gname 非常有用。使用 data-gname 属性为搜索元素提供 gname 值:

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

如果 HTML 无法识别 gname,则搜索元素 JavaScript 会生成一个值,该值将在修改 HTML 之前保持不变。

图片/网页搜索启动回调

系统会在搜索元素 JavaScript 从其服务器请求搜索结果之前立即调用搜索启动回调函数。例如,使用一天中的当地时间来控制对查询的更改。

searchStartingCallback(gname, query)
gname
搜索元素的标识字符串
query
用户输入的值(可能已由搜索元素 JavaScript 修改)。

该回调返回的值应该用作此搜索的查询。如果它返回空字符串,系统会忽略返回值,并且调用方会使用未经修改的查询。

或者,您也可以将回调函数放在 __gcse 对象中,或使用 JavaScript 向该对象动态添加回调函数:

window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};
搜索启动回调函数示例

示例搜索启动回调中的示例搜索启动回调会将 morningafternoon 添加到查询中,具体取决于当前时间。

搜索启动回调示例
    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,搜索元素通常用于放置促销信息和搜索结果的位置。通常,搜索元素 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 呈现页脚之前立即调用这些回调。示例用例包括添加搜索元素未显示的结果内容的回调(如“保存此”复选框或未自动呈现的信息),或者添加“获取更多信息”按钮的回调。

如果结果渲染的回调需要 results ready callbackpromosresults 参数中包含的信息,它可以在两者之间传递该信息,如下所示:

callback(gname, query, promoElts, resultElts);
gname
搜索元素的标识字符串
query
搜索字符串。
promoElts
一个包含促销信息的 DOM 元素的数组。
resultElts
一个包含结果的 DOM 元素的数组。

没有返回值。

呈现的回调的结果示例

结果呈现回调示例中的示例 resultsRendered 回调为每个置顶结果和结果添加了一个虚拟的 Keep 复选框。

渲染结果回调示例
myWebResultsRenderedCallback = function(name, q, promos, results) {
    for (const div of promos.concat(results)) {
      const innerDiv = document.createElement('div');
      innerDiv.appendChild(document.createTextNode('Keep: '));
      const checkBox = document.createElement('input');
      checkBox.type = 'checkbox';
      checkBox.name = 'save';
      innerDiv.appendChild(checkBox);
      div.insertAdjacentElement('afterbegin', innerDiv);
    }
  };

window.__gcse: 中安装此回调

window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    rendered: 'myWebResultsRenderedCallback',
  },
};
  <script async
    src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>

如果呈现的结果回调需要传递给 results ready callback 的信息,那么可以在回调之间传递这些数据。以下示例展示了将 richSnippet 中的评分值从 results ready callback 传递给结果呈现回调函数的多种方式之一。

与结果呈现回调合作的结果就绪回调示例
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 表示法,这些是 promotionresult 对象的属性。 我们在这里列出可能存在的所有属性。其中许多属性的存在取决于宣传或搜索结果的详细信息。

促销属性
{
  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,
}

results 中的 richSnippet 采用对象数组的松散类型。此数组中条目的值由在每个搜索结果的网页上找到的结构化数据控制。例如,评价网站可能包含会将以下数组条目添加到 richSnippet 的结构化数据:

'review': {
  'ratingstars': '3.0',
  'ratingcount': '1024',
},

Programmable Search Element Control API (V2)

google.search.cse.element 对象会发布以下静态函数:

函数 说明
.render(componentConfig, opt_componentConfig) 呈现搜索元素。

参数

名称 说明
componentConfig 可编程搜索元素组件的配置。指定以下内容:
  • div (string|Element):将在其中呈现可编程搜索元素的 <div>div 元素的 id
  • tag(字符串):要渲染的组件的类型。(如果提供了 opt_componentConfig,则 tag 属性的值必须为 searchbox。)允许的值包括:
    • search:搜索框和搜索结果一起显示
    • searchbox:可编程搜索元素的搜索框组件。
    • searchbox-only:一个独立的搜索框,将与 opt_componentConfig 指定的两列布局指定的搜索结果块配对。
    • searchresults-only:一个独立的搜索结果块。嵌入在网址中的查询参数或通过程序化执行来触发搜索。
  • gname(字符串):(可选)此组件的唯一名称。如果未提供,可编程搜索引擎将自动生成 gname
  • attributes(对象):采用键值对形式的可选属性。支持的属性
opt_componentConfig 可选。第二个组件配置参数。在 TWO_COLUMN 模式下用于提供 searchresults 组件。指定以下内容:
  • div(字符串):要在其中渲染元素的 <div>div 元素的 id
  • tag(字符串):要渲染的组件的类型。如果提供 opt_componentConfig,则 tag 属性的值必须为 searchresults。此外,componentConfig tag 属性的值必须为 searchbox
  • gname(字符串):(可选)此组件的唯一名称。如果未提供,可编程搜索引擎会自动为此组件生成 gname。如果提供,则它必须与 componentConfig 中的 gname 匹配。
  • attributes(对象):采用键值对形式的可选属性。 支持的属性。
.go(opt_container) 呈现指定容器中的所有搜索元素标记/类。

参数

名称 说明
opt_container 包含要呈现的搜索元素组件的容器。请指定容器(字符串)的 ID 或元素本身。如果省略此参数,系统将呈现网页的 body 标记中的所有可编程搜索元素组件。
.getElement(gname) 通过 gname 获取元素对象。如果未找到,则返回 null。

返回的 element 对象具有以下属性:

  • gname:元素对象的名称。如果未提供,可编程搜索引擎会自动为该对象生成 gname了解详情
  • type:元素的类型。
  • uiOptions:用于渲染元素的最终属性。
  • execute - 函数(字符串):执行程序化查询。
  • prefillQuery - 函数(字符串):使用查询字符串预填充搜索框,而不执行查询。
  • getInputQuery - function():获取输入框中显示的当前值。
  • clearAllResults - function():通过隐藏搜索框(如果有)以外的所有内容清除控件。

以下代码会在搜索元素“element1”中执行查询“news”:

var element = google.search.cse.element.getElement('element1');
            element.execute('news');
.getAllElements() 返回所有成功创建的元素对象的映射,以 gname 进行键控。