Google AJAX Search API Documentation (to be continue)

技术2022-05-11 90

原文地址：http://code.google.com/apis/ajaxsearch/documentation/

Google AJAX Search API使用手册

Google AJAX Search API是能够让你在自己的网页或是其他web应用程序中嵌入Google Search的JS函数库。要使用这些API，你首先需要登陆并获取API Key，然后学习下面的介绍。

Google AJAX Search API提供了简单web对象，它们可以执行一系列Google的搜索服务（Web Search, Local Search, Video Search, Blog Search, News Search）。如果你的网页是为了帮助用户创建他们的内容（例如：论坛，BLOG等），那么这些API的使用对于用户方便的找到他们的留言或是其他信息十分有帮助。

这份API是全新的，同时它的特性大多数由用户介入决定。请加入我们来完善这份API，也可以参与Google AJAX Search API discussion group给予反馈以及讨论。

本文适合的读者

简介

Hello World

兼容的浏览器

API更新方式

范例

The Basics

GSearcherControl Modes

Searcher Objects

Searcher Options

Keeping a Search Result

Setting Site Restrictions

Search Control Callbacks

Custom Search Form

Advanced Branding

Advanced Samples

常遇到的问题

其他资源

API概览

Styling The Search Control

Styling Search Results

类库手册

本文适合的读者

这篇文档适合于熟悉Javascript和面向对象编程的人们，网络上有许多Javascript的教程，若你不熟悉，可以先去看看。

简介

"Hello, World"

学习这些API最容易的方式就是看一个简单的例子，下面的网页展示了搜索"VW GTI."的结果集，包括了Local Search, Web Search, Video, Blog Search。

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<head>

<title>Hello World - Google AJAX Search API Sample</title>

type="text/css" rel="stylesheet"/>

<script &v=1.0"

type="text/javascript"></script>

//<![CDATA[

function OnLoad() {

// Create a search control

var searchControl = new GSearchControl();

// Add in a full set of searchers

var localSearch = new GlocalSearch();

searchControl.addSearcher(localSearch);

searchControl.addSearcher(new GwebSearch());

searchControl.addSearcher(new GvideoSearch());

searchControl.addSearcher(new GblogSearch());

searchControl.addSearcher(new GnewsSearch());

// Set the Local Search center point

localSearch.setCenterPoint("New York, NY");

// tell the searcher to draw itself and tell it where to attach

searchControl.draw(document.getElementById("searchcontrol"));

// execute an inital search

searchControl.execute("VW GTI");

}

//]]>

</script>

</head>

<body >

<div />

</body>

</html>

你可以下载这个例子，然后编辑并测试，不过你必须把文件中的KEY替换成你自己的AJAX Search API key。

你需要在自己的文件里加入Google AJAX Search API Javascript函数库的URL(

http://www.google.com/uds/api?file=uds.js&v=1.0&key=ABCDEFG

)，才能使用这份search API。这份函数库囊括了用来在你的网页上放置搜索结果的对象和符号。同时在你使用搜索控制功能的时候别忘了用<script>标记来包含函数库。

Google AJAX Search API的核心对象是GSearchControl的一个实例，它等同于包括了一组搜索服务的一个搜索。（译注：相当于根类，也可以算是一个容器，用于添加具体的搜索。）正如你在上面的例子中所见，子对象通过addSearcher()函数添加进search control中，这些searcher对象确定了具体的搜索结果。

搜索控件本身用GSearchControl的draw()方法画在网页上，该方法将你的页面与控件绑定起来（通过DOM）。默认状态下，搜索控件的布局是线性的，当然，你可以采用标签式样布局，我们将在稍后讨论。

用户通过在搜索控件里输入搜索关键字并回车或是单击搜索按钮来开启一个新搜索，搜索控件将自动进行并行的搜索。你只需调用搜索控件的execute()方法，传入搜索关键字便可。

兼容的浏览器

目前Google AJAX Search API兼容Firefox 1.5+, IE 6+, Safari, Opera 9+

API更新方式

URL http://www.google.com/uds/api?file=uds.js&v=1.0中的参数v指示了当前API的版本，当我们对API做了重要的更新时，我们将更新版本号，并在AJAX Search API discussion group中发布。如果关键代码有改动，请及时更新你的URLs至最新版本。

在新版本发布后的一段时间里，Google将会同时支持新旧两个版本，时间大约为一个月。过了那段时间，旧有的API将不被支持，所以请尽快更新自己的代码至最新版本。

Google AJAX Search API开发小组也将持续更新API，修正BUG以及提升运行效率，对于大多数人，这些更新修正都是透明的，but we may inadvertently break some API clients。请用AJAX Search API discussion group来提交这类文章。

范例

提示：所有下面的例子仅仅写出Javascript代码，而非完整的HTML文件。你可以把代码放到如前面所示例子的相应位置，也可以单击链接下载每个范例。

The Basics

