小工具 API 参考

本文档描述了 gadgets.* 名称空间中的类和方法，其中一些类和方法是功能特有的。如需详细信息（包括功能方面的信息），请参阅小工具规范。

注意：尽管 iGoogle Sandbox 中有 API，但 iGoogle 的生产实例尚不支持它。如果您想为 iGoogle 编写小工具，请参阅小工具 API 参考。

目录

• 类型规范
• 核心 API
  • Prefs
  • io
    • AuthorizationType
    • ContentType
    • MethodType
    • ProxyUrlRequestParameters
    • RequestParameters
  • json
  • util
• 功能所特有的 API
  • MiniMessage
  • Tab
  • TabSet
  • flash
  • pubsub
  • rpc
  • skins
    • Property
  • views
    • View
    • ViewType
  • window

返回页首

类型规范

本文档使用以下类型的规范：

Array<T> 或 Array。<T>

数组只能填入 T 类型的对象。该规范类似于 Java 类。

Map<K, V> 或 Map。<K, V>

K 类型键映射到 V 类型值的 JavaScript 对象。该规范也类似于 Java 类。它通常用于 opt_params 变量。

静态

标有静态类的类型没有公共或私有构造函数。换句话说，该类型是个名称空间，而不是可进行实例化以创建对象的类。此类型中的字段和函数也都标有静态。

布尔

布尔值（不是 Boolean 对象）。

字符串

字符串值（不是 String 对象）。

返回页首

gadgets.MiniMessage 类

 概述     详述

MiniMessage 类，用于创建小工具内要显示给用户的消息。典型的用例：

• 状态消息 - 正在载入、正在保存等
• 推广信息 - 新功能、新小工具等
• 调试/错误消息 - 输入错误、无法连接到服务器等

 

构造函数概述

gadgets.MiniMessage(opt_moduleId, opt_container)

创建 MiniMessage。

 

方法概述

 HTMLElement createDismissibleMessage(message, opt_callback)

创建一个可关闭的消息，它有一个 [x] 图标以便用户关闭消息。

 HTMLElement createStaticMessage(message)

创建一个静态消息，它只能通过编程方式（通过调用 dismissMessage()）关闭。

 HTMLElement createTimerMessage(message, seconds, opt_callback)

创建只显示指定秒数的消息。

dismissMessage(message)

关闭指定的消息。

 

构造函数详述

gadgets.MiniMessage

gadgets.MiniMessage(opt_moduleId, opt_container)

创建 MiniMessage。

参数：
String opt_moduleId - 可选模块 ID
HTMLElement opt_container - 可选 HTML 容器元素，小消息将在里面显示

方法详述

createDismissibleMessage

HTMLElement createDismissibleMessage(message, opt_callback)

创建一个可关闭的消息，它有一个 [x] 图标以便用户关闭消息。消息被关闭后，系统就会从 DOM 中删除该消息，并且会调用可选回调函数（如有定义的话）。

参数：
String, Object message - 消息，可以是 HTML 字符串或 DOM 元素
Function opt_callback - 关闭消息后所要调用的可选回调函数

返回：
HTMLElement 已创建的消息的 HTML 元素

createStaticMessage

HTMLElement createStaticMessage(message)

创建一个静态消息，它只能通过编程方式（通过调用 dismissMessage()）关闭。

参数：
String, Object message - 消息，可以是 HTML 字符串或 DOM 元素

返回：
HTMLElement 已创建的消息的 HTML 元素

createTimerMessage

HTMLElement createTimerMessage(message, seconds, opt_callback)

创建只显示指定秒数的消息。计时器超时后，系统就会关闭消息并执行可选回调函数。

参数：
String, Object message - 消息，可以是 HTML 字符串或 DOM 元素
number seconds - 关闭消息前的等待秒数
Function opt_callback - 关闭消息后所要调用的可选回调函数

返回：
HTMLElement 已创建的消息的 HTML 元素

dismissMessage

dismissMessage(message)

关闭指定的消息。

参数：
HTMLElement message - 要删除的消息的 HTML 元素

返回页首

gadgets.Prefs 类

 概述     详述

用于获取用户首选项、模块维度和消息。客户端调用 gadgets.Prefs 的构造函数，并传入其模块 ID 作为参数，获得 gadgets.Prefs 实例。然后通过这个实例来获取其用户首选项。示例：

var prefs = new gadgets.Prefs();
var name = prefs.getString("name");
var lang = prefs.getLang();

 

构造函数概述

gadgets.Prefs(opt_moduleId)

创建新首选项对象。

 

方法概述

 Array.<String> getArray(key)

返回数组类型用户首选项的值

 Boolean getBool(key)

返回布尔类型用户首选项的值。

 String getCountry()

获取当前的国家/地区（返回为 ISO 3166-1 alpha-2 代码）。

 Number getFloat(key)

