建立自訂元件

總覽

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!"

初始化方法

將方法物件傳遞至 createComponent 可讓您存取元件的原型，但無法存取元件的建構函式。

如要解決這個問題，請在建立新的 Embed API 元件時，自動尋找是否存在名為 initialize 的方法。如果找到這個程式碼，系統會使用相同的 arguments 叫用至建構函式。您通常會放入建構函式中的所有邏輯，應改為放入初始化方法。

以下範例說明如何在建立新的 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)。元件作者可自行記錄這些依附元件，並讓元件使用者能確保符合這些依附元件。