Programmable Search Element Control API

您可以将可编程搜索引擎组件(搜索框和搜索结果页)嵌入到 网页和其他 Web 应用。这些可编程搜索引擎 这些元素由根据 可编程搜索服务器以及您所做的任何自定义设置。

所有 JavaScript 都是异步加载的 在浏览器提取可编程搜索引擎 JavaScript 时继续加载。

简介

本文档提供了添加可编程搜索引擎的基本模型 元素,并附有关于该元素所属元素的说明, 可配置的组件和灵活的 JavaScript API。

范围

本文档介绍了如何使用 Programmable Search Engine Control API。

浏览器兼容性

可编程搜索引擎支持的浏览器列表可在 此处

观众

本文档面向希望将 Google Programmable 实现网页的搜索功能。

可编程搜索元素

您可以使用 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">
双页 <ph type="x-smartling-placeholder"> <div class="gcse-searchbox-only">(在第一页上),<div class="gcse-searchresults-only">(或其他组件)在第二页上。
仅限结果 <ph type="x-smartling-placeholder"> <div class="gcse-searchresults-only">
由 Google 托管 <ph type="x-smartling-placeholder"> <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 字符串 (可选)Search Element 对象的名称。名称用于检索 关联组件的名称,或者配对 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 布尔值 指定是否按网址中嵌入的查询来执行搜索 所加载网页的具体位置请注意,网址中必须包含查询字符串 执行自动搜索。默认值:true 不限
enableHistory 布尔值 如果为 true,则为浏览器启用历史记录管理“返回” 和“前进”按钮查看演示。

搜索框

仅限搜索框

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>

搜索结果

searchresults-only

mobileLayout 字符串

指定是否应针对移动设备使用移动设备布局样式。

enabled 仅针对移动设备使用移动设备布局。

disabled 不适用于任何设备的移动设备布局。

forced 针对所有设备使用移动设备布局。

默认:enabled

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

不限
自动补全
enableAutoComplete 布尔值 仅在可编程搜索引擎控制面板中启用自动补全功能时才可用。 true 用于启用自动补全功能。 不限
autoCompleteMaxCompletions 整数 要显示的自动补全查询数量上限。

搜索框

仅限搜索框

autoCompleteMaxPromotions 整数 自动补全功能中显示的促销信息数量上限。

搜索框

仅限搜索框

autoCompleteValidLanguages 字符串 支持自动补全功能的语言列表(以英文逗号分隔) 。<ph type="x-smartling-placeholder"></ph> 支持的语言。

搜索框

仅限搜索框

优化条件
defaultToRefinement 字符串 只有在已在 可编程搜索引擎控制面板。将默认优化标签指定为 注意:Google 托管的布局不支持此属性。 不限
refinementStyle 字符串 可接受的值包括 tab(默认)和 link。 仅当图片搜索处于停用状态时,或者满足以下条件时,才支持 link 图片搜索已启用,但网页搜索已停用。

搜索结果

searchresults-only

图片搜索
enableImageSearch 布尔值 仅适用于 可编程搜索引擎控制面板中启用图片搜索

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

搜索结果

searchresults-only

defaultToImageSearch 布尔值 仅适用于 可编程搜索引擎控制面板中启用图片搜索

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

不限
imageSearchLayout 字符串 仅适用于 可编程搜索引擎控制面板中启用图片搜索

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

搜索结果

searchresults-only

imageSearchResultSetSize 整数、字符串 仅适用于 可编程搜索引擎控制面板中启用图片搜索

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

不限
image_as_filetype 字符串 仅适用于 可编程搜索引擎控制面板中启用图片搜索

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

支持的扩展包括 jpggifpngbmpsvgwebpicoraw

不限

image_as_oq 字符串 仅适用于 可编程搜索引擎控制面板中启用图片搜索

使用逻辑 OR 过滤搜索结果。

如果您想获得包含“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,则停用网页搜索。通常仅在满足以下条件时使用 <ph type="x-smartling-placeholder"></ph> 可编程搜索引擎控制面板中启用图片搜索

搜索结果

searchresults-only

webSearchQueryAddition 字符串 使用逻辑 OR 向搜索查询添加的额外字词。

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

不限
webSearchResultSetSize 整数、字符串 结果集的大小上限。应用对象 图片搜索和网页搜索。默认值取决于布局和 可编程搜索引擎是配置为搜索整个网络,还是仅指定 。可接受的值包括: <ph type="x-smartling-placeholder">
    </ph>
  • 介于 1 到 20 之间的整数
  • small:请求较小的结果集,通常为 4 个结果 。
  • large:请求较大的结果集,通常为 8 个 每页显示 条结果。
  • filtered_cse:每页最多请求 10 个结果,对于 最多 10 页或 100 条结果。
不限
webSearchSafesearch 字符串 指定是否 SafeSearch是 。接受的值为 offactive 不限
as_filetype 字符串 将结果限制为指定扩展名的文件。如需 Google 可编入索引的文件类型列表,请访问 Search Console 帮助中心

