创建用户界面

本文档介绍了如何将不同的用户界面元素添加到您的小工具。

目录

1. 视图
   1. 包括多个内容部分
   2. 合并视图
   3. 确定当前的小工具视图
   4. 获取所有可用视图
   5. 浏览至另一个视图
   6. 通过 requestNavigateTo() 传递数据
2. 管理小工具高度
3. 设置小工具标题
4. 标签
   1. 标签对象分析
   2. 工作原理
   3. 按索引处理标签
   4. 自定义标签显示
5. 小消息
   1. 工作原理
   2. 在不同位置创建消息
   3. 使用 DOM 方法创建消息
   4. 创建计时器消息
   5. 创建静态消息
   6. 自定义小消息显示
6. Flash
   1. Flash 示例

视图

视图是容器中显示小工具的位置。不同视图具有不同特性。例如，容器可能有一个以较小的格式显示小工具的视图，以及一个以整个页面格式显示小工具的视图。有关您的容器支持的视图的列表，请参阅容器文档。

例如，在 iGoogle 测试区中，小工具以主页视图模式（“小模式”）显示，这表示它以列布局的形式出现在其他小工具中间。要创建您的小工具的画布视图（“大模式”），在该视图中小工具会水平扩展至跨越整个小工具区域，您必须为“画布”视图类型定义一个 <Content> 部分，如下所示：

<Content type="html" view="canvas"> 

假设您为针对 iGoogle 的小工具的画布视图定义了 <Content> 部分。您还必须创建 <Content> 部分，以便在主页视图中正确地显示小工具。这可以是“默认”或“主页”。有关编写支持多个 <Content> 部分的小工具的更多讨论，请参阅加入多个内容部分。

下面是某个版本的 Hello World 小工具，它为“主页”和“画布”定义 <Content> 部分视图。其宽度会根据您将其显示在主页视图中还是画布视图中而改变。

<?xml version="1.0" encoding="UTF-8" ?>
<Module> 
  <ModulePrefs title="Hello World!">
    <Require feature="opensocial-0.8" />
  </ModulePrefs>
  <Content type="html" view="home">
    <![CDATA[
      Hello, small world!
    ]]>  
  </Content>
  <Content type="html" view="canvas"> 
    <![CDATA[
      Hello, big world!
    ]]> 
  </Content>
</Module>

包括多个内容部分

在小工具 XML 文件中可以包括多个 <Content> 部分，其中每个 <Content> 部分都公布其应该呈现的视图。文档树中所有 <Content> 部分都应该是同一类，并使用可选参数 view= 定义应在其中呈现的视图。

两个内容部分

下面的简单示例显示了具有两个内容部分的小工具，一个用于“个人资料”，另一个用于“画布”。以下是 Orkut 容器支持的视图。

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Multiple Content Sections (version 1)">
    <Require feature="opensocial-0.8" />
  </ModulePrefs>
  <Content type="html" view="profile">
  <![CDATA[
    <h1>Profile</h1>
  ]]>
  </Content>
  <Content type="html" view="canvas">
  <![CDATA[
    <h1>Canvas</h1>
  ]]>
  </Content>
</Module>

输出如下：

个人资料视图

<h1>Profile</h1>

画布视图

<h1>Canvas</h1>

画布或个人资料以外的其他任何视图

不显示任何内容

指定了多个视图的内容部分

内容部分可指定多个视图，由逗号隔开：

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Multiple Content Sections (version 2)">
    <Require feature="opensocial-0.8" />
  </ModulePrefs>
  <Content type="html" view="canvas,profile">
  <![CDATA[
    <h1>Canvas and Profile</h1>
  ]]>
  </Content>
</Module>

输出如下：

个人资料视图

<h1>Canvas and Profile</h1>

画布视图

<h1>Canvas and Profile</h1>

画布或个人资料以外的其他任何视图

不显示任何内容

指定了视图的内容部分以及没有指定默认内容部分的内容部分

如果指定具有视图参数的内容部分，则该内容部分仅会显示在该视图上。如果未指定默认内容部分，则其他视图将不会显示任何内容。

<?xml version="1.0" encoding="UTF-8" ?>
<Module>  
  <ModulePrefs title="Multiple Content Sections (version 3)">
    <Require feature="opensocial-0.8" />
  </ModulePrefs>
  <Content type="html" view="profile">
  <![CDATA[
    <h1>Profile</h1>
  ]]>        
  </Content>
