Google Code 学习笔记 GSearch & GWebSearch

GwebSearch

该对象通过 Google 网络搜索服务使用 GSearchgoogle.search.Search 界面。完成搜索时，它将提供一组 GwebResult 对象。

GwebSearch():构造器用于创建旨在通过 Google 网络搜索服务提供搜索结果的搜索器对象的实例。

GSearch - 方法

.setSiteRestriction(site, opt_refinement, opt_moreResultsTemplateNew!)

此方法用于限制由此搜索器返回的网络搜索结果集。要限制为 www.amazon.com，只需通过传递一个“www.amazon.com”值调用此方法。要清除网站限制，请传递值 null。以下代码段演示了将限制设置为“amazon.com”。可以在网站限制示例上找到更完整的示例。

var siteSearch = new GwebSearchgoogle.search.WebSearch();
siteSearch.setSiteRestriction("amazon.com");

此方法还允许调用程序将搜索限制为 Google 自定义搜索引擎。传递自定义搜索引擎 ID，而不是指定此方法的网址路径。以下代码段演示了将网站限制设置为一个自定义搜索引擎（其 ID 为 000455696194071821846:reviews）。可以在自定义搜索引擎示例上找到更完整的示例。

var siteSearch = new GwebSearchgoogle.search.WebSearch();
siteSearch.setSiteRestriction("000455696194071821846:reviews");

以此方式使用时，可以通过使用 来提供一个可选的自定义搜索引擎改进opt_refinement。使用此机制，您能够将网站限制为搜索引擎的子集。在 opt_refinement 中指定的值必须匹配与指定的搜索引擎相关联的“自定义搜索引擎改进”标签（请参见以下代码段）。可以在课程搜索示例上找到更完整的示例。

var cseId = "017576662512468239146:omuauf_lfve";
var siteSearch = new GwebSearchgoogle.search.WebSearch();
siteSearch.setSiteRestriction(cseId, "Lectures");

自定义搜索引擎通常包括一个自定义的搜索结果登录页面。为了支持此页面，当自定义搜索引擎网站限制有效时，可能会提供一个可选的 opt_moreResultsTemplate 值。这将指定一个网址模板，该模板将用于在一组搜索结果的底部生成“更多结果”链接。该网址模板必须包括一个“__QUERY__”和“__HL__”占 位符。当生成“更多结果”链接时，系统将使用当前查询条目和 UI 语言来替换这些占位符。此示例演示了如何将此机制用于主标签、左侧标签：课程搜索示例。

自定义搜索引擎的最后一项改进是可以使用链接的自定义搜索引擎。为了支持此功能，已将 site 参数扩展，以便其除了指定网站限制的新匿名对象模式之外，还可以支持以上列出的所有选项和模式。当 site 参数是一个对象时，可能存在以下属性之一（以优先级顺序列出，这意味着如果您提供了多个属性，将获得我们测试的第一个属性 [按以下列出的顺序]）：

• siteUrl - 搜索与提供的网址相关
• cseId - 搜索与提供的自定义搜索引擎 ID 相关，例如， 000455696194071821846:reviews
• crefUrl - 搜索与由提供的网址指向的链接的自定义搜索引擎相关。有关详细信息，请参见此示例。

当指定了 cseId 或 crefUrl 时，可以通过使用 来提供一个可选的自定义搜索引擎改进opt_refinement。使用此机制，您能够将网站限制为搜索引擎的子集。在 opt_refinement 中指定的值必须匹配与指定的搜索引擎相关联的“自定义搜索引擎改进”标签（请参见以下代码段）。

searcher = new GwebSearch();
searcher.setSiteRestriction(
{
crefUrl : "http://www.google.com/cse/samples/vegetarian.xml"
},
"recipes");

• 网站 - 以部分网址形式（例如，''www.amazon.com''、''google.com'' 等）或自定义搜索引擎 ID（例如，"000455696194071821846:reviews"、"000455696194071821846:shopping" 等）形式提供了网站限制设置。这还可以包含如上所述的匿名对象。
• opt_refinement - 当 site 指的是自定义搜索引擎时，该可选参数的值将指定自定义搜索引擎改进
• opt_moreResultsTemplate - 当 site 指的是自定义搜索引擎时，该可选参数的值将指定一个网址模板，此模板将被用于建立“更多结果”链接（此链接将显示在搜索控件中的一组搜索结果下面）。该网 址模板必须包括一个“__QUERY__”和“__HL__”占位符。当生成“更多结果”链接时，系统将使用当前查询条目和 UI 语言来替换这些占位符。
• 返回 - n/a

GSearch