返回浮点类型用户首选项的值。

 Number getInt(key)

返回整数类型用户首选项的值。

 String getLang()

返回小工具在呈现时应使用的语言（返回为 ISO 639-1 语言代码）。

 String, Number getModuleId()

获取当前实例的模块 ID。

 String getMsg(key)

获取未格式化的消息。

 String getString(key)

返回字符串类型用户首选项的值。

set(key, val)

存储首选项。

setArray(key, val)

存储数组首选项。

 

构造函数详述

gadgets.Prefs

gadgets.Prefs(opt_moduleId)

创建新首选项对象。

参数：
String, Number opt_moduleId - 可选参数，用于指定要为其创建首选项的模块 ID；如果未提供该参数，则使用默认的模块 ID

方法详述

getArray

Array.<String> getArray(key)

返回数组类型用户首选项的值未以列表形式声明的 UserPref 值将作为单元素数组进行处理。

参数：
String key - 要获取的首选项

返回：
Array.<String>  首选项；如果未设置，则为空数组

getBool

Boolean getBool(key)

返回布尔类型用户首选项的值。

参数：
String key - 要获取的首选项

返回：
Boolean  首选项；如果未设置，则为 False

getCountry

String getCountry()

获取当前的国家/地区（返回为 ISO 3166-1 alpha-2 代码）。

返回：
String  该模块实例的国家/地区

getFloat

Number getFloat(key)

返回浮点类型用户首选项的值。

参数：
String key - 要获取的首选项

返回：
Number  首选项；如果未设置，则为 0

getInt

Number getInt(key)

返回整数类型用户首选项的值。

参数：
String key - 要获取的首选项

返回：
Number  首选项；如果未设置，则为 0

getLang

String getLang()

返回小工具在呈现时应使用的语言（返回为 ISO 639-1 语言代码）。

返回：
String  该模块实例的语言

getModuleId

String, Number getModuleId()

获取当前实例的模块 ID。

返回：
String, Number  该模块实例的模块 ID

getMsg

String getMsg(key)

获取未格式化的消息。

参数：
String key - 要获取的消息

返回：
String  消息

getString

String getString(key)

返回字符串类型用户首选项的值。

参数：
String key - 要获取的首选项

返回：
String  首选项；如果未设置，则为空字符串

set

set(key, val)

存储首选项。要使用该调用，小工具必须使用特定功能 setprefs。

注意：如果小工具需要存储数组，则它应使用 setArray，而不是本调用。

参数：
String key - 要存储的首选项
Object val - 要存储的值

setArray

setArray(key, val)

存储数组首选项。要使用该调用，小工具必须使用特定功能 setprefs。

参数：
String key - 要存储的首选项
Array val - 要存储的值

返回页首

类 gadgets.Tab

概述     详述

小工具的 Tab 类。您可以使用 TabSet addTab() 方法创建标签。要获取 Tab 对象，请使用 TabSet getSelectedTab() 或 getTabs() 方法。

另请参阅：TabSet

 

方法概述

 Function getCallback()

返回在选择标签时执行的回调函数。

 HTMLElement getContentContainer()

返回呈现标签内容的 HTML 元素。

 Number getIndex()

返回标签的索引。

 String getName()

以字符串形式返回标签的标号（可能包含 HTML）。

 HTMLElement getNameContainer()

返回包含标签的标号的 HTML 元素。

 

方法详述

getCallback

Function getCallback()

返回在选择标签时执行的回调函数。

返回：
Function  标签的回调函数

getContentContainer

HTMLElement getContentContainer()

返回呈现标签内容的 HTML 元素。

返回：
HTMLElement  内容容器的 HTML 元素

getIndex

Number getIndex()

返回标签的索引。

返回：
Number  标签的索引

getName

String getName()

以字符串形式返回标签的标号（可能包含 HTML）。

返回：
String  标签的标号

getNameContainer

HTMLElement getNameContainer()

返回包含标签的标号的 HTML 元素。

返回：
HTMLElement  标签的标号的 HTML 元素

返回页首

类 gadgets.TabSet

概述     详述

帮助小工具创建标签的类。

构造函数概述

gadgets.TabSet(opt_moduleId, opt_defaultTab, opt_container)

创建新标签集对象

 

方法概述

 String addTab(tabName, opt_params)

根据 opt_params 中指定的名值对添加新标签。

alignTabs(align, opt_offset)

设置标签对齐方式。

displayTabs(display)

显示或隐藏标签以及所有相关内容。

 HTMLElement getHeaderContainer()

返回标签标题容器元素。

 gadgets.Tab getSelectedTab()

返回当前选定的标签对象。

 Array.<gadgets.Tab> getTabs()

返回所有现有标签对象的数组。

removeTab(tabIndex)

删除标签索引中某个标签及其所有相关内容。

