小工具

小工具 API
- 更多小工具

小工具 XML 参考

这是关于小工具规范 XML 的参考。

您可以参阅此处的 JavaScript 参考。

目前，gadgets.* JavaScript API 仅在也支持 OpenSocial API 的容器中工作。您仍然可以在支持小工具的所有应用程序（包括不支持 OpenSocial 的应用程序）中使用原始的“传统”小工具 API。

如果您有兴趣更深入地了解 gadgets.* API，请参阅小工具规范。

ModulePrefs 元素和属性

XML 文件中的 <ModulePrefs> 部分指定了小工具的特征，如标题、作者、首选大小等等。例如：

<Module>
  <ModulePrefs title="Developer Forum" 
    title_url="http://groups.google.com/group/Google-Gadgets-API" 
    height="200" 
    author="Jane Smith" 
    author_email="xxx@google.com"/> 
  <Content ...>
   ... content ...
  </Content> 
</Module>

小工具的用户不能更改这些属性。

<ModulePrefs> 用作所有元数据、功能和处理规则的容器元素。有关嵌套元素的说明，请参阅以下各自的部分。本部分总结了 <ModulePrefs> 中的元素和属性。在下面的部分，将用斜线表示嵌套级别。例如，/ModulePrefs/Locale 描述了嵌套于 <ModulePrefs> 元素中的 <Locale> 元素。这种情形可能会如下显示在小工具规范中：

<ModulePrefs>
  <Locale lang="en" country="us" />
  <Locale lang="ja" country="jp" />
</ModulePrefs>

/ModulePrefs

下表列出了所有容器都支持的 <ModulePrefs> 属性。有关任何容器特定的 <ModulePrefs> 属性，请参阅容器文档。

属性	说明
`title`	提供小工具标题的可选字符串。该标题显示在 iGoogle 的小工具标题栏中。如果该字符串包含用户使用偏好替换变量，并且您打算将小工具提交至 iGoogle 内容目录，您还应提供 `directory_title` 以用于目录显示。
`title_url`	提供小工具标题链接至的网址的可选字符串。例如，您可以将标题链接至与小工具相关的网页。
`description`	描述小工具的可选字符串。
`author`	列出小工具作者的可选字符串。
`author_email`	提供小工具作者电子邮件地址的可选字符串。您可以使用任何电子邮件系统，但是鉴于会收到大量垃圾邮件，因此不应使用个人电子邮件地址。一种方法是在小工具规范中使用 helensmith.feedback+coolgadget@gmail.com 形式的电子邮件地址。 Gmail 会省略加号 (+) 后的所有内容，所以该电子邮件地址可解释为 helensmith.feedback@gmail.com。您可以在此处创建 Gmail 帐户。
`screenshot`	提供小工具屏幕截图网址的可选字符串。该图片必须位于不能被 robots.txt 拦截的公共网站上。PNG 是首选格式，GIF 和 JPG 也可接受。小工具屏幕截图的宽度应为 280 像素。屏幕截图的高度应为所使用的小工具的“自然”高度。
`thumbnail`	给出小工具缩略图的网址的可选字符串。该图片必须位于不能被 robots.txt 拦截的公共网站上。PNG 是首选格式，GIF 和 JPG 也可接受。小工具缩略图应为 120x60 像素。

/ModulePrefs/Require 和 /ModulePrefs/Optional

<Require> 和 <Optional> 元素声明该小工具的功能从属关系。

属性：

"feature" -- 功能的名称。必需

示例：

<Require feature="dynamic-height"/>
<Optional feature="shareable-prefs"/>

/ModulePrefs/Require/Param 和 /ModulePrefs/Optional/Param

这些元素为功能提供配置参数。

属性：

"name" -- 参数的名称。必需。

ModulePrefs/Preload

<Preload> 元素可在小工具呈现过程中指示容器从远程源提取数据。该数据会嵌入在呈现的输出中，在执行小工具代码后就能立即使用。使用该方法可以减少小工具的反应时间，具体取决于远程服务器要呈现的内容。

属性：

"href" -- 指定要预先提取的数据位置的网址。必需。
"authz" -- 用于发出该请求的验证类型。有效值为 "none"（默认）、"signed" 和 "oauth"。可选。