</Module>

输出如下：

个人资料视图

<h1>Profile</h1>

画布视图

不显示任何内容

画布或个人资料以外的其他任何视图

不显示任何内容

指定了视图并指定了默认内容部分的内容部分

要指定默认内容部分，只需定义没有视图参数的内容部分即可：

<Module>  
  <ModulePrefs title="Multiple Content Sections (version 4)">
    <Require feature="opensocial-0.8" />
  </ModulePrefs>
  <Content type="html" view="profile">
  <![CDATA[
    <h1>Profile</h1>
  ]]>        
  </Content>
  <Content type="html">
  <![CDATA[
    <h1>Default</h1>
  ]]>
  </Content>
</Module>

输出如下：

个人资料视图

<h1>Profile</h1>

画布视图

<h1>Default</h1>

画布或个人资料以外的其他任何视图

<h1>Default</h1>

完整示例

您可以在一个小工具中使用所有这些技术：

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Multiple Content Sections (version 5)">
    <Require feature="opensocial-0.8" />
  </ModulePrefs>
  <Content type="html" view="profile">
  <![CDATA[
    <h1>Profile</h1>
  ]]>
  </Content>
  <Content type="html" view="canvas">
  <![CDATA[
    <h1>Canvas</h1>
  ]]>
  </Content>
  <Content type="html" view="canvas,profile">
  <![CDATA[
    <h2>This shows up in canvas and profile views</h2>
  ]]>
  </Content>
  <Content type="html">
  <![CDATA[
    <h1>Default</h1>
    <h2>The content in this section only shows up if no other content sections are applicable</h2>
  ]]>
  </Content>
</Module>

输出如下：

个人资料视图

<h1>Profile</h1>
<h2>This shows up in canvas and profile views</h2>

画布视图

<h1>Canvas</h1>
<h2>This shows up in canvas and profile views</h2>

画布或个人资料以外的其他任何视图

<h1>Default</h1>
<h2>The content in this section only shows up if no other content sections are applicable</h2>

合并视图

所有 OpenSocial 容器都支持视图，但是每个容器可能支持一组不同的视图。例如，iGoogle 有一个称为 home 的小视图，但在 Orkut 中该小视图称为 profile。

假设您要编写一个对于 iGoogle 上的 home 和 Orkut 上的profile 具有相同显示的小工具。无需创建重复的 <Content> 部分即可合并单个 <Content> 部分的视图，如下所示：

<Content type="html" view="home,profile">

您可以在不同容器之间或同一容器内使用此技术。例如，处理单个 <Content> 部分中不同大小的视图的演示逻辑的小工具可以通过公布 view="home,canvas" 将这种支持扩展到画布页面。

确定当前的小工具视图

获取当前视图的最容易的途径是在您的小工具模块使用偏好中包含“视图”功能。

<ModulePrefs title="Views example"> 
  <Require feature="views" />
</ModulePrefs>
    

包含视图功能时，您可以通过调用 gadget.util.getCurrentView() 函数来获取当前的视图。

以下示例演示如何获取当前视图并根据返回值有条件地执行代码：

function getViewName() {
  return gadgets.views.getCurrentView().getName();
}

if (getViewName() == "canvas") {
  /* Do canvas specific stuff here */
}

if (getViewName() == "home") {
  /* Do home specific stuff here */
}
    

获取所有可用视图

通过调用 gadgets.views.getSupportedViews() 函数获取可用的 View 对象。

var supported_views = gadgets.views.getSupportedViews();
    

getSupportedViews 调用返回的对象包含代表 iGoogle 中的所有可用视图（按照视图名称进行索引）的 gadgets.views.View 对象。

浏览至另一个视图

如果您想提供指向其他视图的链接，则需要向 gadgets.views.requestNavigateTo() 方法传递一个 gadgets.views.View 对象。 您可以选择使用 getSupportedViews() 调用返回的对象之一。以下代码示例演示了此方法：

  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>

    

通过 requestNavigateTo() 传递数据

如果您正使用 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>
    

管理小工具高度

默认情况下，小工具的高度为 200 像素。您可以使用 <ModulePrefs> 属性 height="nn" 来指定大于或小于默认高度的静态高度。如果内容高度使小工具超过了其指定高度，您可以使用 <ModulePrefs> 属性 scrolling="true" 来使小工具有垂直滚动条。