setSelectedTab(tabIndex)

选中索引值为 tabIndex 的标签，如果标签存在回调函数，则触发该函数。

swapTabs(tabIndex1, tabIndex2)

将索引值为 tabIndex1 和 tabIndex2 的标签交换位置。

 

构造函数详述

gadgets.TabSet

gadgets.TabSet(opt_moduleId, opt_defaultTab, opt_container)

创建新标签集对象

参数：
String opt_moduleId - 可选的标签容器 ID 后缀
String opt_defaultTab - 可选的标签名称，用于指定在初始化之后选择的标签的名称；如果省略该参数，则默认选择第一个标签
HTMLElement opt_container - 用于包含标签的 HTML 元素；如果省略该参数，则会创建新的 div 元素并将其插入到最顶部

方法详述

addTab

String addTab(tabName, opt_params)

根据 opt_params 中指定的名值对添加新标签。opt_params 中支持以下属性：

contentContainer

要用作标签内容容器的现有 HTML 元素。如果省略该参数，则标签库会创建一个参数。

callback

选择标签时要执行的回调函数。

tooltip

当用户将鼠标光标移动到标签上时弹出的工具提示说明。

index

要插入标签的索引。如果删除该参数，则新标签会附加到末尾。

参数：
String tabName - 要创建的标签的标号
Object opt_params - 可选参数对象

返回：
String  标签容器的 DOM ID

alignTabs

alignTabs(align, opt_offset)

设置标签对齐方式。默认情况下，标签居中对齐。

参数：
String align - 'left'、 'center' 或 'right'
Number opt_offset - 可选参数，用于设置标签偏离左边界或右边界的像素数；默认值为 3 像素

displayTabs

displayTabs(display)

显示或隐藏标签以及所有相关内容。

参数：
Boolean display - 为 True 则显示标签；为 False 则隐藏标签

getHeaderContainer

HTMLElement getHeaderContainer()

返回标签标题容器元素。

返回：
HTMLElement  标签标题容器元素

getSelectedTab

gadgets.Tab getSelectedTab()

返回当前选定的标签对象。

返回：
gadgets.Tab  当前选定的标签对象

getTabs

Array.<gadgets.Tab> getTabs()

返回所有现有标签对象的数组。

返回：
Array.<gadgets.Tab>  所有现有标签对象的数组

removeTab

removeTab(tabIndex)

删除标签索引中的某个标签及其所有相关内容。

参数：
Number tabIndex - 要删除的标签的索引

setSelectedTab

setSelectedTab(tabIndex)

选中索引值为 tabIndex 的标签，如果标签存在回调函数，则触发该函数。如果已选择了该标签，则不触发回调。

参数：
Number tabIndex - 要选择的标签的索引

swapTabs

swapTabs(tabIndex1, tabIndex2)

将索引值为 tabIndex1 和 tabIndex2 的标签交换位置。选定的标签不会变化，也不会调用回调函数。

参数：
Number tabIndex1 - 要交换的第一个标签的索引
Number tabIndex2 - 要交换的第二个标签的索引

返回页首

静态类 gadgets.flash

概述     详述

在小工具中嵌入 Flash 内容。

方法概述

<static>  Boolean embedCachedFlash()

在 DOM 树中嵌入缓存的 Flash 文件。

<static>  Boolean embedFlash(swfUrl, swfContainer, swfVersion, opt_params)

在 DOM 树内嵌入 Flash 文件。

<static>  Number getMajorVersion()

检测 Flash Player 及其主版本号。

 

方法详述

embedCachedFlash

<static> Boolean embedCachedFlash()

在 DOM 树中嵌入缓存的 Flash 文件。接受 gadgets.flash.embedFlash 所接受的参数。

返回：
Boolean  函数调用是否顺利完成

embedFlash

<static> Boolean embedFlash(swfUrl, swfContainer, swfVersion, opt_params)

在 DOM 树内嵌入 Flash 文件。

参数：
String swfUrl - SWF 网址
String, Object swfContainer - 现有 HTML 容器元素的 ID 或引用
Number swfVersion - 所需的 Flash Player 最低版本
Object opt_params - 可选对象，可包含任何有效的 HTML 参数；创建时所有属性都将传递给 Flash 影片

返回：
Boolean  函数调用是否顺利完成

getMajorVersion

<static> Number getMajorVersion()

检测 Flash Player 及其主版本号。

返回：
Number  如果不支持 Flash，则返回 Flash Player 的主要版本或 0

返回页首

静态类 gadgets.io

概述     详述

提供远程内容检索功能。

方法概述

<static>  String encodeValues(fields)

将输入对象转换为网址编码的数据字符串。

<static>  String getProxyUrl(url, opt_params)

获取传送网址的代理程序版本。

<static> makeRequest(url, callback, opt_params)

