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