创建自定义组件

概览

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 的方法。如果存在，系统将使用传递给构造函数的 arguments 来调用该方法。您应将平常放入构造函数的所有逻辑放入 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();
myComponentInstance.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() {
      // ...
    }
  });
});

使用第三方组件

第三方 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）。组件开发者应确保将这些依赖关系记录在册，而组件使用者应确保提供这些依赖关系。