GSearchgoogle.search.Search 类的示例提供了执行搜索的功能并且从特定搜索服务接收结果。该对象不被直接使用，它是特定服务搜索器继承自的基本类。下述方法和属性适用于所有继承自此基本类的对象。每个这种对象还可能提供其他界面。

该对象的预期用途与 GSearchControlgoogle.search.SearchControl（在这里搜索控件提供了用户界面和协调）一起配合使用。也就是说，单独使用此对象将完全为您所接受，但是只要确保您并没有要尝试在您的应用程序推理和搜索控件对象之间共享相同的搜索器对象示例。

GSearch():创建新的搜索器对象。注意：由于这是一个基本类，因此应用程序不可能直接使用此构造器，不过将会把构造器作为创建服务特定搜索器对象（例如，GwebSearchgoogle.search.WebSearch）的一方面效果来使用。

.clearResults()


成功完成搜索时，搜索器对象继续收集搜索结果，这描述了特定搜索的结果。此方法用于重设清除所有结果的搜索器。在执行新的搜索之前将含蓄地调用此方法。

• 返回 - n/a

.execute(query)


调用此方法以开始新的搜索。query 参数提供了搜索词语。完成时，对象被相应的一组结果填充，以及注册的搜索完成处理程序被调用。

• 查询 - 提供了用于执行搜索的查询项
• 返回 - n/a

.setSearchCompleteCallback(object, method, opt_arguments?)


此方法用于注册，对象和方法用于通知完成搜索。应用程序可以通过使用 opt_arguments（之后将被传送到特定的方法）随意传入环境参数。

• object - 提供了一个应用程序级别对象，此对象定义了将在其中调用指定方法的环境。
• method - 提供了要调用的方法。例如，如果此方法作为 .setSearchCompleteCallback(foo, MyObject.prototype.mySearchCompleteHandler) 被调用，则当在此搜索器上的搜索完成时，将调用 foo.mySearchCompleteHandler(opt_arguments?)。
• 返回 - n/a

.setUserDefinedLabel(label)


此方法用于设置用户定义的标签，当该搜索器被添加到搜索控件时应当使用此标签。通过调用此功能，指定的用户定义的标签将代替标准的内置标签在结果节头或标 签中被使用。预期用途与限制搜索的网站一起配合使用，应用程序将显示它们已通过更改标准标签在限制中编程，这在该限制搜索网站上是合适的也是预期的。

• 标签 - 提供了用户定义的标签，可替换在结果节头中的“Web”、“Blog”等等
• 返回 - n/a

.setLinkTarget(linkTarget)


调用此方法以设置用于嵌入搜索结果中的链接的链接目标。默认值为 GSearchgoogle.search.Search.LINK_TARGET_BLANK，该值指定了链接将在新的浏览器窗口中打开。将搜索器添加到搜索控件时，搜索控件将通过使用该搜索控件的当前链接目标设置来隐式调用此方法。这意味着如果您的应用程序需要搜索器来操作不同于搜索控件建立的链接目标设置，则需要在将搜索器添加到该搜索控件之后调用此方法。

• linkTarget - 提供了应在其中打开链接的目标框架，有效值包括：
  • GSearchgoogle.search.Search.LINK_TARGET_BLANK - 链接将在新的窗口中打开，例如GSearchgoogle.search.Search.LINK_TARGET_SELF - 链接将在同一窗口和框架中打开，例如
  • GSearchgoogle.search.Search.LINK_TARGET_TOP - 链接将在顶端的框架中打开，例如
  • GSearchgoogle.search.Search.LINK_TARGET_PARENT - 链接将在顶端的框架中打开，或者替换当前的框架，例如
  • anything-else - 链接将在指定的框架或窗口中打开，例如
• 返回 - n/a

.setNoHtmlGeneration()


有时您的应用程序不使用此搜索控件，而仅使用来自搜索结果的一小组属性，您可以通过可高度自定义的格式来显示这些属性。在此情况下，您的应用程序可进行略 微的优化。可以对搜索器进行编程以便不生成 .html 属性，而只在结果中产生有效的原始属性。

• n/a - 无输入参数
• 返回 - n/a

.setQueryAddition(term)


此方法允许调用程序设置（或清除）一个可选的、附加查询条目，该查询条目会附加到通过此搜索器进行的所有查询。通常，应用程序将使用此方法来提供可备选结果，这些备选结果与原始搜索词语相比有一定的变化。例如，假设一个基于 GwebSearchgoogle.search.WebSearch() 的搜索器将此功能作为 search.setQueryAddition("filetype:pdf"); 来调用，然后执行查询“google”，则会导致以下查询“google filetpe:pdf”。当使用该 API 时，我们强烈建议您使用 .setUserDefinedLabel()，以便可以向您的用户显示他们的查询已被修改。当使用 .setSiteRestriction() 时，我们同样建议您使用该常规方法。有关详细信息，请访问我们的示例。

