建立自訂元件

總覽

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 方法建立的元件會自動繼承所有內建元件 (getsetononceoffemit) 共用的基本方法。這可確保所有元件都能以一致且可預測的方式運作。

舉例來說,假使您的元件需要使用者授權,您可以使用沿用的事件處理方法完成這項設定。

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 等日期格式設定程式庫。並記錄元件依附元件和元件使用者,以確保符合這些依附元件。