从提供的网址中获取内容并且将该内容馈送到回调函数中。

 

方法详述

encodeValues

<static> String encodeValues(fields)

将输入对象转换为网址编码的数据字符串。(key=value&...)

参数：
Object fields - 希望编码的 post 字段

返回：
String 经处理的 post 数据；该数据在末尾包含一个 & 符号

getProxyUrl

<static> String getProxyUrl(url, opt_params)

获取传送网址的代理程序版本。

参数：
String url - 用于获取代理程序网址的网址
Map<String, String> opt_params - 要传递给请求的其他可选参数

返回：
String  网址的代理程序版本

makeRequest

<static> makeRequest(url, callback, opt_params)

从提供的网址中获取内容并且将该内容馈送到回调函数中。示例：

var params = {};
params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.TEXT;
gadgets.io.makeRequest(url, callback, params);

签名的验证

如果 opt_params[gadgets.io.RequestParameters.AUTHORIZATION] 设置为 gadgets.io.AuthorizationType.SIGNED，则容器需要向目标服务器保证用户的身份。容器可以通过以下操作实现此目的：

1. 删除所有名称以 oauth、xoauth 或 opensocial（不区分大小写）开头的请求参数。

2. 向请求查询字符串添加以下参数：

   opensocial_viewer_id

   可选。
   当前查看者的 ID，它与查看者个人对象的 getId() 值匹配。

   opensocial_owner_id

   必需。
   当前所有者的 ID，它与所有者个人对象的 getId() 值匹配。

   opensocial_app_url

   必需。
   提出请求的应用程序的网址。当应用程序更改了网址时，容器可能对多个应用程序网址使用一个规范的应用程序网址别名。

   opensocial_instance_id

   可选。
   不透明的标识符，用于区分一个容器内同一个应用程序的多个实例。如果容器不允许同一个应用程序存在多个实例，该参数可以省略。opensocial_app_url 和 opensocial_instance_id 的组合可以唯一标识容器内一个应用程序的一个实例。

   opensocial_app_id

   可选。
   应用程序的不透明标识符（对特定容器来说是唯一的）。想要向后兼容 opensocial 0.7 规范的容器可能会包含本参数。

   xoauth_public_key

   可选。
   公共密钥的不透明标识符，用于在请求上签名。如果容器不使用公共密钥在请求上签名，或者容器根据请求的目标安排使用其他分发密钥的方法，则可以省略该参数。

3. 根据 OAuth 规范第 9 节在所得请求上签名。

gadgets.io.AuthorizationType.SIGNED 的密钥管理

如果容器使用公共密钥在请求上签名，则可以选择使用自签名证书，或使用由知名的证书签发机构签名的证书。如果容器不通过 HTTPS 分发其 OAuth 签名密钥，则应使用由知名的证书签发机构签名的证书。

证书的 commonName 属性应与容器服务器的主机名相匹配，还应与请求中指定的 oauth_consumer_key 参数的值相匹配。

容器应将其公共密钥放置在一个众所周知的位置以供下载。建议放置在 https://container-hostname/opensocial/certificates/xoauth_public_keyvalue 位置。

签名请求的接收者必须验证请求上的签名是否正确以及请求上的时间戳是否在合理的时间段内。建议时间段为当前时间的前后 5 分钟。

签名请求的接收者可以使用 oauth_consumer_key 和 xoauth_public_key 参数来自动检测容器部署新证书的时间。如果容器在一个众所周知的位置部署证书，则接收者可以自动下载新证书。自动下载新证书的接收者应该缓存所得的证书。

如果容器的证书不是从 https://container-hostname 下载的，则接收者应该在验证该证书是由知名的证书签发机构签名之后才能信任该证书。

OAuth 验证

如果 opt_params[gadgets.io.RequestParameters.AUTHORIZATION] 设置为 gadgets.io.AuthorizationType.OAUTH，则容器需要使用 OAuth 来获取访问请求中指定的资源的权限。这可能需要小工具通过指引用户从服务提供商处获取访问权限来获取用户的内容。

附加参数

以下附加参数可以通过 opt_params 指定：

gadgets.io.RequestParameters.OAUTH_SERVICE_NAME

小工具用来指代其 XML 规范中的 OAuth <服务> 元素的昵称。如果未指定，则默认为 ""。

gadgets.io.RequestParameters.OAUTH_TOKEN_NAME

小工具用来指代可授予对特殊资源的访问权限的 OAuth 令牌的昵称。如果未指定，则默认为 ""。如果小工具有权访问来自同一个服务提供商的多个资源，则可以使用多个令牌名称。例如，有权访问联系人列表和日历的小工具可以使用“联系人”令牌名称来使用联系人列表令牌，并可以使用“日历”令牌名称来使用日历令牌。

gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN

