创建自定义组件

概览

Embed API 附带了许多内置组件，您也可以轻松创建自己的组件。本文档将向您介绍如何创建新的自定义组件以及如何将第三方组件添加到您的应用。

创建自定义组件

要创建自定义 Embed API 组件，您需要调用 gapi.analytics.createComponent 并传递组件名称和方法对象。

传递到 createComponent 的名称将成为组件构造函数的名称，并且存储在 gapi.analytics.ext 中。方法对象应包含您想要添加到组件原型的所有函数或媒体资源。

gapi.analytics.createComponent('MyComponent', {
  execute: function() {
    alert('I have been executed!');
  }
});

创建组件后，利用 new 运算符调用组件构造函数即可使用该组件。

// Create a new instance of MyComponent.
var myComponentInstance = new gapi.analytics.ext.MyComponent();

// Invoke the `execute` method.
myComponentInstance.execute() // Alerts "I have been executed!"

initialize 方法

通过将方法对象传递至 createComponent，您可以访问组件原型，但无权访问组件构造函数。

为解决这一问题，新 Embed API 组件创建之后会自动查找是否存在名为 initialize 的方法。如果存在，系统会利用传递给构造函数的参数来调用该方法。您应将平常放入构造函数的所有逻辑放入 initialize 方法中。

以下示例在创建新 MyComponent 实例时设置了一些默认的媒体资源。

gapi.analytics.createComponent('MyComponent', {
  initialize: function(options) {
    this.name = options.name;
    this.isRendered = false;
  }
});

var myComponentInstance = new gapi.analytics.ext.MyComponent({name: 'John'});
alert(myComponentInstance.name); // Alerts "John"
alert(myComponentInstance.isRendered); // Alerts false

继承的方法

采用 createComponent 方法创建的组件将自动继承所有内置组件（get、set、on、once、off 和 emit）共享的基本方法。这样就可以确保所有组件都可以按照相同的方式运行，运行结果也在预期之内。

例如，如果您的组件需要用户获得授权，则使用继承的事件处理方法即可实现此要求。

gapi.analytics.createComponent('MyComponent', {
  initialize: function() {
    this.isRendered = false;
  },
  execute: function() {
    if (gapi.analytics.auth.isAuthorized()) {
      this.render();
    }
    else {
      gapi.analytics.auth.once('success', this.render.bind(this));
    }
  },
  render: function() {
    if (this.isRendered == false) {

      // Render this component...

      this.isRendered = true;
      this.emit('render');
    }
  }
});

var myComponentInstance = new gapi.analytics.ext.MyComponent();

// Calling execute here will delay rendering until after
// the user has been successfully authorized.
myComponentInstance.execute();
myComponent.on('render', function() {
  // Do something when the component renders.
});

等待库准备就绪

Embed API 代码段异步加载库及其所有依赖项。这意味着系统无法立即调用 createComponent 等方法，调用此类方法的代码会遭到延迟，直至所有内容加载完毕。

Embed API 可提供 gapi.analytics.ready 方法，此方法允许在加载完库后调用回调。创建自定义组件时，应始终将您的代码封装到 ready 函数中，以便所有必要方法就绪后再运行您的代码。

gapi.analytics.ready(function() {

  // This code will not run until the Embed API is fully loaded.
  gapi.analytics.createComponent('MyComponent', {
    execute: function() {
      // ...
    }
  });
});

示例

要查看如何创建自定义组件的操作示例，请访问 Github，观看 Embed API 演示。

使用第三方组件

第三方 Embed API 组件通常会封装为单独的 JavaScript 文件，您可以使用 <script> 标记将其添加到您的页面。

加载顺序至关重要，因此请务必首先添加 Embed API 代码段，然后再添加组件脚本和其他所有依赖项。

<!-- Include the Embed API snippet first. -->
<script>
(function(w,d,s,g,js,fjs){
  g=w.gapi||(w.gapi={});g.analytics={q:[],ready:function(cb){this.q.push(cb)}};
  js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
  js.src='https://apis.google.com/js/platform.js';
  fjs.parentNode.insertBefore(js,fjs);js.onload=function(){g.load('analytics')};
}(window,document,'script'));
</script>

<!-- Then include your components. -->
<script src="path/to/component.js"></script>
<script src="path/to/another-component.js"></script>

管理依赖项

组件可能包含一些依赖项，例如图表库（如 d3.js）或日期格式化库（如 moment.js）。组件开发者应确保将这些依赖关系记录在册，而组件使用者应确保提供这些依赖关系。