ModulePrefs/Icon

<Icon> 元素指定容器可将特定小工具与其相关联的 16px x 16px 图片（例如，容器可能会在左侧导航栏中的小工具名称旁显示图标）。

<Icon> 标签的内容可为以下选项之一：

指向网络上图片文件的 HTTP 网址
嵌入的 base64 编码的图片数据。

属性：

"mode" -- 嵌入图片时用于图标的编码。目前，只支持 base64。可选。
"type" -- 嵌入的图标文本的 MIME。可选。

示例：

<ModulePrefs title="My gadget">
  <Icon>http://remote/favicon.ico</Icon>
</ModulePrefs>

<ModulePrefs title="My gadget">
  <Icon mode="base64" type="image/png">base64 encoded data</Icon>
</ModulePrefs>

ModulePrefs/Locale

<Locale> 元素指定您小工具支持的区域设置。如小工具与国际化中所述，您也可以用它来指定消息包。

属性：

"lang" -- 与区域设置相关联的语言。可选。
"country" -- 与区域设置相关联的国家/地区。可选。
"messages" -- 指向消息包的网址。消息包是包含给定区域的翻译字符串的 XML 文件。有关详细信息，请参阅小工具和国际化。可选。
"language_direction" -- 小工具的方向。可选。其值可以是“rtl”（从右到左），也可以是“ltr”（从左到右）。默认为“ltr”。该属性允许您创建既支持从左到右语言又支持从右到左语言的小工具。有关该主题的更多讨论内容，请参阅创建双向小工具。您也可以与 language_direction 配合使用以下替换变量：
- __BIDI_START_EDGE__：当小工具处于 LTR 模式时，该值为“左”；当小工具处于 RTL 模式时，该值为“右”。
- __BIDI_END_EDGE__：当小工具处于 LTR 模式时，该值为“右”；当小工具处于 RTL 模式时，该值为“左”。
- __BIDI_DIR__：当小工具处于 LTR 模式时，该变量的值为“ltr”；当小工具处于 RTL 模式时，其值为“rtl”。
- __BIDI_REVERSE_DIR__：当小工具处于 LTR 模式时，该变量的值为“ltr”；当小工具处于 RTL 模式时，其值为“rtl”。

例如，以下代码段指定了两个不同的区域设置：

<ModulePrefs>
  <Locale lang="en" country="us" />
  <Locale lang="ja" country="jp" />
</ModulePrefs>

“lang”（语言）和“country”属性都是可选的，但您必须为每个 <Locale> 指定至少一个属性。如果您忽略了任一属性，则值等于“*”和“ALL”。如果您指定了国家/地区而未指定语言，则将认为您的小工具支持与该国家/地区相关的所有语言。类似地，如果您指定了语言而未指定国家/地区，则将认为您的小工具支持与该语言相关的所有国家/地区。

语言的有效值是 ISO639-1 两位语言代码，国家/地区的有效值是 ISO 3166-1 alpha-2 代码。

有一些常用语言规则的例外情况：

简体中文： lang="zh-cn"（通常，country=“cn”）。
繁体中文：lang="zh-tw"（中国台湾和香港特别行政区通常分别是 country=“tw”或“hk”）。

ModulePrefs/Link

容器特定的链接。例如，此标签可用于支持新链接类型（例如 gadgetsHelp 和 gadgetsSupport）。

属性：

"rel" -- 可触发生命周期事件的值。必需。
"href" -- 网址。必需。
"method" -- 发送请求应当采用的方法（POST 或 GET）。默认为 GET。可选。

容器可以选择通过向网址端点发送相关查询参数来支持向应用程序开发人员站点发送生命周期事件。要接收这些事件，您可以使用 <Link> 标签。每个 <Link> 标签都有 rel 和 href 属性。href 属性表示发送事件 ping 信息的端点。如果 rel 属性是 "opensocialevent"，那么所有事件都会发送到该端点。如果 rel 属性与 "opensocialevent.TYPE", 相匹配，那么 TYPE 事件会发送到该端点。可选的方法属性可以设置为 POST 或 GET，以指定应发送请求的方式。默认为 GET。以下是一些示例：