不限

as_oq 字符串 使用逻辑 OR 过滤搜索结果。

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

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

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

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

搜索结果

searchresults-only

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

搜索结果

searchresults-only

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

回调

<ph type="x-smartling-placeholder">
</ph>
回调序列图
来自搜索元素 JavaScript 的回调序列图

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

<ph type="x-smartling-placeholder">
</ph>
注册回调

  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 中的元素。如果 parsetagsexplicit __gcse,搜索元素 JavaScript 会将搜索元素呈现给 初始化回调(如注册回调中所示)。 此属性可用于选择要渲染的元素,或将渲染元素延迟到它们 所需的资源。它还可以覆盖元素的属性;例如,它可以将 通过“控制面板”或“HTML”属性配置的搜索框默认为“网络” 在图片搜索框中搜索,或者指定通过可编程搜索引擎表单提交的查询 。 <ph type="x-smartling-placeholder"></ph> 查看演示。

初始化回调的角色由 parsetags 的值控制 属性。__gcse

  • 如果值为 onload,则搜索元素 JavaScript 会自动呈现网页上的所有搜索元素。初始化回调为 但它不负责呈现搜索元素。
  • 如果值为 explicit,则搜索元素 JavaScript 不会呈现 搜索元素。回调可以使用 render() 函数, 或使用 go() 函数呈现所有搜索元素

以下代码演示了如何在 div,使用 explicit parsetag 和初始化回调:

。 <ph type="x-smartling-placeholder">
</ph> 初始化回调示例

我们需要添加一个具有 ID 值的 <div> 我们想要搜索元素代码的位置:

    <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 支持六种回调,这些回调在 搜索控制流 搜索回调成对出现,即网页搜索回调和匹配的图片搜索回调:

  • 开始搜索 <ph type="x-smartling-placeholder">
      </ph>
    • 用于图片搜索
    • 用于网页搜索
  • 结果已就绪 <ph type="x-smartling-placeholder">
      </ph>
    • 用于图片搜索
    • 用于网页搜索
  • 已呈现结果 <ph type="x-smartling-placeholder">
      </ph>
    • 用于图片搜索
    • 用于网页搜索

初始化回调一样,搜索回调也属于 使用 __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

<ph type="x-smartling-placeholder">
</ph> 搜索启动回调示例
    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 中,搜索元素通常位于该 DOM 中 地方促销和搜索结果。通常,搜索元素 JavaScript 会处理 但此回调可能会选择停止自动呈现结果 并使用此 div 来呈现结果本身。

如果此回调返回 true 值,搜索元素 JavaScript 将跳至其 页脚工作。

结果准备就绪回调示例

resultsReady 回调中的示例 结果准备就绪回调示例会替换默认呈现方式 只需简单的替换即可。

<ph type="x-smartling-placeholder">
</ph> 结果准备就绪回调示例
    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 呈现网页之前立即调用这些回调 页脚。示例用例包括一个回调,用于添加 (例如保存此复选框或 自动呈现的内容,也可以是添加 for more information 按钮的回调。

如果结果呈现的回调需要 promos 中的信息,并且 results results ready callback 参数表示,则可在二者之间传递该参数,如下所示:

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

没有返回值。

结果呈现的回调示例

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

<ph type="x-smartling-placeholder">
</ph> 结果呈现的回调示例
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,该回调可以在 回调。以下示例展示了将评分值从 richSnippetresults ready callback 传递给呈现结果 回调。

。 <ph type="x-smartling-placeholder">
</ph> 结果就绪回调与结果渲染的回调协同工作的示例
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>

更多回调示例

如需查看更多回调示例,请参阅 更多回调示例文档。

Promotion 和 Result 属性

使用 JSDoc 表示法时,以下属性 promotionresult 对象。 在这里,我们列出了可能存在的所有属性。存在许多属性 具体取决于宣传或搜索结果的细节。

<ph type="x-smartling-placeholder">
</ph>
促销属性
{
  content: string,
  image: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  url: string,
  visibleUrl: string,
}
<ph type="x-smartling-placeholder">
</ph>
结果对象属性
{
  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 可编程搜索元素组件的配置。指定以下内容: <ph type="x-smartling-placeholder">
    </ph>
  • 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 组件。指定以下内容: <ph type="x-smartling-placeholder">
    </ph>
  • div(字符串):<div>id,或 将在其中呈现元素的 div 元素。
  • tag(字符串):要呈现的组件的类型。时间 提供了 opt_componentConfig,即 tag 的值 属性必须为 searchresults。此外, componentConfigtag 属性 必须为 searchbox
  • gname(字符串):(可选)此组件的唯一名称。如果不是 可编程搜索引擎会为此项自动生成gname 组件。如已提供,则必须与 gname componentConfig
  • attributes(对象):采用键值对形式的可选属性 对。<ph type="x-smartling-placeholder"></ph> 支持的属性。
.go(opt_container) 在指定容器中呈现所有搜索元素标记/类。

参数

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

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

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

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

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