• term - 提供了附加到通过此搜索器进行的每个查询的表达式（请注意，无需使用空格）。当条目的值为 "" 时，将取消该 API 的效果，并且不会修改查询。
• 返回 - n/a

.createResultHtml(result)


此方法允许调用程序创建或重新生成指定结果的 .html 属性。有时当调用程序先前已经使用 .setNoHtmlGeneration()，或当调用程序从其自身的存储系统重新加载一个结果对象时，需要使用此方法。

• 结果 - 提供了一个结果对象。它的 .html 属性将被删除并且将作为该调用的结果重新生成。如果结果不包含 .html 属性，则将创建该属性。
• 返回 - n/a

.gotoPage(page)


完成搜索后，cursor 属性在搜索器选项上可能变为可用。这是可用搜索结果数的以及基本搜索器容量的函数。如果使用光标属性，则此方法还使您可以提取另外一组搜索结果。应用程序通过使用 page 参数来指定页面。然后，将使用该值为 cursor.pages 数组建立索引，该数组最后将用于计算 &start 网址参数的值。

• page - 提供了应用程序所需的结果的页码。此值是相对于 .cursor.pages 属性检查的范围，如果页面在范围之外，或者基本搜索器没有 cursor 属性，则不执行操作。
• 返回 - n/a

GSearch - 静态方法

.getBranding(opt_element?, opt_orientation?)


此方法是一种静态辅助函数，它可以将“powered by Google”HTML DOM 标志节点返回到您的应用程序，并且可以将其作为指定的可选元素的唯一子项随意附加到您的文档。此方法的目的在于确保您的应用程序可以通过简单的方式在某些 情况（使用 GSearchControlgoogle.search.SearchControl 或 GSearchFormgoogle.search.SearchForm 中的搜索窗体并不适合于您的应用程序）下遵循标志要求。

默认情况下，标志节点是针对水平方向而设计的，并且可以在搜索窗格下面、结果集合上面或下面等位置正常运行。在某些情况下，需要垂直方向的标志。作为此情况的实例，请考虑一个垂直定向的视频栏。在这种情况下，由于标志需求的控件比较狭小，因此需要垂直方向的标志（请参见视频栏底部的“powered by Google”标志）。默认情况下此 API 将提供水平方向的标志，但是作为应用程序，您可以轻松请求垂直方向的标志。

• opt_element - 如果提供了可选的参数，则将指定 HTML DOM 节点，此节点将用“powered by Google”标志元素来填充。
• opt_orientation - 如果提供了可选的参数，则将指定标志节点的方向。有效的值包括：
  • GSearchgoogle.search.Search.HORIZONTAL_BRANDING - 请求水平方向
  • GSearchgoogle.search.Search.VERTICAL_BRANDING - 请求垂直方向
• 返回 - 一个您可以免费附加或复制到您文档上的“powered by Google”HTML DOM 节点。

GSearch - 属性

使用此接口的所有对象均可提供以下公共属性的集合。除非另有说明，否则将假定这些属性为只读。

.results[]

该属性包含搜索结果对象数组，每个对象对应一个结果。每次执行搜索时会清除该属性，每次完成搜索时会填充该数组。如果没有要报告的结果，则该数组的 .length 属性将被设置为 0。

.cursor


当成功完成搜索后，此可选属性将可用。对于本地搜索和博客搜索此可选属性不可用，因为这些搜索器当前不支持分页。使用时，此属性将指定应用程序如何请求当 前查询条目、预计结果数、当前页面以及网址（可用于导引到 Google 上托管的搜索结果页面）的其他搜索结果。此属性具有以下结构：

• .pages[] - 提供了一个由 .gotoPage() 使用的数组以检索一组结果。数组中的每个条目均为具有以下结构的对象：
  • .start - 提供了将用于 &start 网址参数中的值以请求一组结果
  • .label - 提供了与条目相关联的文本标签，例如“1”、“2”、“3”或“4”
• .estimatedResultCount - 提供了匹配当前查询的预计结果数。请注意，此值将不必匹配 Google.com 搜索属性上可见的相似值。
• .currentPageIndex - 提供了在当前结果集的 pages 数组中的索引。
• .moreResultsUrl - 提供了指向 Google 托管的搜索页面（包含其他搜索结果）的网址。