<link rel="event" href="http://www.example.com/pingme" method="POST/>
<link rel="event.addapp" href="http://www.example.com/add" />
<link rel="event.removeapp" href="http://www.example.com/remove" />

大多数事件都具有与一个或多个 opensocial ID 值有关的信息。这些 ID 值会作为一个或多个 ID 属性进行传递。请注意，单个 ping 信息可以通过指定许多 ID 值来汇总多个事件。

定义了以下事件类型：

addapp -- 已安装了应用程序 (ID) 的用户。可选的“从”指定了用户添加此应用程序的方式。可能的值为 "invite"、"gallery" 和 "external"。
removeapp -- 已删除此应用程序的用户的 ID。
app -- action={enabled|disabled|approved} reason={policy|quota|maintenance}
invite -- id 是被邀请的用户，from_id 是发送邀请的 ID。

用户使用偏好

某些小工具需要给用户一个提供用户特定信息的途径。例如，天气小工具可能要求用户提供其邮政编码。XML 文件中的用户使用偏好 (<UserPref>) 部分介绍了可在小工具运行时转换为用户界面控件的用户输入字段。

下表列出了 <UserPref> 属性：

属性	说明
`name`	用户使用偏好必需的“符号”名称；如果未定义`display_name`，则在编辑期间对用户显示。必须仅包含字母、数字和下划线，即，常规表达式 ^[a-zA-Z0-9_]+$。必须是唯一的。
`display_name`	在编辑窗口中显示在用户使用偏好旁边的可选字符串。必须是唯一的。
`urlparam`	作为内容 `type="url"` 的参数名称传送的可选字符串。
`datatype`	表示该属性的数据类型的可选字符串。可以是`string`、`bool`、`enum`、`hidden`（非可见或用户不可编辑的字符串）、`list`（由用户输入生成的动态数组）或`location`（用于基于 Google 地图的小工具）。默认为 `string`。
`required`	表示该用户使用偏好是否为必需的可选布尔变量（`true` 或 `false`）。默认为 `false`。
`default_value`	表示用户使用偏好的默认值的可选字符串。

可使用用户使用偏好 JavaScript API 来从小工具访问用户使用偏好，例如：

<script type="text/javascript">
   var prefs = new _IG_Prefs();
   var someStringPref = prefs.getString("StringPrefName");
   var someIntPref = prefs.getInt("IntPrefName");
   var someBoolPref = prefs.getBool("BoolPrefName");
</script>

枚举数据类型

您可以为 <UserPref> datatype属性指定的一个值为enum。enum 数据类型在用户界面中显示为选项菜单。您可以使用 <EnumValue> 指定菜单内容。

例如，该 <UserPref> 允许用户设置游戏的难易级别。显示在菜单中的每个值（简单、中等和困难）是使用 <EnumValue> 标签来定义的。

<UserPref name="difficulty" 
     display_name="Difficulty"
     datatype="enum"
     default_value="4">
  <EnumValue value="3" display_value="Easy"/>
  <EnumValue value="4" display_value="Medium"/>
  <EnumValue value="5" display_value="Hard"/>
</UserPref>

下表列出了 <EnumValue> 属性：

属性	说明
`value`	提供唯一值的必选字符串。除非提供`display_value`，否则该值显示在用户使用偏好编辑框的菜单中。
`display_value`	显示在用户使用偏好编辑框的菜单中的可选字符串。如果您不指定 `display_value`，则 `value` 显示在用户界面中。

内容部分

<Content> 部分定义了 Content 类型，是包含自身内容还是引用外部内容。<Content> 部分是小工具属性和用户使用偏好与编程逻辑和格式化信息结合成为可运行小工具的地方。有关 Content 类型的更多论述内容，请参阅选择 Content 类型。

下表列出了 <Content> 属性：

属性	说明
`type`	提供 Content 类型的可选字符串。可能值包括 `html` 和 `url`。默认为 `html`。
`href`	提供目标网址的字符串。需要 `type="url"`，而不允许使用其他 Content 类型。
`cdata`	可选字符串。对于 HTML，包含要提交至 iframe 中的原始 HTML。

JavaScript 参考