新版 Google 协作平台已于 2016 年 11 月 22 日发布。协作平台 API 无法访问或修改使用此版本创建的网站，但仍可以访问传统版协作平台。

此页面由 Cloud Translation API 翻译。

Google 协作平台的小工具

Google 的小工具是可以嵌入到网页中的 HTML 和 JavaScript 应用页面和其他应用，包括协作平台。这些小工具能够将外部和动态内容，如小型应用和数据库驱动的列表，文字和图片，以提供顺畅的用户体验。

每个 Google 协作平台页面都是一种潜在的小工具容器。此外，通过 Google 协作平台 Data API（可与这些 API 结合使用）利用 Google 小工具开发功能强大的应用程序。这意味着，作为小工具开发者利用传统版 Google 协作平台 API 为其他 Web 开发者及其受众群体构建富有吸引力的工具，供您自己使用。

您为 Google 协作平台创建小工具后，它就可以供数百万活跃用户使用用户。只需将您的小工具提交给我们，它就会显示在适当的位置，用户可以轻松浏览、配置您的小工具并将其添加到他们的协作平台。

现在您应该知道，{sites_name_short} 是一个很棒的小工具发布平台，还在等什么？立即开始为 Google 协作平台构建小工具吧！

网站小工具概述

一般来说，小工具是一些小型实用程序，可用于生成外部信息或将外部信息提取到网络中。页面。简单来说，小工具是一个小型 .xml 文件，它使用同时在多个网页中提供。在 Google 协作平台中，包括小工具结果（用作此外部信息渠道的 iframe）中。一些小工具已不复存在而是指从其他网站传递信息的 iframe。

更高级的小工具可收集动态内容，并为内的交互式应用提供。请参阅示例小工具。

小工具包含以下组件：

小工具规范文件 - 一种封装 HTML 和 JavaScript 函数的 .xml 文件。
容器页面 - 插入小工具的网页，此例中为 Google 网站。
外部数据源 - 此为可选内容，可与 .xml 文件位于同一位置，但通常由小工具规范通过 HTTP 调用以提供其结果。

专为网站的所有浏览者都可以使用网站。它们往往具有互动性，侧重于拉取用于呈现动态内容，而不是展示效果。这种设计旨在对网页内容网站。

日历小工具就是这一区别的一个很好的例子。中的个性化日历小工具则可能默认显示已登录用户的日历，而日历小工具可能会允许协作者从各种地点专属日历中进行选择。

Google 协作平台小工具可让您显示来自外部来源（例如来自不同但相关的性能信息中心的实时图表）以及直接在 Google 协作平台中发布的说明性文字。这样既能节省视觉空间同一视图中有关同一主题的不同信息。通过小工具，您还可以包含否则可能会被 Google 协作平台安全检查阻止的动态内容。

警告：使用旧版构建的小工具 Google 小工具 API 可以在 Google 协作平台中使用，但不受官方支持。基于 Feed 的内置小工具同样不受支持因此，Google 建议您使用最新的小工具.*API。请参阅此帖子了解相关说明：
http://igoogledeveloper.blogspot.com/2009/09/more-things-change-more-they-stay-same.html

示例小工具

下面是一个简单但受欢迎的包含小工具，它仅提供用于传递其他网络内容的 iframe：

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Include gadget (iframe)" title_url="http://sites.google.com/"
          description="Include another web page in your Google Site"
          thumbnail="https://www.gstatic.com/sites-gadgets/common/images/sites-icon-gadget-thumb.png"
          screenshot="https://www.gstatic.com/sites-gadgets/common/images/sites-icon-gadget-ss.png"
          height="800" width="600" author="Google">
    <Require feature="dynamic-height"/>
  </ModulePrefs>
  <UserPref name="iframeURL" display_name="URL to content" required="true"/>
  <UserPref name="scroll" display_name="Display scrollbar" default_value="auto" datatype="enum">
    <EnumValue value="auto" display_value="Automatic"/>
    <EnumValue value="no" display_value="No"/>
    <EnumValue value="yes" display_value="Yes"/>
  </UserPref>
  <Content type="html" view="default,canvas">
  <div id='dest'><img src="http://www.google.com/ig/images/spinner.gif"></div>
  <script type="text/javascript">
  gadgets.util.registerOnLoadHandler(doRender);

  function doRender(){
    // setup variables
    var prefs = new gadgets.Prefs();
    var iframeURL = prefs.getString('iframeURL');
    var scroll = prefs.getString('scroll');
    var height = 800;
    var width = 600;

    if (gadgets.window) {
      var viewport = gadgets.window.getViewportDimensions();
      if (viewport.width) {
        var width = viewport.width;
      }
      if (viewport.height) {
        var height = viewport.height;
      }
    }

    var iframe = document.createElement('iframe');
    iframe.setAttribute('width', width + 'px');
    iframe.setAttribute('height', height + 'px');
    iframe.setAttribute('frameborder','no');
    if(scroll){
      iframe.setAttribute('scrolling', scroll);
    }
    iframe.setAttribute('src', iframeURL);

    // set the slideshow to the placeholder div
    var dest = document.getElementById('dest');
    dest.innerHTML = '';
    dest.appendChild(iframe);
  }
  </script>
  </Content>