服务提供商或许能够自动为已预先获得对资源的访问权限的小工具提供请求令牌。此小工具可以将该令牌与 OAUTH_REQUEST_TOKEN 参数配合使用。该参数是可选的。

gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN_SECRET

与预先批准的请求令牌相对应的密钥。该参数是可选的。

如果使用 OAuth，则容器应代表小工具执行 OAuth 协议。如果小工具尚未注册用于该服务提供商的消费者密钥，则容器可以选择使用默认的 RSA 签名密钥（相当于知名的证书）在请求上签名。如果容器使用默认的消费者密钥，则还应加入 OAuth 参数 xoauth_app_url 来识别提出请求的小工具。

回调参数

除了由 makeRequest() 返回的正常值外，makeRequest() 回调参数还传递具有若干 OAuth 特有的域的 javascript 对象。

"oauthApprovalUrl"

如果指定了该值，则用户需要访问外部页面才能批准小工具访问数据的请求。建议使用弹出窗口引导用户转至外部页面。一旦用户批准访问，小工具便可重复进行 makeRequest 调用来检索数据。

"oauthError"

如果指定了该值，则表示发生了与 OAuth 相关的错误。该值将会是一组字符串常量中的一个，这些常量可用于以编程方式检测错误。这些常量没有针对 opensocial 0.8 定义，但是执行者应该试图商定一组有用的常量值来作为 opensocial 0.9 中的标准。

"oauthErrorText"

如果指定了该值，则表示发生了与 OAuth 相关的错误。该值为无格式文本，可用于为小工具开发人员提供调试信息。

参数：
String url - 存放内容的网址
Function callback - 提取网址后，与来自该网址的数据一起调用的函数
Map.<gadgets.io.RequestParameters, Object> opt_params - 附加的请求参数或代理请求参数

返回页首

静态类 gadgets.io.AuthorizationType

概述     详述

由 RequestParameters 使用。

Field 概述

<static> object NONE

无验证。

<static> object OAUTH

容器将使用 OAuth 进行验证。

<static> object SIGNED

请求将由容器签名。

 

Field 详述

NONE

<static> object NONE

无验证。

OAUTH

<static> object OAUTH

容器将使用 OAuth 进行验证。

SIGNED

<static> object SIGNED

请求将由容器签名。

返回页首

静态类 gadgets.io.ContentType

概述     详述

由 RequestParameters 使用。

Field 概述

<static> object DOM

返回 DOM 对象；用于获取 XML。

<static> object FEED

返回 RSS 或 Atom 供稿的 JSON 表示。

<static> object JSON

返回 JSON 对象。

<static> object TEXT

返回文本；用于获取 HTML。

 

Field 详述

DOM

<static> object DOM

返回 DOM 对象；用于获取 XML。

FEED

<static> object FEED

返回 RSS 或 Atom 供稿的 JSON 表示。

JSON

<static> object JSON

返回 JSON 对象。

TEXT

<static> object TEXT

返回文本；用于获取 HTML。

返回页首

静态类 gadgets.io.MethodType

概述     详述

定义 RequestParameters.METHOD 的值。

Field 概述

<static> object DELETE

容器对该方法类型的支持是可选的。

<static> object GET

默认类型。

<static> object HEAD

容器对该方法类型的支持是可选的。

<static> object POST

容器对该方法类型的支持是可选的。

<static> object PUT

容器对该方法类型的支持是可选的。

 

Field 详述

DELETE

<static> object DELETE

容器对该方法类型的支持是可选的。

GET

<static> object GET

默认类型。

HEAD

<static> object HEAD

容器对该方法类型的支持是可选的。

POST

<static> object POST

容器对该方法类型的支持是可选的。

PUT

<static> object PUT

容器对该方法类型的支持是可选的。

返回页首

静态类 gadgets.io.ProxyUrlRequestParameters

概述     详述

由 gadgets.io.getProxyUrl() 方法使用。

Field 概述

<static> object REFRESH_INTERVAL

尝试使用内容缓存。

 

Field 详述

REFRESH_INTERVAL

<static> object REFRESH_INTERVAL

尝试使用内容缓存。刷新间隔是我们希望缓存指定响应的秒数。默认情况下会考虑 HTTP 标头。如果没有任何 HTTP 标头，该值则默认为 3600（一个小时）。请注意，签名的请求和显示 POST_DATA 的对象通常不进行缓存。

返回页首

静态类 gadgets.io.RequestParameters

概述     详述

由 gadgets.io.makeRequest() 方法使用。

Field 概述

<static> object AUTHORIZATION

获取内容时使用的验证的类型；默认为 AuthorizationType.NONE。

<static> object CONTENT_TYPE

网址上现有内容的类型；默认为 ContentType.TEXT。

<static> object GET_SUMMARIES

内容为供稿时，是否获取该供稿的概述；默认为 False。

<static> object HEADERS