但是某些小工具需要能够动态地更改其高度。例如，假设您有一个列表小工具，其高度需要根据列表的内容扩大和缩小。当用户向列表添加项目时，小工具增高。当他们清除列表时，小工具恢复到其原始高度。运行的小工具可能如下所示：

要使您的小工具能够自行调整大小，您需要将以下内容添加到您的小工具规范中：

• <Require feature="dynamic-height"/> 标签（位于 <ModulePrefs> 下），用于通知小工具加载 dynamic-height 库。
• 当内容有所更改时，或发生其他需要小工具自行调整大小的事件时，将调用 JavaScript 函数 gadgets.window.adjustHeight()。

例如，以下是杂货店列表小工具的小工具规范：

<?xml version="1.0" encoding="UTF-8" ?> 
<Module>
  <ModulePrefs title="Dynamic Height" 
    height="100"> 
    <Require feature="dynamic-height"/>
  </ModulePrefs>
  <Content type="html">
  <![CDATA[
    <script type="text/javascript">
    // This example lets users add items to a grocery list and then clear the list.
    // When items are added or cleared, the gadget resizes itself.
    var mylist = "";
    var flag = 0;

    // Function that is invoked whenever user clicks the Add button to add an
    // item to the list.
    function addToList (form) {
        var input = _trim(form.inputbox.value);
        if (input == "") {
            return;
        }

        // Make alternating lines green/white, depending on value of flag variable.
        if(flag == 0){
            mylist += "<div style='padding-left: 5px;background-color: #E6FFE6; font-family:Arial, Helvetica;'>" +input + "</div>";
            flag = 1;
        }
        else {
            mylist += "<div style='padding-left: 5px;font-family:Arial, Helvetica;'>" +input + "</div>";
            flag = 0;
        }

        // Call setContent to output HTML to div and resize gadget
        setContent(mylist);
    }

    // Clear the list
    function clearList(form) {
        // Call setContent to remove all items from the list and resize the gadget
        setContent("");
    }

    // Outputs content to the div and resizes the gadget
    function setContent(html) {
        document.getElementById('content_div').innerHTML = html;

       // Tells gadget to resize itself
       gadgets.window.adjustHeight();
    }
    </script>
  <FORM NAME="myform" ACTION="" METHOD="GET"><BR>
  <INPUT TYPE="text" NAME="inputbox" VALUE="">
  <INPUT TYPE="button" NAME="button" Value="Add" onClick="addToList(this.form)">
  <INPUT TYPE="button" NAME="button2" Value="Clear" onClick="clearList(this.form)">
  </FORM>
  <div id="content_div"></div>
  ]]>
  </Content>
</Module>

对于测试小工具的宽度和高度的指导原则，请参阅测试宽度和高度。

设置小工具标题

您可以使用 gadgets.window.setTitle() 函数通过编程方式设置小工具的标题。要使用此函数，小工具规范必须包括以下内容：

• <ModulePrefs> 下的 <Require feature="settitle"/> 标签，用于通知小工具加载 settitle 库。
• 调用 gadgets.window.setTitle() 设置小工具标题。

该示例提供了使用户可以设置小工具标题的文本字段：

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Set Title Example">
    <Require feature="settitle"/>
  </ModulePrefs>
  <Content type="html">
  <![CDATA[
    <script type="text/javascript">
    function changeTitle(form) {
      var newTitle = form.inputbox.value;
      gadgets.window.setTitle(newTitle);	 
    }
    </script>
<FORM NAME="myform" ACTION="" METHOD="GET">Change the Gadget Title: <BR><BR>
<INPUT TYPE="text" NAME="inputbox" VALUE=""><BR><BR>
<INPUT TYPE="button" NAME="button" Value="Change Title" onClick="changeTitle(this.form)">
</FORM>
<div id="content_div"></div>
  ]]>
  </Content>
</Module>

标签

您可以使用标签库向小工具添加标签式用户界面。要使用标签，小工具规范至少必须包括以下内容：

• <ModulePrefs> 下的 <Require feature="tabs"/> 标签，用于通知小工具加载 tabs 库。
• 用于构造标签并用内容填充标签的 JavaScript。有关详情，请参阅工作原理。

它通常还包括 setprefs 库以便小工具可以永久存储用户上次选定的标签。如果用户离开此页面随后返回，则小工具将加载已记忆的标签。要利用此功能，请在您的小工具规范中嵌入以下两行代码：