</Module>

请参阅使用入门：小工具*。API 获取有关小工具标签和预期内容的完整说明。

托管您的小工具

无论您的小工具有什么用途，其文件都必须位于万维网上，才能被找到并。任何可通过 HTTP 无需身份验证即可访问的在线位置用途。请记住，您的小工具必须在公开目录中发布才能被选中。否则，用户必须通过直接插入网址来进行嵌入。

以下是您的小工具托管选项：

App Engine - 能够存储您的小工具所需的所有文件。需要进行一些设置，即创建项目并上传后续文件。但可以轻松地扩展到大量用户。您可以创建一个应用来存储所有小工具，再创建一个应用来提供静态文件，其中包括类似于以下内容的 app.yaml 文件：
```
application: <your app name>
version: 1
runtime: python
api_version: 1

handlers:
- url: /.*
  static_dir: static
```
如果将所有小工具文件放在静态目录中，则可以编辑本地目录中的文件，并在每次进行更改时部署到 App Engine。如果您有文件 /static/gadget.xml，则其网址将是：http://<your-app-name>.appspot.com/static/gadget.xml
您选择的任何在线位置 - 完全由您控制，而且您的全权负责。您的服务器停机可能导致您的小工具用户中断服务。

构建您的小工具

小工具只是 HTML 以及封装在 XML 中的 JavaScript、Flash 或 Silverlight（可选）。小工具开发者指南提供了构建您自己的小工具所需的所有详细信息。此外，OpenSocial 模板还可用于在小工具中快速构建社交应用。

以下是构建 Google 协作平台小工具的概要步骤：

确定您的小工具的托管位置。有关选项说明，请参阅托管小工具部分。
使用您选择的文本编辑器创建将用作规范的新 .xml 文件。
确定内容类型（HTML 或网址），并在小工具 .xml 文件中指定，如下所示：
<Content type="html">
这几乎总是 HTML，即假定所有内容都是在 .xml 文件中直接提供的。但是，如果您打算在单独的文件中提供内容，请使用网址内容类型。有关两者差异的完整说明，请参阅选择内容类型。
在小工具 .xml 文件中或规范调用的单独文件中创建内容。有关检查现有小工具的方法，请参阅查看示例小工具部分。
定义用户可以更改的小工具的基本偏好设置。有关说明，请参阅定义用户偏好设置。如需提供更高级的配置，请参阅允许进行高级用户配置部分。
定义仅小工具作者可以更改的模块偏好设置。要了解更多详情，请参阅定义小工具偏好设置。
测试小工具。有关说明，请参阅测试小工具部分。

嵌入您的小工具

在 Google 协作平台网页中嵌入小工具的方法有两种：从 Google 协作平台小工具目录（与 iGoogle 小工具目录同步）中选择该小工具，或者直接加入其网址。

要在 Google 协作平台中嵌入小工具，请执行以下操作：

转到将包含新小工具的“网站”页面。
打开要修改的页面。
选择插入 >更多小工具。
搜索相应小工具，从左侧的类别中选择它，或者点击按网址添加小工具，然后将相应网址粘贴到您的 .xml 文件中。然后点击添加。
提示：同样的“按网址添加小工具”方法也可以用于嵌入来自 iGoogle 和其他任何在线的小工具。
指定小工具的尺寸，从可用设置中进行选择，然后点击确定。小工具已添加。
保存页面以查看并测试站点中的小工具。

测试您的小工具

构建小工具后，您应在使用该小工具并让他人做同样的事情。通过创建一个或多个测试 Google 协作平台并进行嵌入，手动测试您的小工具。请参见嵌入您的小工具部分，了解具体步骤。通过您的小工具的功能和外观取决于包含。因此，调试小工具的最佳方法是在实际的 Google 协作平台尝试在不同的网站主题之间进行切换，以确保您的小工具在每个主题中都能正确显示。