下面的例子（和前面的Hello World中的JS代码相同）创建了一个搜索控件，并将它配置成可进行Local Search, Web Search, Video, Blog Search，然后将它放置到你的页面中。

// create a search control

var searchControl = new GSearchControl(null);

// add in a full set of searchers

searchControl.addSearcher(new GlocalSearch());

searchControl.addSearcher(new GwebSearch());

searchControl.addSearcher(new GvideoSearch());

searchControl.addSearcher(new GblogSearch());

searchControl.addSearcher(new GnewsSearch());

// tell the searcher to draw itself and tell it where to attach

// Note that an element must exist within the HTML document with id "search_control"

searchControl.draw(document.getElementById("search_control"));

查看范例(helloworld.html)

GSearcherControl Draw Modes

搜索控件可以以不同的模式显示，GdrawOptions对象通过setDrawMode()方法控制这种行为。该方法带有下面参数：

GSearchControl.DRAW_MODE_LINEAR

GSearchControl.DRAW_MODE_TABBED

要为某个搜索控件设置显示模式，可以把GdrawOptions对象作为参数传给搜索控件的draw()函数。

// create a drawOptions object

var drawOptions = new GdrawOptions();

// tell the searcher to draw itself in linear mode

drawOptions.setDrawMode(GSearchControl.DRAW_MODE_LINEAR);

searchControl.draw(element, drawOptions);

// tell the searcher to draw itself in tabbed mode

drawOptions.setDrawMode(GSearchControl.DRAW_MODE_TABBED);

searchControl.draw(element, drawOptions);

查看范例(tabbed.html)

另一种通用的方法是将search form与search results分离，GdrawOptions通过setSearchFormRoot()方法控制这种行为，该方法支持作为search form容器的DOM元素。

// create a drawOptions object

var drawOptions = new GdrawOptions();

drawOptions.setSearchFormRoot(document.getElementById("searchForm"));

searchControl.draw(element, drawOptions);

查看范例(searchformroot.html)

Searcher Objects

搜索控件对象的addSearcher()方法决定了搜索控件将调用哪些搜索服务。该方法带有两个参数，其一指定了服务对象，另一个参数则设置服务的其他选项。下面是被支持的服务列表：

GlocalSearch

GwebSearch

GvideoSearch

GblogSearch

GnewsSearch

此外，由于Google AJAX Search API仍在不断的开发，越来越多的服务将会被支持。

在向search control中添加单个searcher时，可选的参数－GsearcherOptions对象，控制了每个服务的默认展开模式，它影响着在页面上显示的搜索结果的数量。展开模式由下面几种构成：

GsearchControl.EXPAND_MODE_OPEN

显示所有搜索结果

GSearchControl.EXPAND_MODE_CLOSED

隐藏搜索结果，可以通过单击某些按钮(e.g. 箭头)打开/展示结果

GSearchControl.EXPAND_MODE_PARTIAL

只显示部分搜索结果

// create a searcher options object

// set up for open expansion mode

// load a searcher with these options

var options = new GsearcherOptions();

options.setExpandMode(GSearchControl.EXPAND_MODE_OPEN);

searchControl.addSearcher(new GwebSearch(), options);

Controlling Expansion Mode

下面的例子演示了使用不同展开模式的searcher。需要注意的是，当searcher处于标签式布局下，展开模式将不起作用。那时searcher总是使用OPEN模式。

// local search, partial

options = new GsearcherOptions();

options.setExpandMode(GSearchControl.EXPAND_MODE_PARTIAL);

searchControl.addSearcher(new GlocalSearch(), options);

// web search, open

options = new GsearcherOptions();

options.setExpandMode(GSearchControl.EXPAND_MODE_OPEN);

searchControl.addSearcher(new GwebSearch(), options);

查看范例(expandmode.html)

Controlling Searcher Results Location

在一些应用中，人们希望将搜索结果摆放到网页的任意位置。诸如这样的操作可以通过服务相应的searcher对象的setRoot()方法来实现。

// web search, open, alternate root

var options = new GsearcherOptions();

options.setExpandMode(GSearchControl.EXPAND_MODE_OPEN);

options.setRoot(document.getElementById("somewhere_else"));

searchControl.addSearcher(new GwebSearch(), options);

查看范例(somewhere-else.html)

Keeping a Search Result

到目前为止的所有例子都只是将搜索结果简单的显示在你的网页上，而没有将它存储至其他应用程序中。事实上，通过Google AJAX Search API，我们很容易实现搜索结果的分发，类似于BLOG或是BBS的发帖。

GSearchControl对象通过方法setOnKeepCallback()实现上述功能。

// establish a keep callback

searchControl.setOnKeepCallback(this, MyKeepHandler);

function MyKeepHandler(result) {

// clone the result html node

var node = result.html.cloneNode(true);

// attach it

var savedResults = document.getElementById("saved_results");

savedResults.appendChild(node);

}

查看范例(keephandling.html)

专利

最新回复(0)