Programmable Search Element Control API

您可以使用 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> 检索对象时，如果多个组件具有相同的 `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 searchresults-only
`mobileLayout`	字符串	指定是否应将移动布局样式用于移动设备。 `enabled` 仅针对移动设备使用移动版布局。 `disabled` 不会为任何设备使用移动版布局。 `forced` 针对所有设备使用移动版布局。默认值：`enabled` 用法示例：`<div class="gcse-search" data-mobileLayout="disabled"></div>`	不限
自动补全
`enableAutoComplete`	布尔值	仅当在可编程搜索引擎控制台中启用了自动补全功能时才可用。 `true` 用于启用自动补全功能。	不限
`autoCompleteMaxCompletions`	整数	要显示的最大自动补全数量。	搜索框仅限搜索框
`autoCompleteMaxPromotions`	整数	自动补全中显示的最大促销数量。	搜索框仅限搜索框
`autoCompleteValidLanguages`	字符串	以英文逗号分隔的语言列表，用于指定应为哪些语言启用自动补全功能。支持的语言。	搜索框仅限搜索框
优化
`defaultToRefinement`	字符串	仅当在可编程搜索引擎控制台中创建了优化条件时才可用。指定要显示的默认细化标签。注意：Google 托管布局不支持此属性。	不限
`refinementStyle`	字符串	可接受的值为 `tab`（默认值）和 `link`。仅当图片搜索已停用，或者图片搜索已启用但网页搜索已停用时，才支持 `link`。	searchresults searchresults-only
图片搜索
`enableImageSearch`	布尔值	仅当在可编程搜索引擎控制台中启用了图片搜索时才可用。如果为 `true`，则启用图片搜索。图片搜索结果将显示在单独的标签页中。	searchresults searchresults-only
`defaultToImageSearch`	布尔值	仅当在可编程搜索引擎控制台中启用了图片搜索时才可用。如果值为 `true`，搜索结果页面将默认显示图片搜索结果。网页搜索结果将在单独的标签页中显示。	不限
`imageSearchLayout`	字符串	仅当在可编程搜索引擎控制台中启用了图片搜索时才可用。指定图片搜索结果页面的布局。可接受的值包括 `classic`、`column` 或 `popup`。	searchresults searchresults-only
`imageSearchResultSetSize`	整数、字符串	仅当在可编程搜索引擎控制台中启用了图片搜索时才可用。指定图片搜索的搜索结果集的最大大小。例如，`large`、`small`、`filtered_cse`、`10`。	不限
`image_as_filetype`	字符串	仅当在可编程搜索引擎控制台中启用了图片搜索时才可用。将结果限制为具有指定扩展名的文件。支持的扩展名包括 `jpg`、`gif`、`png`、`bmp`、`svg`、`webp`、`ico`、`raw`。	不限
`image_as_oq`	字符串	仅当在可编程搜索引擎控制台中启用了图片搜索时才可用。使用逻辑 OR 过滤搜索结果。如果您希望搜索结果包含“term1”或“term2”，可以按以下方式使用：`<div class="gcse-search" data-image_as_oq="term1 term2"></div>`	不限
`image_as_rights`	字符串	仅当在可编程搜索引擎控制台中启用了图片搜索时才可用。基于许可的过滤条件。支持的值包括 `cc_publicdomain`、`cc_attribute`、`cc_sharealike`、`cc_noncommercial`、`cc_nonderived` 以及这些值的组合。请参阅典型组合。	不限
`image_as_sitesearch`	字符串	仅当在可编程搜索引擎控制台中启用了图片搜索时才可用。将结果限制为特定网站中的网页。用法示例：`<div class="gcse-search" data-image_as_sitesearch="example.com"></div>`	不限
`image_colortype`	字符串	仅当在可编程搜索引擎控制台中启用了图片搜索时才可用。将搜索范围限制为黑白（单色）、灰度或彩色图片。支持的值为 `mono`、`gray`、`color`。	不限
`image_cr`	字符串	仅当在可编程搜索引擎控制台中启用了图片搜索时才可用。将搜索结果限制为源自特定国家/地区的文档。支持的值	不限
`image_dominantcolor`	字符串	仅当在可编程搜索引擎控制台中启用了图片搜索时才可用。将搜索范围限制为具有特定主色的图片。支持的值包括 `red`、`orange`、`yellow`、`green`、`teal`、`blue`、`purple`、`pink`、`white`、`gray`、`black`、`brown`。	不限
`image_filter`	字符串	仅当在可编程搜索引擎控制台中启用了图片搜索时才可用。自动过滤搜索结果。支持的值：0/1 用法示例：`<div class="gcse-search" data-image_filter="0"></div>`	不限
`image_gl`	字符串	仅当在可编程搜索引擎控制台中启用了图片搜索时才可用。提高原产国家/地区与参数值相符的搜索结果的排名。支持的值	不限
`image_size`	字符串	仅当在可编程搜索引擎控制台中启用了图片搜索时才可用。返回指定尺寸的图片，其中尺寸可以是以下值之一：`icon`、`small`、`medium`、`large`、`xlarge`、`xxlarge` 或 `huge.`	不限
`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`，则停用网页搜索。通常仅在可编程搜索引擎控制面板中启用图片搜索时使用。	searchresults searchresults-only
`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。可接受的值为 `off` 和 `active`。	不限
`as_filetype`	字符串	将结果限制为具有指定扩展名的文件。如需查看 Google 可编入索引的文件类型列表，请访问 Search Console 帮助中心。	不限
`as_oq`	字符串	使用逻辑 OR 过滤搜索结果。如果您希望搜索结果包含“term1”或“term2”，则可以按以下方式使用：`<div class="gcse-search" data-as_oq="term1 term2"></div>`	不限
`as_rights`	字符串	基于许可的过滤条件。支持的值包括 `cc_publicdomain`、`cc_attribute`、`cc_sharealike`、`cc_noncommercial`、`cc_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`	字符串	使用日期或其他结构化内容对结果进行排序。属性值必须是可编程搜索引擎的结果排序设置中提供的选项之一。如需按相关性排序，请使用空字符串 (sort_by="")。用法示例：`<div class="gcse-search" data-sort_by="date"></div>`	不限
搜索结果
`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 中呈现搜索框以及搜索结果：

注意：本页上的可执行示例在 JSFiddle 网站上运行。在代码块的右上角找到 jsfiddle 按钮

。按此按钮将打开一个 JSFiddle 页面，其中显示了 HTML、JavaScript、css 和运行窗格中的示例。它一开始处于“活跃”状态，因此只需在运行窗格中显示的搜索框中输入查询，回调就会运行。

本文档中的示例根据其类型和功能分为多个部分，但：

示例的所有部分都会一起发送到 JSFiddle
示例的每个部分都有一个 JSFiddle 按钮。它们都执行相同的操作。

由于这是 JSFiddle，您可以随意修改代码。在 JSFiddle 中所做的更改不会传播回本文档。

初始化回调示例

我们需要包含一个具有 ID 值的 <div>，我们希望在其中放置搜索元素代码：

    <div id="test"></div>

将此 JavaScript 添加到 <div> 之后。请注意，它引用了 test，即我们用于标识 <div> 的 id

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 以开始加载搜索元素。将 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 自行呈现结果。

注意：回调可以随意修改参数的值。对 gname, query, promos, 和 results 的更改不会影响搜索元素 JavaScript 的行为，但如果回调返回 true，则会显示以 div 为根的 DOM 树。

如果此回调返回 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 元素数组。

没有返回值。

注意：更改 gname 和 query 的值不会改变搜索元素 JavaScript 的行为，但更改 promoElts 和 resultElts 中的条目会改变 DOM。

注意：只有由搜索元素 JavaScript 本身呈现的 DOM 元素才会传递给 resultsRendered 回调。

示例结果呈现回调

示例结果呈现回调中的示例 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',
},