测试小工具时，不可避免地会发现错误并需要更正添加到您的小工具 .xml 文件中。在以下情况下，您应停用小工具缓存：调整 XML。否则，您的更改不会显示在页面上。系统会缓存小工具规范，除非您指示网站不要这样做。要在开发过程中绕过缓存，请将以下内容添加到包含小工具的网站页面网址（而不是小工具规范 .xml 文件的网址）的末尾：

 ?nocache=1

Google 协作平台提供了用于添加和配置小工具的标准用户界面。添加小工具后，它会显示一个预览，并显示任何可配置的 UserPref 参数。测试对各种配置值和将小工具添加到测试网站。确认您的小工具在。您应该测试网站管理员都可以正确配置您定义的任何 UserPref。

然后，参阅“发布小工具”的“准备发布”部分，进行其他测试。

允许进行高级用户配置

所有小工具都提供设置基本用户偏好设置的功能，通过小工具规范文件的 UserPref 部分完成。这些通常会影响尺寸、滚动条、边框、标题和特定于小工具的设置，如此处的屏幕截图所示：

Google 协作平台小工具用户偏好设置

不过，在很多情况下，小工具受益于比标准 UserPref 组件更高级的偏好设置。偏好设置通常需要包含自定义业务逻辑、验证或选择器等功能。从小工具的 UserPref 部分生成的界面支持有限数量的数据类型（字符串、枚举等），因此无法对网址或日期等输入进行验证。

此外，在查看器和编辑器均相同的容器（如 iGoogle）中，小工具作者可以将配置扩展为标准视图的一部分。在 Google 协作平台中，查看者并非总是编辑者，因此小工具作者无法保证查看的用户有权更新偏好设置。Google 协作平台等社交容器不允许任何用户修改偏好设置，只能允许修改作者。

在 Google 协作平台中，由 UserPref 生成的基本小工具偏好设置界面可以替换为配置视图，其中可能会提供许多其他偏好设置和数据类型，如以下屏幕截图所示：

网站小工具配置视图

在插入时或修改时，配置视图会取代 UserPref 设置，并允许您使用自定义界面来设置用户偏好设置。您还可以使用自定义输入元素，例如用于选择地图上的位置，而不是输入地图坐标。

开发者可以使用标准 setprefs API 将偏好设置保存在此视图中。如需了解更多详情，请参阅小工具 XML 参考文档和开发者基础知识的“保存状态”部分。这些视图允许容器应用提供补充性配置信息，并在 UserPref 部分后面的小工具 .xml 规范文件中建立，起始标记类似于：

  <Content type="html" view="configuration" preferred_height="150">

例如，提供上述配置视图的 news.xml 小工具就包含此部分：

<Content type="html" view="configuration" preferred_height="300">
<style type="text/css">
  .config-options {
    margin: 10px;
  }
  .label {
    font-weight: bold;
    width: 35%;
    vertical-align: top;
  }
  .gray {
    color:#666666;
  }
  html {
    font-family:arial,sans-serif;
    font-size:0.81em;
    font-size-adjust:none;
    font-style:normal;
    font-variant:normal;
    font-weight:normal;
    line-height:1.5;
  }
  a:link, a:visited, a:active { text-decoration: none }