<Require feature="setprefs"/>
...
<UserPref name="selectedTab" datatype="hidden"/>

标签对象分析

标签库提供在以下对象上运行的函数和 CSS。

• TabSet 对象。此标签对象是所有标签的父容器。从程序上来说，此标签对象是各个标签对象的数组。基本 HTML 实施方案通常是作为“标题容器”在 API 中引用的 <table> 元素。您可以通过 gadgets.TabSet.getHeaderContainer() 函数访问该 HTML。
• 标签对象。标签对象是一组索引的标签内的单个标签。基本 HTML 实施方案通常是作为“名称容器”在 API 中引用的 <td> 元素。您可以通过 gadgets.Tab.getNameContainer() 函数访问该 HTML。
• 内容容器。内容容器可以保存各个标签对象的内容。基本 HTML 实施方案通常是作为“内容容器”在 API 中引用的 <div> 元素。您可以通过 gadgets.Tab.getContentContainer() 函数访问该 HTML。

工作原理

您可以使用 gadgets.TabSet() 构造器创建标签对象（即包含一组索引的标签的对象）。例如：

// Initialize tabs, designate the tab named "Two" as 
// the tab selected by default. 
var tabs = new gadgets.TabSet(__MODULE_ID__, "Two"); 

拥有标签对象后，可以使用 addTab() 函数将各个标签添加到标签对象。单个标签有三个主要组件：索引、名称和匹配相应 <div> ID 的唯一 ID。<div> 是放置标签的内容的位置。如果您没有自行提供 <div> 容器，标签库将为您生成一个。

addTab() 方法使用以下参数：

• String tabName - 要创建的标签的标号。
• Object opt_params - 可选参数对象。其可以包括以下内容：
  • contentContainer - 要用作标签内容容器的现有 HTML 元素。如果省略该参数，则标签库将创建一个参数。
  • callback - 选择标签时要执行的 mA 回调函数。
  • tooltip - 当用户将鼠标光标移动到标签上时将弹出的工具提示说明。
  • index - 要插入标签的索引。如果省略该参数，则在末尾附加新标签。

addTab()返回包含标签容器的 DOM ID 的字符串。

您可以将标签添加到标签对象，并通过以下任意方式用内容填充：

技巧 #1：当您创建标签的 ID 时记录此 ID，并使用此 ID 将内容添加到标签的对应 <div>：

var one_Id = tabs.addTab("One"); 
document.getElementById(one_Id).innerHTML = "Content for tab One.";

该方法的另一种方式是在 HTML 中定义标签的名称。例如：

var one_Id = tabs.addTab('<div style="color: red; font-weight: bold; background-color:#ccf;">Cool Tab</div>');
document.getElementById(one_Id).innerHTML = "Content for tab One.";

技巧 #2：创建标签并将对应的 <div> 添加到小工具的 HTML 部分；在 <div> 中放置静态内容：

tabs.addTab("Two", "two_id");
...
</script>     
<div id="two_id" style="display:none">Content for tab Two.</div>

技巧 #3：创建标签并将对应的 <div> 添加到小工具的 HTML 部分；在 <div> 中放置静态内容。使用回调函数将动态内容添加到静态内容：

tabs.addTab("Three", "three_id", callback); 
...
function callback(tabId) {
  var p = document.createElement("p");
  p.innerHTML = "This is dynamic content generated in callback.";
  document.getElementById(tabId).appendChild(p);
}
...
</script>
<div id="three_id" style="display:none">This is static content for tab Three.</div>

技巧 #4：使用 addTab(tabName, opt_params) 函数按名称添加标签。例如：

tabs.addTab("Tab", { 
     contentContainer: document.getElementById("domId"), 
     callback: func, 
     tooltip: "Popup description" 

}); 

以下简单小工具显示了添加标签并用内容填充的不同方法：