要发送到网址的 HTTP 标题；默认为 Null。

<static> object METHOD

从网址中获取内容时使用的方法；默认为 MethodType.GET。

<static> object NUM_ENTRIES

内容为供稿时要获取的条目数；默认为 3。

<static> object POST_DATA

要使用 POST 方法发送到网址的数据；默认为 Null。

 

Field 详述

AUTHORIZATION

<static> object AUTHORIZATION

获取内容时使用的验证的类型；默认为 AuthorizationType.NONE。指定为 AuthorizationType。

CONTENT_TYPE

<static> object CONTENT_TYPE

网址上现有内容的类型；默认为 ContentType.TEXT。指定为 ContentType。

GET_SUMMARIES

<static> object GET_SUMMARIES

内容为供稿时，是否获取该供稿的概述；默认为 False。指定为 Boolean。

HEADERS

<static> object HEADERS

要发送到网址的 HTTP 标题；默认为 Null。指定为 Map.<String,String>。

METHOD

<static> object METHOD

从网址获取内容时使用的方法；默认为 MethodType.GET。由 MethodType 指定的值是有效值。

NUM_ENTRIES

<static> object NUM_ENTRIES

内容为供稿时要获取的条目数；默认为 3。指定为 Number。

POST_DATA

<static> object POST_DATA

要使用 POST 方法发送到网址的数据；默认为 Null。指定为 String。

返回页首

静态类 gadgets.json

概述     详述

提供在对象和 JSON 之间相互转换的操作。

方法概述

<static>  Object parse(text)

解析 JSON 字符串，生成 JavaScript 值。

<static>  String stringify(v)

将 JavaScript 值转换为 JSON 字符串。

 

方法详述

parse

<static> Object parse(text)

解析 JSON 字符串，生成 JavaScript 值。

参数：
String text - 要转换为对象的字符串，通常为上一次字符串化调用的结果

返回：
Object  从传递的文本中解析的对象；如果出错，则为 False

stringify

<static> String stringify(v)

将 JavaScript 值转换为 JSON 字符串。

参数：
Object v - 要转换的对象

返回：
String  等效的 JSON

返回页首

静态类 gadgets.pubsub

概述     详述

提供发布和订阅消息频道的操作。

方法概述

<static> publish(channelName, message)

向频道发布字符串型消息。

<static> subscribe(channelName, callback)

为小工具订阅消息频道。

<static> unsubscribe(channelName)

为小工具取消订阅消息频道。

 

方法详述

publish

<static> publish(channelName, message)

向频道发布字符串型消息。

参数：
String channelName - 频道的名称
String message - 要发布的消息

subscribe

<static> subscribe(channelName, callback)

为小工具订阅消息频道。

参数：
String channelName - 频道的名称
Function callback - 通过频道消息调用的函数

unsubscribe

<static> unsubscribe(channelName)

为小工具取消订阅消息频道。

参数：
String channelName - 频道的名称

返回页首

静态类 gadgets.rpc

概述     详述

为小工具到容器、容器到小工具和小工具到小工具通讯提供远程程序调用操作。

方法概述

<static> call(targetId, serviceName, callback, var_args)

调用 RPC 服务。

<static> register(serviceName, handler)

注册 RPC 服务。

<static> registerDefault(handler)

注册一个默认的服务处理程序以处理所有未知的远程程序调用，这些调用在默认情况下对失败不做任何反应。

<static> unregister(serviceName)

取消注册 RPC 服务。

<static> unregisterDefault()

取消注册默认的服务处理程序。

 

方法详述

call

<static> call(targetId, serviceName, callback, var_args)

调用 RPC 服务。

参数：
String targetId - RPC 服务提供商的 ID；如果调用父容器，则该参数为空
String serviceName - 要调用的服务名称
Function, null callback - 用于处理 RPC 请求的返回值的回调函数（如果有的话）
* var_args - RPC 请求的参数

register

<static> register(serviceName, handler)

注册 RPC 服务。

参数：
String serviceName - 要注册的服务名称
Function handler - 服务处理程序

registerDefault

<static> registerDefault(handler)

注册一个默认的服务处理程序以处理所有未知的远程程序调用，这些调用在默认情况下对失败不做任何反应。

参数：
Function handler - 服务处理程序

unregister

<static> unregister(serviceName)

取消注册 RPC 服务。

参数：
String serviceName - 要取消注册的服务名称

unregisterDefault

<static> unregisterDefault()

取消注册默认的服务处理程序。以后的未知远程程序调用对失败将不做任何反应。

返回页首

静态类 gadgets.skins

概述     详述

提供获取有关当前所显示外观的显示信息的操作。

方法概述

<static>  String getProperty(propertyKey)

获取映射至指定关键字的显示属性。

 

方法详述

getProperty

<static> String getProperty(propertyKey)