</style>
  <img alt="Google Web Elements" src="http://www.google.com/webelements/images/web_elements_logo.gif"/>
  <table class="config-options">
  <tr>
  <td align="left" class="label">Size:</td>
  <td align="left">
  <select id="size" onchange="Update()">
  <option selected="selected" value="300x250">Medium rectangle (300x250)</option>
  <option value="728x90">Leaderboard (728x90)</option>
  </select>
  </td>
  </tr>
  <tr>
  <td align="left" class="label">Select sections:</td>
  <td align="left">
  <table>
  <tbody><tr>
  <td><input type="checkbox" onclick="Update()" id="sec_h" value="h"/> Top Stories</td>
  <td><input type="checkbox" onclick="Update()" id="sec_w" value="w"/> World</td>
  <td><input type="checkbox" onclick="Update()" id="sec_b" value="b"/> Business</td>
  </tr><tr>
  <td><input type="checkbox" onclick="Update()" id="sec_p" value="p"/> Politics</td>
  <td><input type="checkbox" onclick="Update()" id="sec_n" value="n"/> Nation</td>
  <td><input type="checkbox" onclick="Update()" id="sec_e" value="e"/> Entertainment</td>
  </tr><tr>
  <td><input type="checkbox" onclick="Update()" id="sec_t" value="t"/> Technology</td>
  <td><input type="checkbox" onclick="Update()" id="sec_s" value="s"/> Sports</td>
  <td><input type="checkbox" onclick="Update()" id="sec_m" value="m"/> Health</td>
  </tr></tbody>
  </table>
  </td>
  </tr>
  <tr>
  <td align="left" class="label">Or create one:</td>
  <td align="left">
  <input type="text" id="query" onchange="Update()"/>
  <br/>
  <span class="gray">Example: 2010 Olympics</span>
  </td>
  </tr>
  <tr>
  <td colspan="2">
  <div id="preview" style="margin-top:10px;overflow:auto;width:100%;">
  <iframe id="preview_ifr" frameborder="0" marginwidth="0" marginheight="0" border="0"
  style="border:0;margin:0;"
  scrolling="no" allowtransparency="true"></iframe>
  </div>
  </td>
  </tr>
  </table>
  <script type="text/javascript">
  var prefs = new gadgets.Prefs();

  function getSelectedTopics() {
    var selected = [];
    var topics = ['h', 'w', 'b', 'p', 'n', 'e', 't', 's', 'm'];
    for (var i = 0; i < topics.length; i++) {
      if (document.getElementById('sec_' + topics[i]).checked) {
        selected.push(topics[i]);
      }
    }
    return selected.join(',');
  }

  function setSelectedTopics(selected) {
    if (selected && selected.length >= 0) {
      var topics = selected.split(',');
      for (var i = 0; i < topics.length; i++) {
        document.getElementById('sec_' + topics[i]).checked = true;
      }
    }
  }

  function Update() {
    var topic = getSelectedTopics();
    var query = document.getElementById('query').value;
    var size = document.getElementById('size').value;

    var url = 'http://www.google.com/uds/modules/elements/newsshow/iframe.html?rsz=large&' +
        'format=SIZE&element=true';
    var iframe = document.getElementById('preview_ifr');
    url = url.replace(/SIZE/, size);
    if (topic.length > 0) {
      url += '&topic=' + topic;
    }
    if (query.length > 0) {
      url += '&q=' + encodeURIComponent(query);
    }
    iframe.src = url;
    if (size == '728x90') {
      iframe.style.width = '728px';
      iframe.style.height = '90px'
    } else {
      iframe.style.width = '300px';
      iframe.style.height = '250px';
    }
    prefs.set('size', size);
    prefs.set('topic', topic);
    prefs.set('query', query);
    gadgets.window.adjustHeight();
  }

  function Initialize() {
    var size = '__UP_size__';
    if (size.length > 0) {
      document.getElementById('size').value = size;
    }
    var query = '__UP_query__';
    if (query.length > 0) {
      document.getElementById('query').value = query;
    }
    setSelectedTopics('__UP_topic__');
    Update();
  }

  gadgets.util.registerOnLoadHandler(Initialize);
  </script>
  </Content>

通过配置视图，您可以找到此示例以及 Google 协作平台的其他专用小工具：
https://www.gstatic.com/sites-gadgets/news/news.xml
http://gadgets.pardonmyzinger.org/static/qrcode.xml
https://www.gstatic.com/sites-gadgets/news/youtube_news.xml

遵循有关 Google 协作平台小工具的最佳做法

网站用户希望在网络上呈现良好面貌。请遵循以下最佳做法 Google 小工具可与 Google 协作平台中使用的众多主题完美结合。请参阅小工具概览，详细了解如何创建小工具。其余本部分提供了专门针对 Google 协作平台小工具的指南。

请勿在小工具的规格或标题中添加敏感信息，因为公众可以看到您的小工具。例如，不要包含内部项目名称。
为了最大限度地降低您的小工具的能见度，请不要将其提交到 iGoogle 小工具目录或任何其他公开服务。而是让所有用户都仅通过网址添加该网址。此外，您还可以创建仅针对其内容调用另一个文件的网址类型的小工具（而不是包含所有内容的典型 HTML 类型）。如果使用此直通选项，系统只会显示第二个文件的网址。有关 HTML 和网址小工具的区别，请参见“开发者基础知识”的“选择内容类型”部分；有关遮盖小工具的其他方法，请参阅编写自己的小工具中的“小工具公开”部分。
最重要的是，请在许多不同的网站上测试您的小工具。修改网站的背景颜色、文字颜色和字体，以确保您的小工具能与各种模板相得益彰。

返回页首