©2009 Google -
Code 主页 -
站点服务条款 -
隐私政策 -
站点目录
Google Code 有以下版本：
English -
Español -
日本語 -
한국어 -
Português -
Pусский -
中文(简体) -
中文(繁體)
|
中文(简体)
| Sign in
本指南将帮助您在 iGoogle 环境中构建和管理小工具。它是针对在一定程度上熟悉 iGoogle、小工具 API 和 JavaScript 的开发人员设计的。本指南也提供指向与 iGoogle 中小工具开发相关的其他资源的链接。
每个小工具容器都有不同的开发体验。本部分介绍了开发在 iGoogle 上使用的小工具的过程。
本指南使用以下术语描述与 iGoogle 开发体验相关的元素和主题。
| 更新小工具 | 一种小工具，用于显示含有一个人的活动的数据供稿。 |
|---|---|
| 小工具 | 第三方代码，它使用小工具和 OpenSocial API 扩展 iGoogle 体验。 |
| 小工具定义 | 定义小工具的 XML 文件。语法基于小工具 XML（也称为“小工具规范”）。 |
| 小工具目录 | 根据受欢迎程度和用户反馈排列的可用小工具的列表。 |
| 左侧导航栏 | iGoogle 页面左侧上链接的列表。左侧导航栏列有指向用户页面上每个小工具的画布视图的链接。 |
| 左侧导航栏链接 | 左侧导航栏上的链接，它打开小工具的画布页面。 |
| 视图 | 显示小工具的位置。在 iGoogle 中，小工具可显示在画布或主页视图上。两个视图都是私有的。iGoogle 不允许用户看到彼此的小工具。 |
| 主页视图 | 小工具的小视图，与其他小工具一起显示。以较小的显示格式显示您的所有小工具。主页视图是私有的，就是说只有登录的用户才能看见该视图。 |
| 画布视图 | 小工具的大视图，单独显示，而且不显示其他任何小工具。画布视图是私有的，就是说只有登录的用户才能看见该视图。 |
| 好友 | 使用 OpenSocial API 可访问用户的好友网络。在 iGoogle 测试区中，可以使用“测试区好友”(Sandbox Friends) 小工具添加好友。 |
为 iGoogle 构建小工具之前，首先熟悉小工具的各种功能以及它们的合作方式很有用。《iGoogle 小工具分析》文档是一个实用的指南。
如果这是您的第一个小工具，请按照《OpenSocial 教程》中所列的步骤进行操作，以便能熟悉 OpenSocial API。本教程介绍了使用 OpenSocial API 开发简易赠礼小工具时所需的步骤。
如果您有现成的小工具，则可增强其功能以便能够使用通过 iGoogle 测试区提供的一些新功能，包括：
如果您没有权限访问服务器以存储小工具 XML 文件，那么可以使用 Google 小工具编辑器 (GGE)，这是用于快速编辑和托管小工具的不错工具。要创建快速“Hello World”小工具，请确保使用 Google 帐户登录（否则无法保存您的小工具），并在 Google 小工具编辑器中修改以下小工具。例如，将消息“Hello, world!”更改为“Hello, iGoogle!”：
使用“文件”>“另存为”，以“igoogle-sample.xml”为名称保存文件。完成后，请点击编辑器右上角的文件名来打开您的小工具的 XML 文件。
这会在您的浏览器中打开小工具 XML。在下一部分中，您需要该文件的网址来安装您的小工具。
小工具需要在容器内部运行，以便访问社交网络数据。iGoogle 提供开发人员测试区，您可在其中访问 OpenSocial API 和其他新功能。您可以在此处注册使用测试区。
要添加新的小工具，请执行以下步骤：
一旦添加了开发人员工具标签，也可以通过开发人员小工具添加小工具。
iGoogle 测试区提供两种不同的视图来显示您的小工具。第一种是主页视图。在主页视图中，您的小工具会以 3 列格式与您已添加的任何其他小工具一起显示：
要以最大尺寸查看小工具，可在“主页”下点击其链接来以画布视图显示它。默认情况下，小工具只以较小的格式显示。有关向您的小工具添加画布视图的信息，请参阅“视图”。
例如，下面是画布视图中的一个图书小工具。它只列出用户的阅读列表、用户的好友图书和推荐图书：
图书小工具的扩展画布视图提供更丰富的体验，含有标签以及有关用户图书和用户评论的更多详细信息：
iGoogle 中的主页视图和画布视图是私有的，这表示只有已登录的用户才能查看它们。这是 iGoogle 和一些社交小工具容器（例如 Orkut）之间的关键区别。
要设置您的测试区开发环境，请登录测试区并添加开发人员工具标签。
开发人员工具标签包括以下小工具：
开发人员小工具充当您 iGoogle 页面上所有小工具的“命令中心”。除了列出您正运行的所有小工具之外，它还允许您添加、查看和管理小工具。开发人员小工具向您提供进行小工具开发时需要的功能。例如，它允许您添加“已破坏”的小工具，该功能在您主动更改小工具时很有用。
在开发人员小工具中，可点击个别小工具链接，以查看它们的 XML 规范。这是查看其他小工具如何执行的好方法。
帮助您开发小工具的一个功能是“已缓存”复选框。默认情况下，系统会缓存小工具规范。开发小工具时，应取消选中小工具的“已缓存”复选框。这可让您看到小工具的最新版本，而非缓存版本。
测试区好友小工具可让您管理您的 iGoogle 测试区好友。
将某人建立为测试区好友一共分为两个过程。一个人必须发出一份邀请，另一个人必须接受该邀请。
要查看您的邀请并邀请其他人，请点击“邀请和建议”。该面板包括两份列表：
要邀请某人成为好友，请点击联系人列表旁边的“加为好友”，或者在文本字段中键入一个新的电子邮件地址。电子邮件地址必须与 Google 帐户相关，否则系统就会自动将它丢弃。点击“保存更改”以保存您在该面板上所做的更改。这一步很重要，因为如果不执行这一步，您发出或接受的任何邀请都不会得到处理。
一旦您接受了邀请，或者您发出的邀请被接受，那么对方就会添加到您的好友列表。此时可以通过 OpenSocial API 访问这个人。有关处理好友数据的示例，请参阅“教程”。
测试区个人资料编辑器小工具可让您编辑您的 iGoogle 测试区个人资料。请注意，可通过 API 访问的个人资料信息只有用户 ID、姓名、位置和缩略图网址。有关详细信息，请参阅“个人资料数据”。
更新小工具维护一份用户所有已发布活动的列表，此列表从最新的活动开始，并随时更新。
有关更新的更多讨论，请参阅“更新”。
既然您已学习了安装和更新小工具的基本知识，下面就来介绍一些提示和技巧，帮助您构建可以利用 iGoogle 测试区功能的小工具。
OpenSocial 小工具是新型小工具，它基于小工具技术，但已得到了扩展，因而能够与从支持 OpenSocial API 的网站（也称为容器）检索到的社交数据交互。iGoogle 是 OpenSocial 容器的一个示例，本部分集中介绍在 iGoogle 环境中处理小工具的开发内容。
视图是容器中显示小工具的位置。不同视图具有不同特性。例如，容器可能具有一个以较小的格式显示小工具的视图，以及一个以整个页面格式显示小工具的视图。
默认情况下，在 iGoogle 测试区中，小工具以主页视图模式（“小模式”）显示，这表示它以列布局的形式出现在其他小工具中间。要创建您的小工具的画布视图（“大模式”），在该视图中小工具会水平扩展至跨越整个小工具区域，您必须为“画布”视图类型定义一个 <Content> 部分，如下所示：
<Content type="html" view="canvas">
为画布视图定义了 <Content> 部分后，还必须创建 <Content> 部分以便小工具能在主页视图中正确显示。这可以是“默认”或“主页”。有关编写支持多个 <Content> 部分的小工具的更多讨论，请参阅《OpenSocial JavaScript 开发人员指南》。
下面是“Hello World”小工具的一个版本，它为“主页”和“画布”定义 <Content> 部分视图。其宽度会根据您将其显示在主页视图中还是画布视图中而改变。
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Hello World!">
<Require feature="opensocial-0.7" />
</ModulePrefs>
<Content type="html" view="home">
<![CDATA[
Hello, small world!
]]>
</Content>
<Content type="html" view="canvas">
<![CDATA[
Hello, big world!
]]>
</Content>
</Module>
所有 OpenSocial 容器都支持视图，但是每个容器可能支持一组不同的视图。例如，iGoogle 有一个称为 home 的小视图，但在 Orkut 中该小视图称为 profile。
假设您要编写一个对于 iGoogle 上的 home 和 Orkut 上的profile 具有相同显示的小工具。无需创建重复的 <Content> 部分即可合并单个 <Content> 部分的视图，如下所示：
<Content type="html" view="home,profile">
您可以在不同容器之间或同一容器内使用此技术。例如，处理一个 <Content> 部分中大小不同的视图的演示逻辑的小工具可以进行扩展，以通过声明 view="home,canvas" 来支持画布页面。
在 iGoogle 中，您的小工具可以以画布视图和主页视图显示。只有已登录的用户才能看到这两个视图。
获取当前视图最容易的途径是在您的小工具模块使用偏好中包含“视图”功能。
<ModulePrefs title="Views example"> <Require feature="views" /> </ModulePrefs>
如果包含了视图功能，您可以通过调用 gadget.util.getCurrentView() 函数来获取当前的视图。这将把 gadgets.views.View 对象分配给 current_view 变量。有关此调用可能返回的视图列表，请参阅“iGoogle 中的可用视图”。
以下示例演示如何获取当前视图并根据返回值有条件地执行代码：
function getViewName() {
return gadgets.views.getCurrentView().getName();
}
if (getViewName() == "canvas") {
/* Do canvas specific stuff here */
}
if (getViewName() == "home") {
/* Do home specific stuff here */
}
ModulePrefs 部分包含 <Require
feature="views">。通过调用 gadgets.views.getSupportedViews() 函数获取可用的 View 对象。
var supported_views = gadgets.views.getSupportedViews();
getSupportedViews 调用返回的对象包含 gadgets.views.View 对象，这些对象代表 iGoogle 中的所有可用视图，并按照视图名称进行索引。
小工具的主页视图显示用户最感兴趣的内容和通知。主页视图是汇总内容和好友更新以及向用户提供完成简单任务的快捷方法的好地方。
小工具的画布视图提供扩展的空间，以显示更丰富的内容并实现更强大的功能。利用该视图吸引用户，向他们显示好友正在进行的活动，并允许他们完成复杂的任务。
ModulePrefs 部分包含 <Require
feature="views">。如果您想提供指向其他视图的链接，则需要向 gadgets.views.requestNavigateTo() 方法传递一个 gadgets.views.View 对象。 您可选择使用 getSupportedViews() 调用返回的某个对象，“iGoogle 中的可用视图”中描述了该调用。以下代码示例演示了此方法：
function navigateTo(dest) {
var supported_views = gadgets.views.getSupportedViews();
gadgets.views.requestNavigateTo(supported_views[dest]);
};
/**
* When called, this method asks the container to switch to the canvas
*/
function gotoCanvas() {
navigateTo("canvas");
};
/**
* When called, this method asks the container to switch to the home
*/
function gotoHome() {
navigateTo("home");
};
备选方法是手动创建新的 View 对象，然后使用该对象开始导航。以下代码示例显示了创建新的 gadgets.views.View 对象并将它传递给 gadgets.views.requestNavigateTo() 方法：
/**
* When called, this method asks the container to switch to the canvas
*/
function gotoCanvas() {
var canvas_view = new gadgets.views.View("canvas");
gadgets.views.requestNavigateTo(canvas_view);
};
/**
* When called, this method asks the container to switch to the home
*/
function gotoHome() {
var home_view = new gadgets.views.View("home");
gadgets.views.requestNavigateTo(home_view);
};
下面是基于“Hello World”小工具的完整示例：
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs height="100" title="Navigation">
<Require feature="views" />
</ModulePrefs>
<Content type="html" view="home">
<![CDATA[
<div>Hello world Home view</div>
<script type="text/javascript">
function goToView(dest) {
var supported_views = gadgets.views.getSupportedViews();
gadgets.views.requestNavigateTo(supported_views[dest]);
};
</script>
<a href="javascript:goToView('canvas')" >Go to canvas view</a><br><br>
]]>
</Content>
<Content type="html" view="canvas">
<![CDATA[
<div>Hello world Canvas view</div>
<script type="text/javascript">
function goToView(dest) {
var supported_views = gadgets.views.getSupportedViews();
gadgets.views.requestNavigateTo(supported_views[dest]);
};
</script>
<a href="javascript:goToView('home')" >Go to home view</a><br><br>
]]>
</Content>
</Module>
注意：在 OpenSocial 0.7 中，没有调用可返回您的小工具 ID 号码。如果您想在您的小工具中使用该值，请手动存储它。
ModulePrefs 部分包含 <Require
feature="views">。如果您正使用 gadgets.views.requestNavigateTo() 调用，则可提供一个可选的参数，该参数包含将传递到新页面的数据。
以下代码将两个变量（foo 和 bar）传递到当前小工具的画布表面：
function gotoCanvas(params) {
var canvas_view = new gadgets.views.View("canvas");
gadgets.views.requestNavigateTo(canvas_view, params);
};
var my_params = {
foo : 12345,
bar : "Bar value"
};
gotoCanvas(my_params);
在画布视图中，使用以下代码检查这些值：
var prefs = gadgets.views.getParams(); var foo = prefs["foo"]; /* foo contains 12345 */ var bar = prefs["bar"]; /* bar contains "Bar value" */<sup class="changed">New!</sup>
您可以使用 shareable-prefs 功能，以使多个用户可以编辑小工具的用户使用偏好。这样，用户可以共享该小工具并看到彼此的编辑。例如，家庭成员可以共享一个杂物列表小工具，每个人都可以添加自己喜欢的东西。用户使用偏好数据是小工具语句中由 iGoogle 托管的部分。有关 Userprefs 的详细信息，请参阅《小工具 API 开发人员指南》。
要在多个用户之间共享小工具的 Userprefs，该小工具必须在 <ModulePrefs> 部分包括 <optional feature="shareable-prefs"/> 行。例如，该小工具使用 list 数据类型 Userprefs 填充杂物列表。
以下是该小工具的代码：
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs
title="Our Grocery List"
scrolling="true">
<optional feature="shareable-prefs"/>
</ModulePrefs>
<UserPref name="mylist"
display_name="Add items"
datatype="list" />
<Content type="html">
<![CDATA[
<div id="content_div" style='color: #CC0099; font-family: serif; font-size: 120%;'></div>
<script type="text/javascript">
// Get userprefs
var prefs = new gadgets.Prefs();
// Get the list
var items = prefs.getArray("mylist");
var html = "";
// If there are no items in the list yet, display message.
if (items.length == 0)
{
html += "Edit the userprefs to add items to the list.";
}
else {
for (var i = 0; i < items.length ; i++) {
var term = (items[i]);
html += term + "<br />";
}
}
document.getElementById("content_div").innerHTML = html;
</script>
]]>
</Content>
</Module>
将支持可共享的用户偏好的小工具添加到 iGoogle 后，您就可以让它成为可协作的小工具，如下所示。
步骤 1：点击您要共享的小工具上的三角形并选择“共享该小工具”。
步骤 2：如果您是 Gmail 用户，请挑选您要与之共享的好友或键入他们的电子邮件地址。
步骤 3：决定您是希望好友能够编辑您的小工具内容，还是仅通过其 iGoogle 页面查看小工具内容。
点击“发送邀请”。您的好友会收到您邀请他们将该小工具添加到他们自己的 iGoogle 页面的电子邮件。
然后，您授权可编辑该小工具的好友便可以修改该小工具的 Userprefs，并将他们所做的更改发布到该小工具的所有共享版本中。
更新是已向用户好友发布的关于与 iGoogle 小工具交互时执行的操作的活动。更新小工具会显示所有已发布的更新（活动）的列表，该列表会从最新的开始排列，并会不断更新。
该示例小工具可让您在文本框中输入一个更新，然后点击“发布更新”来将其发布。发布后，就可通过点击更新小工具中的“立即刷新”看到该更新：
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Post Updates" >
<Require feature="opensocial-0.7"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<script type="text/javascript">
// Post an activity and set its title to be the text the user entered in the
// text box.
function postUpdate(form) {
var text = form.inputbox.value;
var div = document.getElementById('content_div');
var params = {};
params[opensocial.Activity.Field.TITLE] = text;
var activity = opensocial.newActivity(params);
opensocial.requestCreateActivity(activity, opensocial.CreateActivityPriority.HIGH);
div.innerHTML = "Update title is: " + activity.getField(opensocial.Activity.Field.TITLE);
}
</script>
<FORM NAME="myform" ACTION="" METHOD="GET">Add Update: <BR>
<INPUT TYPE="text" NAME="inputbox" VALUE=""><P>
<INPUT TYPE="button" NAME="button" Value="Post Update" onClick="postUpdate(this.form)">
</FORM>
<div id="content_div"></div>
]]>
</Content>
</Module>
以上示例只访问 Activity 对象的 TITLE 字段。iGoogle 还支持这些可选字段：BODY、MEDIA_ITEMS、STREAM_FAVICON_URL 和 STREAM_URL。
出于开发目的，iGoogle 测试区支持调用 getActivities() 和获取用户所有活动的功能。稍后，getActivities() 将只返回特定小工具的活动。
要使用此调试功能，请如下设置可选参数：
var optParams = {};
optParams[opensocial.DataRequest.ActivityRequestFields.APP_ID] = '*';
星号 (*) 是一个通配符，表示您想要获得所有活动。
下表显示哪些活动将显示在哪些位置：
| 活动类型 | 更新小工具 |
|---|---|
| 本机活动 | |
| 小工具安装和卸载 | 是 |
| 源于小工具的活动 | 是 |
为了避免小工具向更新小工具滥发消息，小工具每天可以向每位用户发布的更新在数量方面有上限限制。为了使开发更为容易，测试区目前没有该限制。有关详细信息，请参阅我们的“常见问题解答”。
使用 OpenSocial API 能够访问有关 iGoogle 用户的信息（以个人资料数据形式）。本部分描述 iGoogle 中可以使用哪些个人资料字段。iGoogle 测试区会为用户提供个人资料小工具以编辑其个人资料数据。
iGoogle 测试区允许您通过 Person 对象访问当前用户的以下字段：
getId()getDisplayName()getField(opensocial.Person.Field.THUMBNAIL_URL)
getField(opensocial.Person.Field.CURRENT_LOCATION)
下面的示例说明如何提取用户并显示其缩略图、名称、ID 和位置：
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Profile Example" scrolling="true">
<Require feature="opensocial-0.7"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<script type="text/javascript">
/**
* Request for viewer information.
*/
function getData() {
var req = opensocial.newDataRequest();
req.add(req.newFetchPersonRequest(opensocial.DataRequest.PersonId.VIEWER), 'viewer');
req.send(onLoadViewer);
};
/**
* Display the viewer's thumbnail, name, ID, and location.
*/
function onLoadViewer(dataResponse) {
var viewer = dataResponse.get('viewer').getData();
var thumb = viewer.getField(opensocial.Person.Field.THUMBNAIL_URL);
var loc = viewer.getField(opensocial.Person.Field.CURRENT_LOCATION);
var address = loc.getField(opensocial.Address.Field.UNSTRUCTURED_ADDRESS);
var html = "<img src=\"" + thumb + "\"/><br />";
html += "The ID for " + viewer.getDisplayName() + " is " + viewer.getId()+"<br />";
html += "The location for " + viewer.getDisplayName() + " is " + address;
document.getElementById('message').innerHTML = html;
};
gadgets.util.registerOnLoadHandler(getData);
</script>
<div id="message"> </div>
]]>
</Content>
</Module>
iGoogle 测试区限制单个用户实例可存储多少永久性数据（应用程序数据）（有关应用程序数据的更多讨论，请参阅《OpenSocial JavaScript 开发人员指南》）。该限制是 10 KB。如果尝试的应用程序数据写入操作超过此配额，就会因发生“超过配额”错误而失败。
有关 iGoogle 支持的语言和国家/地区的列表，请转至此处。有关编写可针对国际化受众轻松本地化的小工具的详细信息，请参阅《小工具 API 开发人员指南》。
要继续学习 OpenSocial API，请查看 OpenSocial API 主页上包含的其他文档和资料。