获取映射至指定关键字的显示属性。

参数：
String propertyKey - 要获取数据的关键字；关键字在 中定义 gadgets.skins.Property

返回：
String  数据

返回页首

静态类 gadgets.skins.Property

概述     详述

可以在小工具 UI 中获取和使用的所有显示值。这些显示值是 gadgets.skins.getProperty() 方法支持的关键字。

Field 概述

<static> object ANCHOR_COLOR

锚点标签应使用的颜色。

<static> object BG_COLOR

小工具的背景颜色。

<static> object BG_IMAGE

要在小工具的背景中使用的图像。

<static> object FONT_COLOR

应用来呈现主要字体的颜色。

 

Field 详述

ANCHOR_COLOR

<static> object ANCHOR_COLOR

锚点标签应使用的颜色。

BG_COLOR

<static> object BG_COLOR

小工具的背景颜色。

BG_IMAGE

<static> object BG_IMAGE

要在小工具的背景中使用的图像。

FONT_COLOR

<static> object FONT_COLOR

应用来呈现主要字体的颜色。

返回页首

静态类 gadgets.util

概述     详述

提供通用的实用工具功能。

方法概述

<static>  String escapeString(str)

使用 HTML 实体转义输入以使其更安全。

<static>  Object getFeatureParameters(feature)

返回该功能的参数的值。

<static>  Boolean hasFeature(feature)

返回指定的功能是否受支持。

<static> registerOnLoadHandler(callback)

注册装载处理程序 - 小工具加载时执行的函数。

<static>  String unescapeString(str)

反转义 escapeString

 

方法详述

escapeString

<static> String escapeString(str)

使用 HTML 实体转义输入以使其更安全。以下字符受影响：
• 新行（\n，Unicode 码点 10）
• 回车（\r，Unicode 13）
• 双引号（"，Unicode 34）
• & 符号（&，Unicode 38）
• 单引号（'，Unicode 39）
• 左尖括号（<，Unicode 60）
• 右尖括号（>，Unicode 62）
• 反斜线（\，Unicode 92）
• 行分隔符 (Unicode 8232)
• 段落分隔符 (Unicode 8233)

参数：
String str - 要转义的字符串

返回：
String  转义的字符串

getFeatureParameters

<static> Object getFeatureParameters(feature)

返回该功能的参数的值。小工具使用 <Requires> 或 <Optional> 元素的 <Param> 子元素指定参数。

参数：
String feature - 要获取其参数的功能

返回：
Object  指定功能的参数，或 Null

hasFeature

<static> Boolean hasFeature(feature)

返回指定的功能是否受支持。

参数：
String feature - 要测试的功能

返回：
Boolean  如果功能受支持，则返回 True

registerOnLoadHandler

<static> registerOnLoadHandler(callback)

注册装载处理程序 - 小工具加载时执行的函数。

参数：
Function callback - 要运行的处理程序

unescapeString

<static> String unescapeString(str)

反转义 escapeString

参数：
String str - 要反转义的字符串。

返回：
String  反转义的字符串

返回页首

静态类 gadgets.views

概述     详述

提供用于处理视图的操作。

另请参阅：gadgets.views.View

 

方法概述

<static>  String bind(urlTemplate, environment)

将网址模板与传递环境中的变量绑定在一起以生成网址字符串。

<static>  gadgets.views.View getCurrentView()

返回当前视图。

<static>  Map.<String, String> getParams()

返回已传递到此视图的该小工具中的参数。

<static>  Map<gadgets.views.ViewType, String, gadgets.views.View> getSupportedViews()

返回所有受支持的视图的映射。

<static> requestNavigateTo(view, opt_params, opt_ownerId)

尝试在其他视图中浏览至该小工具。

 

方法详述

bind

<static> String bind(urlTemplate, environment)

将网址模板与传递环境中的变量绑定在一起以生成网址字符串。

另请参阅：View.getUrlTemplate()

参数：
urlTemplate - 容器视图的网址模板
environment - 类型字符串的一组已命名的变量（例如，[OWNER | PATH | PARAMS | NAME]）。

返回：
String  网址字符串

getCurrentView

<static> gadgets.views.View getCurrentView()

返回当前视图。

返回：
gadgets.views.View  当前视图

getParams

<static> Map.<String, String> getParams()

返回已传递到此视图的该小工具中的参数。不要加入有网址参数，只加入传递至 gadgets.views.requestNavigateTo 的网址参数。

返回：
Map.<String, String>  参数映射

getSupportedViews

<static> Map<gadgets.views.ViewType, String, gadgets.views.View> getSupportedViews()

返回所有受支持的视图的映射。按照每个 gadgets.view.View 的名称添加关键字。

返回：
Map<gadgets.views.ViewType, String, gadgets.views.View>  所有受支持的视图，按照其名称属性添加关键字。