<?xml version="1.0" encoding="UTF-8" ?> 
<Module>
  <ModulePrefs title="Tabs Demo" height="140" scrolling="true" > 
    <Require feature="tabs" /> 
  </ModulePrefs>
  <Content type="html">
  <![CDATA[ 

    <script type="text/javascript">
    // Initialize tabs, designate the tab named "Two" as
    // the tab selected by default.
    var tabs = new gadgets.TabSet(__MODULE_ID__, "Two");
    function init() {
        // Technique #1: Capture the tab's ID when you create it, and use the ID 
        // to add content to the tab's corresponding <div>.        
        var one_Id = tabs.addTab('<div style="color: red; font-weight: bold; background-color:#ccf;">Cool Tab</div>');       
        document.getElementById(one_Id).innerHTML = "Content for tab One.";

        // Technique #2: Create the tab and define a corresponding <div> in the
        // HTML portion of the gadget. Add static content to the <div>.      

        tabs.addTab("Two", {
           contentContainer: document.getElementById("two_id")
        });

        // Technique #3: Create the tab and define a corresponding <div> in the
        // HTML portion of the gadget. Add static content to the <div>.
        // Use a callback function to add dynamic content to the static content.

        tabs.addTab("Three", {
           contentContainer: document.getElementById("three_id"),
           callback: callback
        });

        // Technique #4: Create the tab with a tooltip message. If specified <div>
        // doesn't exist, tabs library creates one.   
        // Invoke callback function.        
        tabs.addTab("Four", {            
           contentContainer: document.getElementById("four_id"),
           callback: callback,            
           tooltip: "I'm special"          
        });
    }

    // Callback that provides content to tabs Three and Four
    function callback(tabId) {
      var p = document.createElement("p");
      // Get selected tab
      var selectedTab = tabs.getSelectedTab();
      p.innerHTML = "This is dynamic content generated in callback for tab " + selectedTab.getName();
      document.getElementById(tabId).appendChild(p);
    }

    // Call init function to initialize and display tabs.
    gadgets.util.registerOnLoadHandler(init);
    </script>

   <div id="two_id" style="display:none">Content for tab Two.</div>
   <div id="three_id" style="display:none">This is static content for tab Three.</div>
  ]]>
  </Content>
</Module>

按索引处理标签

标签 API 还包括使您可以按索引控制标签的函数。标签索引从 0 到 n，其中 0 是第一个标签。例如，如果您有 3 个标签，则它们的标记为 0、1 和 2。您可以使用这些标记通过编程方式选择标签，以及切换两个标签的位置。

请注意，虽然标签的 ID 保持不变，但其索引会发生改变。例如，如果您将第三个标签移到第一个位置，则其索引从 2 变为 0。

以下是通过编程选择标签的示例。该代码段将创建一个链接。当用户单击此链接时，会选定第二个标签，就像用户单击此标签本身一样。

<script>
...
function selectTab() {
    tabs.setSelectedTab(1);
}
</script>

<a href="javascript:void(0)" onclick="selectTab()">Select Second Tab</a>

此处是通过编程移动标签的示例。该代码段将创建一个链接。当用户单击此链接时，小工具将切换第一个和第二个标签的位置。

<script>
...
function switchTabs() {
    tabs.swapTabs(0, 1);
}

</script>
<a href="javascript:void(0)" onclick="switchTabs()">Switch Tabs</a>

自定义标签显示

本部分介绍了如何使用 CSS 或 JavaScript 自定义标签的外观。

使用 CSS 自定义标签

标签 CSS 定义了应用到 HTML 元素（列出标签）的类。

您可以使用以下 CSS 类来覆盖默认设置，并修改您的标签的外观。

CSS 类	说明
.tablib_table	应用到包含标签的 HTML 表。
.tablib_selected	应用到选定的标签。
.tablib_unselected	应用到未选定的标签。
.tablib_spacerTab	应用到每个标签之间的分隔符元素。
.tablib_emptyTab	控制标签开始和结束的分隔符。
.tablib_navContainer	应用到父容器，其包含所有标签相关的内容（即标签标题和各个内容容器）。

下面是您可以覆盖的默认 CSS 类和设置：

.tablib_table {
  width: 100%;
  border-collapse: separate;
  border-spacing: 0px;
  empty-cells: show;
  font-size: 11px;
  text-align: center;
}
.tablib_emptyTab {
  border-bottom: 1px solid #676767;
  padding: 0px 1px;
}
.tablib_spacerTab {
  border-bottom: 1px solid #676767;
  padding: 0px 1px;
  width: 1px;
}
.tablib_selected {
  padding: 2px 0px;
  background-color: #ffffff;
  border: 1px solid #676767;
  border-bottom-width: 0px;
  color: #3366cc;
  font-weight: bold;
  width: 80px;
  cursor: default;
}
.tablib_unselected {
  padding: 2px 0px;
  background-color: #dddddd;
  border: 1px solid #aaaaaa;
  border-bottom-color: #676767;
  color: #000000;
  width: 80px;
  cursor: pointer;
}
.tablib_navContainer {
  width: 10px;
  vertical-align: middle;
}
.tablib_navContainer a:link, .tablib_navContainer a:visited, .tablib_navContainer a:hover {
  color: #3366aa;
  text-decoration: none;
}

