小工具 JavaScript 参考文档

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

本文档介绍了 gadgets.* 命名空间中的类和方法,其中一些类和方法特定于功能。如需了解如何添加功能,请参阅小工具规范

类型惯例

本文档使用以下类型惯例:

Array&T; Array.<T>
仅填充 T 类型的对象的数组。 此惯例类似于 Java 泛型。
Map<K, V> 或 Map.<K, V>
一个类型为 K 且映射到 V 类型值的键的 JavaScript 对象。同样,这种惯例类似于 Java 泛型。它通常用于 opt_params 变量。
静态
标有静态类的类型没有公共或私有构造函数。换句话说,类型是命名空间,而不是可实例化以创建对象的类。此类中的字段和函数也会被标记为 static
布尔值
布尔值(不是 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 - 关闭消息时要调用的可选回调函数
    返回
      已创建的消息的 HTML 元素

createStaticMessage

HTMLElement createStaticMessage(message)
    创建只能通过程序化方式关闭的静态消息(通过调用 dismissMessage())。
    参数
    String, Object message - 作为 HTML 字符串或 DOM 元素的消息
返回
    HTMLElement  已创建的消息的 HTML 元素
{11

create 计时器消息

HTMLElement createTimerMessage(message, seconds, opt_callback)
    创建显示指定秒数的消息。 当计时器到期时,系统会关闭消息并执行可选的回调函数。
    参数
      String, Object message - 消息(采用 HTML 字符串或 DOM 元素形式)
      number seconds - 关闭消息前等待的秒数
      Function opt_callback - 在关闭消息时调用的可选回调函数
    返回
      HTMLElement  HTMLElement  HTMLElement  HTMLElement 

      关闭消息

      dismissMessage(message)
        关闭指定的消息。
        参数
          HTMLElement message - 要移除的消息的 HTML 元素

      返回页首

      Gadgets.Prefs 类

      提供用户偏好设置、模块维度和消息的访问权限。 客户端可以通过构建 Gadgets.Prefs 实例并传入其模块 ID 来访问其偏好设置。示例:

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

      构造函数摘要

      gadgets.Prefs(opt_moduleId)
      创建新的 Prefs 对象。
       

      方法摘要

       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(opt_moduleId)
        创建一个新的 Prefs 对象。
        参数
          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)
        存储偏好设置。 如需使用此调用,小工具必须设置功能偏好设置。

        注意:如果小工具需要存储一个数组,则应使用 setArray 而非此调用。

        参数
          String key - 存储偏好设置
          Object val - 要存储的值

      setArray

      setArray(key, val)
        存储数组偏好设置。 如需使用此调用,小工具必须设置功能偏好设置。
        参数
          String key - 存储偏好设置
          Array val - 要存储的值

      返回页首

      小工具.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)
      创建新的 TabSet 对象

      方法摘要

       String addTab(tabName, opt_params)
      根据 Opt_params 中指定的名称-值对添加一个新标签页。
      alignTabs(align, opt_offset)
      设置标签页的对齐方式。
      displayTabs(display)
      显示或隐藏标签页和所有关联内容。
       HTMLElement getHeaderContainer()
      返回标签页标题容器元素。
       gadgets.Tab getSelectedTab()
      返回当前选定的标签页对象。
       Array.<gadgets.Tab> getTabs()
      返回包含所有现有标签页对象的数组。
      removeTab(tabIndex)
      移除 tabIndex 中的某个标签页及其所有关联内容。
      setSelectedTab(tabIndex)
      在 tabIndex 中选择标签页,并触发标签页回调函数(如果存在)。
      swapTabs(tabIndex1, tabIndex2)
      在 tabIndex1 和 tabIndex2 中切换标签页的位置。
       

      构造函数详细信息

      Gadgets.TabSet

      gadgets.TabSet(opt_moduleId, opt_defaultTab, opt_container)
        创建新的 TabSet 对象
        参数
          String opt_moduleId - 标签页容器 ID 的可选后缀
          String opt_defaultTab - 可选标签名称,用于指定初始化后选择的标签页名称;如果省略此参数,则第一个标签页会默认选择以下格式:

        方法详细信息

        添加标签页

        String addTab(tabName, opt_params)
          根据 Opt_params 中指定的名称-值对添加一个新标签页。 opt_params 支持以下属性:
          contentContainer
          一个现有的 HTML 元素,用作标签页内容容器。如果省略,标签页库会创建一个。
          callback
          选择标签页后要执行的回调函数。
          工具提示
          当用户将鼠标光标移到该标签页上时弹出的提示说明。
          index
          表示要插入制表符的索引。如果省略,则新标签页会附加到末尾。
          参数
            String tabName - 要创建的标签页的标签
            Object opt_params - 可选参数对象
          返回结果
            String  标签页容器的 DOM ID

        对齐

        alignTabs(align, opt_offset)
          设置标签页的对齐方式。默认情况下,标签页居中对齐。图片:

          显示标签页

          displayTabs(display)
            显示或隐藏标签页及所有关联内容。
            参数
              Boolean display - 若为 true,则显示标签页;为 false,则隐藏标签页

          getHeaderContainer

          HTMLElement getHeaderContainer()
            返回标签页标头容器元素。
            返回结果
              HTMLElement  标签页标题容器元素

          getSelectedTab

          gadgets.Tab getSelectedTab()
            返回当前选定的标签页对象。
            返回
              gadgets.Tab 当前选定的标签页对象

          getTabs

          Array.<gadgets.Tab> getTabs()
            返回所有现有标签页对象的数组。
            返回值
              Array.<gadgets.Tab>  所有现有标签页对象的数组

          移除 Tab

          removeTab(tabIndex)
            移除 tabIndex 中的某个标签页及其所有关联内容。
            参数
              Number tabIndex - 要移除的标签页的索引

          setSelectedTab

          setSelectedTab(tabIndex)
            选择 tabIndex 所在的标签页,并触发该回调函数(如果存在)。如果已经选择过该标签页,则不会触发回调。
            参数
              Number tabIndex - 要选择的标签页的索引

          交换标签页

          swapTabs(tabIndex1, tabIndex2)
            切换 TabIndex1 和 tabIndex2 中的标签页位置。所选标签页不会发生变化,也不会调用任何回调函数。
            参数
              Number tabIndex1 - 第一个要切换的标签页的索引
              Number tabIndex2 - 要切换的次级标签页的索引

          返回页首

          静态类小工具.flash

          在小工具中嵌入 Flash 内容。

          方法摘要

          <static>  Boolean embedCachedFlash()
          将缓存的 Flash 文件注入 DOM 树。
          <static>  Boolean embedFlash(swfUrl, swfContainer, swfVersion, opt_params)
          将 Flash 文件注入 DOM 树。
          <static>  Number getMajorVersion()
          检测 Flash Player 及其主要版本。
           

          方法详细信息

          嵌入式缓存 Flash

          <static> Boolean embedCachedFlash()
            将缓存的 Flash 文件注入 DOM 树。 接受的参数与 Gadgets.flash.embedFlash 所用的参数相同。
            返回
              Boolean  函数调用是否成功完成

          嵌入 Flash

          <static> Boolean embedFlash(swfUrl, swfContainer, swfVersion, opt_params)
            将 Flash 文件注入 DOM 树中。
            参数
              String swfUrl - SWF 网址
              String, Object swfContainer - 现有 HTML 容器元素的 ID 或对象引用
              Number swfVersion - 所需的 Flash Player 最低版本
              Object opt_params - 可能包含任何有效 HTML 参数的可选对象;所有属性都将在创建后传递到 Flash 影片
          11/} 1

          getMajorVersion

          <static> Number getMajorVersion()
            检测 Flash Player 及其主要版本。
            返回值
              Number  Flash 播放器的主要版本 或 0(如果不支持 Flash)

          返回页首

          静态类小工具.io

          提供远程内容检索功能。

          方法摘要

          <static>  String encodeValues(fields)
          将输入对象转换为网址编码的数据字符串。
          <static>  String getProxyUrl(url, opt_params)
          获取传入网址的代理版本。
          <static> makeRequest(url, callback, opt_params)
          从提供的网址中提取内容,并将相应内容馈送到回调函数。
           

          方法详细信息

          编码值

          <static> String encodeValues(fields)
            将输入对象转换为网址编码的数据字符串。 (key=value&...)
            参数
              Object fields - 要编码的帖子字段
            返回
              已处理的帖子数据;这包括末尾的和号 (&)

          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. 移除所有名称以 oauthxoauthopensocial 开头的请求参数(不区分大小写)。

            2. 将以下参数添加到请求查询字符串:

              opensocial_viewer_id
              可选。
              当前查看者的 ID,与查看者人员对象的 getId() 值匹配。
              opensocial_owner_id
              必需
              当前所有者的 ID,与所有者用户对象的 getId() 值匹配。
              opensocial_app_url
              必需
              发出请求的应用的网址。在应用更改网址时,容器可以将多个应用网址别名为一个规范应用网址。
              opensocial_instance_id
              可选。
              不透明标识符,用于区分同一容器中同一应用的多个实例。如果容器不允许同一应用的多个实例共存,则可以省略此参数。opensocial_app_urlopensocial_instance_id 的组合可唯一标识容器中的应用实例。
              opensocial_app_id
              可选。
              特定容器独有的应用不透明标识符。 希望保持与 opensocial-0.7 规范的向后兼容性的容器可以包含此参数。
              xoauth_signature_publickey
              可选。
              用于对请求进行签名的公钥的不透明标识符。如果容器不使用公钥为请求签名,或者容器安排了其他与请求目标匹配的密钥分发方式,则可以省略此参数。
            3. 根据 OAuth 规范第 9 节对生成的请求进行签名。

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

          如果容器使用公钥对请求进行签名,则容器可能会选择使用自签名证书或由知名证书授权机构签名的证书。如果容器未通过 HTTPS 分发其 OAuth 签名密钥,则应使用由知名证书授权机构签名的证书。

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

          容器应使其公钥位于已知位置供用户下载。建议使用 https://container-hostname/opensocial/certificates/xoauth_signature_publickeyvalue 位置。

          签名请求的收件人必须验证请求的签名是否正确,以及请求的时间戳是否在合理的时间范围内。建议在当前时间之前和之后 5 分钟的时间段。

          签名请求的收件人可以使用 oauth_consumer_keyxoauth_signature_publickey 参数来自动检测容器何时部署新证书。如果容器在一个已知的位置部署证书,收件人可能会自动下载新证书。自动下载新证书的收件人应缓存生成的证书。

          如果未从 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 &Service> 元素所使用的昵称。如果未指定,则默认为“”。
          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 对象:

          &oauthot;oauthApprovalUrl”
          如果指定了此值,用户将需要访问外部网页才能批准小工具访问数据的请求。建议使用弹出式窗口将用户定向到外部页面。用户批准访问后,小工具就可以重复 makeRequest 调用以检索数据。
          &oauthot;oauthError"
          如果指定此值,则表示发生了与 OAuth 相关的错误。该值将是一组用于以编程方式检测错误的字符串常量。这些常量对 opensocial-0.8 没有定义,但实现人员应尝试就一组标准化的 OpenSocial-0.9 中有用的常量值达成一致。
          "oauthErrorText”
          如果指定此值,则表示发生了与 OAuth 相关的错误。该值是自由格式文本,可用于为小工具开发者提供调试信息。
            参数
              String url - 内容所在的网址
              Function callback - 提取网址后在数据中调用的函数
              Map.<gadgets.io.RequestParameters, Object> opt_params - 其他 请求参数代理 1

              返回页首

              静态类小工具.io.AuthorizationType

              RequestParameters 使用。

              字段摘要

              <static> object NONE
              无授权。
              <static> object OAUTH
              容器将使用 OAuth 进行身份验证。
              <static> object SIGNED
              请求将由容器进行签名。
               

              字段详细信息

              <static> object NONE
                无授权。

              OAuth

              <static> object OAUTH
                容器将使用 OAuth 进行身份验证。

              已签名

              <static> object SIGNED
                请求将由容器签名。

              返回页首

              静态类小工具.io.ContentType

              RequestParameters 使用。

              字段摘要

              <static> object DOM
              返回一个 DOM 对象,用于提取 XML。
              <static> object FEED
              返回 RSS 或 Atom Feed 的 JSON 表示法。
              <static> object JSON
              返回 JSON 对象。
              <static> object TEXT
              返回文本;用于提取 HTML。
               

              字段详细信息

              DOM

              <static> object DOM
                返回 DOM 对象,用于提取 XML。

              FEED

              <static> object FEED
                返回 RSS 或 Atom Feed 的 JSON 表示法。

              JSON

              <static> object JSON
                返回 JSON 对象。

              TEXT

              <static> object TEXT
                返回文本;用于提取 HTML。

              返回页首

              静态类 Gadgets.io.MethodType

              定义 RequestParameters.METHOD 的值。

              字段摘要

              <static> object DELETE
              对此方法类型的容器支持是可选的。
              <static> object GET
              默认类型。
              <static> object HEAD
              对此方法类型的容器支持是可选的。
              <static> object POST
              对此方法类型的容器支持是可选的。
              <static> object PUT
              对此方法类型的容器支持是可选的。
               

              字段详细信息

              删除

              <static> object DELETE
                可选择是否支持此方法类型的容器。

              GET

              <static> object GET
                默认类型。
              <static> object HEAD
                可选择是否支持此方法类型的容器。

              POST

              <static> object POST
                可选择是否支持此方法类型的容器。

              PUT

              <static> object PUT
                可选择是否支持此方法类型的容器。

              返回页首

              静态类 Gadgets.io.ProxyUrlRequestParameters

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

              字段摘要

              <static> object REFRESH_INTERVAL
              尝试使用内容缓存。
               

              字段详细信息

              刷新_INTERVAL

              <static> object REFRESH_INTERVAL
                尝试使用内容缓存。刷新间隔是我们希望缓存给定响应的秒数。默认情况下,系统将遵循 HTTP 标头。如果没有任何 HTTP 标头,此值将默认为 3600(一小时)。请注意,签名请求和具有 POST_DATA 的对象通常不会被缓存。

              返回页首

              静态类 Gadgets.io.RequestParameters

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

              字段摘要

              <static> object AUTHORIZATION
              提取内容时要使用的身份验证类型;默认值为 AuthorizationType.NONE
              <static> object CONTENT_TYPE
              位于网址中的内容的类型;默认值为 ContentType.TEXT
              <static> object GET_SUMMARIES
              如果内容是 Feed,则是否提取该 Feed 的摘要;默认为 false。
              <static> object HEADERS
              要发送到网址的 HTTP 标头;默认为 null。
              <static> object METHOD
              从网址提取内容时要使用的方法;默认值为 MethodType.GET
              <static> object NUM_ENTRIES
              如果内容是 Feed,则要提取的条目数;默认值为 3。
              <static> object POST_DATA
              使用 POST 方法发送到网址的数据;默认值为 null。
               

              字段详细信息

              授权

              <static> object AUTHORIZATION
                提取内容时要使用的身份验证类型;默认值为 AuthorizationType.NONE。 指定为 AuthorizationType

              CONTENT_TYPE

              <static> object CONTENT_TYPE
                网址上的内容的类型;默认值为 ContentType.TEXT。指定为 ContentType

              GET_SUMMARIES

              <static> object GET_SUMMARIES
              如果内容是 Feed,则是否提取该 Feed 的摘要;默认值为 false。
                指定为 Boolean

              标头

              <static> object HEADERS
                要发送到网址的 HTTP 标头;默认为 null。指定为 Map.<String,String>

              方法

              <static> object METHOD
                从网址提取内容时要使用的方法;默认值为 MethodType.GET。 有效值由 MethodType 指定。

              NUM_ENTRIES 条

              <static> object NUM_ENTRIES
                如果内容是 Feed,则要提取的条目数;默认值为 3。 指定为 Number

              POST_数据

              <static> object POST_DATA
                使用 POST 方法发送到网址的数据;默认值为 null。 指定为 String

              返回页首

              静态类小工具.json

              提供将对象转换为 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

              字符串化

              <static> String stringify(v)
                将 JavaScript 值转换为 JSON 字符串。
                参数
                  Object v - 要转换的对象
                返回
                  String  JSON 等效项

              返回页首

              静态类小工具.pubsub

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

              方法摘要

              <static> publish(channelName, message)
              向渠道发布字符串类型消息。
              <static> subscribe(channelName, callback)
              为消息渠道订阅小工具。
              <static> unsubscribe(channelName)
              退订来自消息渠道的小工具。
               

              方法详细信息

              publish

              <static> publish(channelName, message)
                将字符串类型消息发布到渠道。
                参数
                  String channelName - 渠道的名称
                  String message - 要发布的消息

              订阅

              <static> subscribe(channelName, callback)
                为小工具订阅消息渠道。
                参数
                  String channelName - 渠道的名称
                  Function callback - 将通过渠道消息调用的函数

              unsubscribe

              <static> unsubscribe(channelName)
                为小工具退订消息渠道。
                参数
                  String channelName - 渠道的名称

              返回页首

              静态类小工具.rpc

              提供对小工具到容器、容器到小工具以及小工具到小工具的通信进行远程过程调用的操作。

              方法摘要

              <static> call(targetId, serviceName, callback, var_args)
              调用 RPC 服务。
              <static> register(serviceName, handler)
              注册 RPC 服务。
              <static> registerDefault(handler)
              注册默认服务处理程序,以处理所有未知的远程过程调用,这些调用默认以静默方式失败。
              <static> unregister(serviceName)
              取消注册 RPC 服务。
              <static> unregisterDefault()
              取消注册默认服务处理程序。
               

              方法详细信息

              打电话

              <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 - 服务处理程序

              注册默认值

              <static> registerDefault(handler)
                注册默认服务处理程序,以处理所有未知的远程过程调用,这些调用默认以静默方式失败。
                参数
                  Function handler - 服务处理程序

              unregister

              <static> unregister(serviceName)
                取消注册 RPC 服务。
                参数
                  String serviceName - 要取消注册的服务名称

              取消注册默认值

              <static> unregisterDefault()
                取消注册默认服务处理程序。未来的未知远程过程调用将静默失败。

              返回页首

              静态类小工具.skins

              提供用于获取有关当前显示的皮肤的显示信息的操作。

              方法摘要

              <static>  String getProperty(propertyKey)
              获取映射到指定键的显示属性。
               

              方法详细信息

              getProperty

              <static> String getProperty(propertyKey)
                提取映射到指定键的显示属性。
                返回
                  String  数据
              { 15/}6

              返回页首

              静态类小工具.skins.Property

              可在小工具界面中提取和使用的所有显示值。这些是 Gadgets.skins.getProperty() 方法支持的键。

              字段摘要

              <static> object ANCHOR_COLOR
              锚标记应使用的颜色。
              <static> object BG_COLOR
              小工具背景颜色。
              <static> object BG_IMAGE
              在小工具背景中使用的图片。
              <static> object FONT_COLOR
              应呈现主字体的颜色。
               

              字段详细信息

              ANCHOR_COLOR

              <static> object ANCHOR_COLOR
                锚标记应使用的颜色。

              背景颜色

              <static> object BG_COLOR
                小工具背景颜色。

              背景图片

              <static> object BG_IMAGE
                小工具后台使用的图片。

              字体颜色

              <static> object FONT_COLOR
                应呈现主字体的颜色。

              返回页首

              静态类小工具.util

              提供通用实用函数。

              方法摘要

              <static>  String escapeString(str)
              使用 HTML 实体转义输入,提高安全性。
              <static>  Object getFeatureParameters(feature)
              返回该特征的参数值。
              <static>  Boolean hasFeature(feature)
              返回是否支持指定的功能。
              <static> registerOnLoadHandler(callback)
              注册 onload 处理程序 - 加载小工具时执行的函数。
              <static>  String unescapeString(str)
              反转 EscString

              方法详细信息

              转义字符串

              <static> String escapeString(str)
                使用 HTML 实体转义输入,提高安全性。 以下字符会受到影响:
                • 换行符(\n,Unicode 代码点 10)
                • 回车符 (\r, Unicode 13)
                • 英文双引号(",Unicode 34)
                • 和号 (&,Unicode 38)
                • 单引号(',Unicode 39)
                • 左尖括号(&lt;Unicode 60)
                • 右尖括号(&gt;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 - 要运行的处理程序

              非转义字符串

              <static> String unescapeString(str)
                反转 EscString
                参数
                  String str - 要取消转义的字符串。
                返回值
                  String 非转义字符串

              返回页首

              静态类小工具.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()
                返回包含所有受支持视图的地图。按名称控制每个小工具.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 - 导航到 Surface 后要传递给小工具的参数
                  String opt_ownerId - 要导航到的页面所有者的 ID; 默认值为当前所有者
              / / / /

              返回页首

              Gadgets.views.View 类

              所有视图对象的基接口。

              方法摘要

               String bind(environment)
              将视图的网址模板与传递环境中的变量绑定,以生成网址字符串。
               gadgets.views.ViewType, String getName()
              返回此视图的名称。
               String getUrlTemplate()
              返回符合 IETF 规范草稿的字符串 URI 模板,并在其中替换变量。
               boolean isOnlyVisibleGadget()
              如果此视图中只有这个小工具,则返回 true。
               

              方法详细信息

              bind

              String bind(environment)
                将视图的网址模板与传递环境中的变量绑定,以生成网址字符串。

                另请参阅getUrlTemplate()

                参数
                  environment - 一组类型为字符串的命名变量(例如 [OWNER | PATH | PARAMS | NAME])。
                返回值
                  String  网址字符串

              getName

              gadgets.views.ViewType, String getName()
                返回此视图的名称。
                返回次数
                  gadgets.views.ViewType, String  视图名称,通常指定为 widgets.views.ViewType

              getUrlTemplate

              String getUrlTemplate()
                返回符合 IETF 规范草稿的字符串 URI 模板,并在其中替换变量。

                支持四种变量:

                name
                应用的名称或 ID
                所有者
                信息页所有者的 ID
                路径
                一组路径步骤
                params
                关联数组或数组 [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

              View 使用。

              字段摘要

              <static> object CANVAS
              视图在非常大模式下显示小工具。
              <static> object HOME
              一个视图,其中小工具通常显示在包含其他小工具的页面上。
              <static> object PREVIEW
              该小工具的演示视图。
              <static> object PROFILE
              一个视图,其中小工具通常显示在包含其他小工具的页面上。
               

              字段详细信息

              CANVAS

              <static> object CANVAS
                在超大模式下显示小工具的视图。它通常是网页上的主要内容。查看者不一定与所有者相同。

              HOME

              <static> object HOME
                该视图通常在包含其他小工具的页面上显示为小区域。通常情况下,观看者与所有者是相同的。

              预览

              <static> object PREVIEW
                小工具的演示视图。在此视图中,所有者和查看者未知。

              资料

              <static> object PROFILE
                该视图通常在包含其他小工具的页面上显示为小区域。观看者不一定与所有者相同。

              返回页首

              静态类小工具.window

              提供关于获取和修改放置小工具的窗口的操作。

              方法摘要

              <static> adjustHeight(opt_height)
              调整小工具的高度。
              <static>  Object getViewportDimensions()
              检测帧的内部尺寸。
              <static> setTitle(title)
              设置小工具标题。
               

              方法详细信息

              调整高度

              <static> adjustHeight(opt_height)
                调整小工具高度。
                参数
                  Number opt_height - 可选的首选高度(以像素为单位);如果未指定,系统会尝试将小工具与其内容进行匹配

              getViewportDimension

              <static> Object getViewportDimensions()
                返回
                  Object  具有宽度和高度属性的对象

              setTitle

              <static> setTitle(title)
                设置小工具标题。
                参数
                  String title - 首选标题

              返回页首