requestNavigateTo

<static> requestNavigateTo(view, opt_params, opt_ownerId)

尝试在其他视图中浏览至该小工具。如果容器支持，则参数会将可选参数传递给新视图中的小工具。

参数：
gadgets.views.View view - 要浏览的目标视图
Map.<String, String> opt_params - 在界面上浏览至小工具后，要传递到该小工具的参数
String opt_ownerId - 要浏览的目标页面所有者的 ID；默认为当前所有者

返回页首

类 gadgets.views.View

概述     详述

所有视图对象的基本界面。

方法概述

 String bind(environment)

将视图的网址模板与传递环境中的变量绑定在一起以生成网址字符串。

 gadgets.views.ViewType, String getName()

返回该视图的名称。

 String getUrlTemplate()

使用要替换的变量来返回符合 IETF 规范草稿的字符串网址模板。

 boolean isOnlyVisibleGadget()

如果该小工具是本视图中唯一可见的小工具，则返回 True。

 

方法详述

bind

String bind(environment)

将视图的网址模板与传递环境中的变量绑定在一起以生成网址字符串。

另请参阅：getUrlTemplate()

参数：
environment - 类型字符串的一组已命名的变量（例如，[OWNER | PATH | PARAMS | NAME]）。

返回：
String  网址字符串

getName

gadgets.views.ViewType, String getName()

返回该视图的名称。

返回：
gadgets.views.ViewType, String  视图名称，通常指定为 gadgets.views.ViewType

getUrlTemplate

String getUrlTemplate()

使用要替换的变量来返回符合 IETF 规范草稿的字符串网址模板。

支持以下四个变量：

name

应用程序的名称或 ID

owner

页面所有者的 ID

path

路径步骤的数组

params

关联的数组或 array[param1,value1,param2,value2,...]

示例

以下是两个有效的网址模板字符串：

http://container.com/{-list|/|name,owner,path}?{-join|&|params}
http://container.com/apps/{name}/{owner}{-prefix|/|path}{-opt|?os_|params}{-join|&os_|params} 

以下是一些参数：

{ 
 name : 'Wilma',
 owner : 'Betty',
 path : ['dino','car'], 
 params = { a : 'Barney', b : 'Fred'}
}

通过这些参数，两个实例网址模板字符串可以解析出以下网址：

http://container.com/Wilma/Betty/dino/car?a=Barney&b=Fred
http://container.com/apps/Wilma/Betty/dino/car?os_a=Barney&os_b=Fred

另请参阅：bind()

返回：
String  可用于构建浏览至该视图的网址的模板

isOnlyVisibleGadget

boolean isOnlyVisibleGadget()

如果该小工具是本视图中唯一可见的小工具，则返回 True。在画布页面上或最大化模式下，通常为 True；在个人资料页面上或面板模式下，通常为 False。

返回：
boolean  如果该小工具是唯一可见的小工具，则返回 True；否则，返回 False

返回页首

静态类 gadgets.views.ViewType

概述     详述

由 Views 使用。

Field 概述

<static> object CANVAS

以巨大模式显示小工具的视图。

<static> object HOME

在小区域中显示小工具的视图，其所在页面通常还包含其他小工具。

<static> object PREVIEW

小工具的演示视图。

<static> object PROFILE

在小区域中显示小工具的视图，其所在页面通常还包含其他小工具。

 

Field 详述

CANVAS

<static> object CANVAS

以巨大模式显示小工具的视图。通常是页面上的主要内容。查看者与所有者并不总是相同。

HOME

<static> object HOME

在小区域中显示小工具的视图，其所在页面通常还包含其他小工具。通常查看者与所有者相同。

PREVIEW

<static> object PREVIEW

小工具的演示视图。在该视图中，所有者和查看者均未知。

PROFILE

<static> object PROFILE

在小区域中显示小工具的视图，其所在页面通常还包含其他小工具。查看者与所有者并不总是相同。

返回页首

静态类 gadgets.window

概述     详述

提供获取有关信息以及修改放置小工具的窗口的操作。

方法概述

<static> adjustHeight(opt_height)

调整小工具高度.

<static>  Object getViewportDimensions()

检测框架的内部尺寸。

<static> setTitle(title)

设置小工具标题。

 

方法详述

adjustHeight

<static> adjustHeight(opt_height)

调整小工具高度.

参数：
Number opt_height - 可选的首选高度（以像素为单位）；如果未指定，则尝试调整该小工具使其适合相应内容

getViewportDimensions

<static> Object getViewportDimensions()

检测框架的内部尺寸。有关详细信息，请参阅 http://www.quirksmode.org/dom/w3c_cssom.html。

返回：
Object  具有宽度和高度属性的对象

setTitle

<static> setTitle(title)

设置小工具标题。

参数：
String title - 首选标题