例如：

<![CDATA[ 
  <style type="text/css"> 
   .tablib_selected { color: #FF0000; }
   .tablib_unselected { color: #660099; }
   .tablib_table { font-size:20px; }
   .tablib_emptyTab { padding:2px 5px; }
   .tablib_spacerTab { padding:0px 5px; }
  </style>
<script...> 

也可以使用 JavaScript 将 CSS 样式应用到标签标题容器。函数 getHeaderContainer() 返回标签 HTML 表，然后您可以根据需要对其进行修改。

例如，以下代码段更改字体大小并在顶部添加了一些空白：

var tabs = new gadgets.TabSet();
...

var table = tabs.getHeaderContainer();
table.style.fontSize = "10px";
table.style.marginTop = "15px";

您可以通过获取各个标签元素并修改其属性，来自定义各个标签标题的样式。以下是使第一个标签样式唯一的示例：

var tabs = new gadgets.TabSet();
tabs.addTab("Unique");
...
var firstTab = tabs.getTabs()[0].getNameContainer();
firstTab.style.backgroundColor = "#999999";
firstTab.style.color = "#ffffff";

更改标签对齐方式

默认情况下，标签被添加时居中对齐。但是，如果您有至少 3 或 4 个标签，您可能希望将它们向左或向右对齐。您可以通过使用 alignTabs() 函数来实现这一目标。它使用值为 left、right 或 center 的参数。如果您将标签向左或向右对齐，则您可以传递一个附加可选参数以显示距左边或右边的偏移。默认大小为 3px。

例如：

var tabs = new gadgets.TabSet();
...
// Align tabs to the left and offset it by 10 pixels
tabs.alignTabs("left", 10);

隐藏标签

您可以使用 displayTabs() 函数切换标签及其内容的显示。该函数使用 true 或 false 的布尔值。

以下是创建显示或隐藏标签的按钮的示例：

<input onclick="toggleTabs()" type="button" value="Show/Hide"/>
<script>
var tabs = new gadgets.TabSet();
...
var showTabs = true;
function toggleTabs() {
  showTabs = !showTabs;
  tabs.displayTabs(showTabs);
}
</script>

小消息

小消息是一种在小工具中向用户显示的临时消息。小消息专用于拒绝操作（通过编程方式或通过用户）。小消息的基本类型如下所示：

• 用户可以通过单击 [x] 删除的可拒绝消息。
• 在特定秒数过去后消失的计时器消息。
• 必须通过编程方式拒绝的静态消息。

要使用小消息，小工具规范必须包括下以下内容：

• <ModulePrefs> 下的 <Require feature="minimessage"/> 标签，用于通知小工具加载小消息库。
• 描述您的小消息行为的 JavaScript 函数。有关小消息库中函数的完整列表，请参阅参考。

您可能想要使用小消息的部分原因如下所示：

• 宣传：可以使用小消息在您的小工具中显示宣传消息。
• 状态：许多小工具可以在后台获取和加载数据。您可以使用小消息显示“正在加载...”或其他状态相关的消息。
• 调试/错误：如果小工具发生错误，其可以使用小消息来通知用户，而非静默失败。
• 其他：根据小工具的类型（例如日历、eBay），您可能想要向用户显示通知。由于小消息较小且可拒绝，您可以使用它们交流特殊信息。

工作原理

将小消息添加到小工具的基本步骤很简单：

1. 导入小消息库：

<Require feature="minimessage"/>

2. 使用 gadgets.MiniMessage() 构造器示例化新的小消息对象：

var msg = new gadgets.MiniMessage(__MODULE_ID__);

在大多数情况下，您希望使该对象成为可在所有范围访问的单个全局对象。

3. 创建带有某些文本的新的小消息：

msg.createDismissibleMessage("Please close me when you're done reading me.");

这将在您的小工具顶部添加一个可拒绝的、已预先设置格式的消息以及关联的 [x]。当用户单击 [x] 时，消息将关闭。

已完成！您已创建了多种可拒绝消息中的一种。

在不同位置创建消息

默认情况下，消息置于容器 HTML 元素中，位于小工具的最顶部。每个连续的消息以自上而下的顺序作为子消息附加到容器。但是，您可以为所有消息或单个消息修改此行为。

为所有消息设置位置

您可以通过将 HTML 元素（最好是 <div>）传递到构造器，来覆盖消息容器元素的默认位置。该元素在消息插入和显示的位置成为消息容器。

例如，在该代码段中，<h3> 消息“我现在位于顶部！”显示在小工具顶部。小消息以消息的添加顺序显示在其下面的 messageBox <div> 中。

<div>
  <h3>I'm on top now!</h3>
</div>


<div id="messageBox"></div>

<script type="text/javascript"> 
  // In the constructor, state that messages should be be displayed
  // in the messageBox <div> rather than at the top of the gadget.
  var msg = new gadgets.MiniMessage(__MODULE_ID__, document.getElementById("messageBox"));
  msg.createDismissibleMessage("I'm the first message.");
  msg.createDismissibleMessage("I'm the second message.");
  msg.createDismissibleMessage("I'm at the bottom.");

</script>

为单个消息设置位置

您可以在指定位置创建可拒绝消息，而不是在消息容器中附加消息。可以通过在小工具的 HTML 部分中标记此消息，然后将元素（最好是 <div>）作为第一个参数传递到 createDismissibleMessage() 来执行此操作。

例如，在该代码段中，消息显示在 status <div> 中：

<div id="status" style="color:#B30000;">
  <b>Check out our new API documentation!</b> --
  <a href="http://www.google.com/apis/gadgets" target="_blank">Read</a>
</div>


<script type="text/javascript">
  var msg = new gadgets.MiniMessage(__MODULE_ID__);
  // Pass the HTML element to createDismissableMessage() to indicate
  // where the message should be displayed.
  msg.createDismissibleMessage(document.getElementById("status"));
</script>

使用 DOM 方法创建消息

有时，您可能想使用 HTML DOM 方法生成可拒绝消息。由于消息不存在于 DOM 中，其默认情况下将附加在消息容器中。

例如：

<script type="text/javascript"> 
  var msg = new gadgets.MiniMessage(__MODULE_ID__);
  // Generate the message using DOM methods
  var div = document.createElement("div");
  div.innerHTML = "New message created by W3C DOM methods.";
  // Set some DOM properties
  div.onmouseover = function() {
    div.style.backgroundColor = "green";
  };
  div.onmouseout = function() {
    div.style.backgroundColor = "";
  };
  msg.createDismissibleMessage(div);

</script>

创建计时器消息

计时器消息是一种预先设置了格式的消息，在特定秒数过去后消失。函数 createTimerMessage() 采用两个参数：消息字符串，以及指示消息应显示多少秒的数字。例如：

var msg = new gadgets.MiniMessage(__MODULE_ID__);
msg.createTimerMessage("I'm going to disappear in 5 seconds.", 5);

创建静态消息

静态消息一种预先设置了格式的消息，在通过编程拒绝（通过 dismissMessage() 函数）之前一直显示。这对于在小工具执行后台工作时（例如获取内容）显示通知消息以通知用户非常有用。例如：

  var msg = new gadgets.MiniMessage(__MODULE_ID__);
  var loadMessage = msg.createStaticMessage(document.getElementById("loading"));

自定义小消息显示

有两种更改小消息默认外观的方式：

• 更改单个消息的外观。
• 全局更改所有消息的外观。

更改单个消息的样式

可以使用 DOM 函数更改消息的样式。当您创建新的可拒绝消息时，将返回 HTML 元素。您可以通过设置返回的 HTML 元素的样式属性，来修改消息的外观。例如：

<script type="text/javascript">
  var msg = new gadgets.MiniMessage(__MODULE_ID__);
  var statusMsg = msg.createDismissibleMessage("This is a critical error!");
  // Change the message's background color to red
  statusMsg.style.backgroundColor = "red";
  statusMsg.style.color = "white";
</script>

注意：本示例显示了更改消息整体背景颜色的正确方式。设置包含不更改整体背景颜色的消息的 <div> 的背景颜色。

更改所有消息的样式

可以使用 CSS 全局更改所有消息的样式。CSS 定义应用到 HTML 元素（定义小消息）的类。

您可以使用以下 CSS 类来覆盖默认设置，并修改消息的外观。

CSS 类	说明
.mmlib_table	应用到包含消息的 HTML 表。
.mmlib_xlink	应用到用于拒绝消息的 [x] 链接。设置仅应用到可拒绝消息。

例如，这会将背景更改为深蓝色，将前景更改为白色：

<![CDATA[
   <style>
     .mmlib_table__MODULE_ID__ {
       background-color: #000066;
       color: #ffffff;
     }
   </style>
<script...>

下面是您可以覆盖的默认 CSS 类和设置：

.mmlib_table {
  width: 100%;
  font: bold 9px arial,sans-serif;
  background-color: #fff4c2;
  border-collapse: separate;
  border-spacing: 0px;
  padding: 1px 0px;
  }
.mmlib_xlink {
  font: normal 1.1em arial,sans-serif;
  font-weight: bold;
  color: #0000cc;
  cursor: pointer;
  }

Flash

您可以使用 flash 库将 Flash 影片（确切的说，.swf 文件）嵌入到小工具中。要嵌入 Flash 内容，小工具规范至少必须包括下以下内容：

• <ModulePrefs> 下的 <Require feature="flash"/> 标签，用于通知小工具加载 flash 库。
• 调用 gadgets.flash.embedFlash() 来将 .swf 文件嵌入您的小工具中，并在指定位置显示该文件。请注意，要使用该功能，所有资源必须绑定在 .swf 文件中。

flash 库包括以下函数：

函数	说明
gadgets.flash.embedFlash(swf_url, swf_container, swfVersion, opt_params)	嵌入 swf_url 指定的 .swf 文件，并在小工具中 swf_container 指定的位置显示该文件。参数 opt_params 是一个可选对象，可以包含任意有效 HTML 参数。 R如果成功，则返回 true，如果失败，则返回 false。 注意：如果您遇到性能问题，或插入符号不显示（在 Firefox 2.0 中有时会遇到此问题），请尝试将 wmode 明确地设置为 "window"，如下所示：gadgets.flash.embedFlash("example.swf", "wrapper", {wmode: "window"});
gadgets.flash.embedCachedFlash(swf_url, swf_container, swfVersion, opt_params)	在 DOM 树中嵌入缓存的 Flash 文件。参数和返回值与 embedFlash() 方法相同。
gadgets.flash.getMajorVersion()	返回 Flash Player 的主要版本，如果未检测到 Flash Player 将返回零。

Flash 示例

当您在此示例小工具中单击按钮时，其将显示相应的 .swf 文件。当您单击“停止”时，小工具将显示静态照片。

以下是该示例的小工具规范：

<?xml version="1.0" encoding="UTF-8" ?> 
<Module> 
<ModulePrefs title="Trevor Does Tricks" height="300">
  <Require feature="flash" />
</ModulePrefs>
<Content type="html">
<![CDATA[

<style type="text/css">
  input.mybutton
  {
     background-color:#FFCC99;
     border-style:solid;
     border-color:#000000;
     font-family:Comic Sans MS,sans-serif;
     font-size:14px;
  }
</style>

<div id="flashcontainer" style="text-align: center;"></div> 

<script type="text/javascript">

  // Display still photo.
  function showPhoto() {
    document.getElementById("flashcontainer").innerHTML = "<img src='http://doc.examples.googlepages.com/Trevor.JPG' />";
  }

  // Play .swf file for specified trick.
  function doTrick(trick) {

    // The URL for the .swf file that shows the specified trick.
    var url = "http://doc.examples.googlepages.com/Trevor-"+trick+".swf";

    // Play .swf file.
      gadgets.flash.embedFlash(url, "flashcontainer", {
      swf_version: 6,
      id: "flashid",
      width: 300,
      height: 250
    })
  }

  // When gadget first loads, display still photo.
  gadgets.util.registerOnLoadHandler(showPhoto);
  </script>
  <br />
  <div style="text-align: center;"> 
    <input type=submit class="mybutton" value="Spin" onClick="doTrick('spin')">
    <input type=submit class="mybutton" value="Speak" onClick="doTrick('speak')">
    <input type=submit class="mybutton" value="Sit" onClick="doTrick('sit')">
    <input type=submit class="mybutton" value="Down" onClick="doTrick('down')">
    <input type=submit class="mybutton" value="Stop" onClick="showPhoto()">
  </div>
  ]]>
</Content>
</Module>

返回页首