Tạo thành phần tuỳ chỉnh

Tổng quan

API Nhúng đi kèm với một số thành phần tích hợp sẵn và cũng giúp bạn dễ dàng tạo bản dựng của riêng mình. Tài liệu này giải thích cách tạo một thành phần tuỳ chỉnh mới và cách đưa các thành phần của bên thứ ba vào ứng dụng của bạn.

Tạo thành phần tuỳ chỉnh

Các thành phần API Nhúng tuỳ chỉnh được tạo bằng cách gọi gapi.analytics.createComponent và truyền đối tượng phương thức cũng như tên thành phần.

Tên được truyền đến createComponent sẽ là tên hàm khởi tạo của thành phần và sẽ được lưu trữ trên gapi.analytics.ext. Đối tượng phương thức phải chứa mọi hàm hoặc thuộc tính mà bạn muốn thêm vào nguyên mẫu của thành phần.

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

Sau khi tạo thành phần, bạn có thể sử dụng thành phần đó bằng cách gọi toán tử new bằng hàm khởi tạo thành phần.

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

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

Phương thức khởi tạo

Việc truyền một đối tượng phương thức đến createComponent sẽ cấp cho bạn quyền truy cập vào nguyên mẫu của thành phần, nhưng bạn không có quyền truy cập vào hàm khởi tạo của thành phần.

Để giải quyết vấn đề này, khi các thành phần API Nhúng mới được tạo, các thành phần đó sẽ tự động tìm sự hiện diện của phương thức tên là initialize. Nếu tìm thấy, lớp này sẽ được gọi bằng chính arguments đã truyền đến hàm khởi tạo. Tất cả logic mà bạn thường đặt trong hàm khởi tạo phải được đặt vào phương thức khởi tạo.

Dưới đây là ví dụ về cách đặt một số thuộc tính mặc định khi tạo các thực thể MyComponent mới.

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

Phương thức kế thừa

Các thành phần được tạo bằng phương thức createComponent sẽ tự động kế thừa các phương thức cơ sở dùng chung với mọi thành phần tích hợp sẵn (get, set, on, once, off, emit). Điều này đảm bảo tất cả các thành phần đều hoạt động theo cách nhất quán và dễ dự đoán.

Ví dụ: nếu thành phần của bạn yêu cầu người dùng phải được uỷ quyền, thì bạn có thể hoàn thành việc này bằng cách sử dụng các phương thức xử lý sự kiện kế thừa.

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.
});

Đang chờ cho đến khi thư viện sẵn sàng

Đoạn mã API Nhúng sẽ tải thư viện và tất cả phần phụ thuộc của thư viện một cách không đồng bộ. Điều này có nghĩa là các phương thức như createComponent sẽ không có sẵn ngay lập tức và mã gọi các phương thức đó phải được trì hoãn cho đến khi mọi thứ được tải.

API Nhúng cung cấp phương thức gapi.analytics.ready chấp nhận lệnh gọi lại sẽ được gọi khi thư viện được tải đầy đủ. Khi tạo các thành phần tuỳ chỉnh, bạn phải luôn bao bọc mã bên trong hàm ready để mã này không chạy trước khi có tất cả các phương thức bắt buộc.

gapi.analytics.ready(function() {

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

Sử dụng các thành phần của bên thứ ba

Các thành phần API nhúng của bên thứ ba thường được đóng gói dưới dạng tệp JavaScript riêng lẻ mà bạn có thể đưa vào trang của mình bằng cách sử dụng thẻ <script>.

Thứ tự tải rất quan trọng, vì vậy, bạn cần bao gồm đoạn mã API Nhúng trước, theo sau các tập lệnh thành phần và mọi phần phụ thuộc của các tập lệnh đó.

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

Quản lý phần phụ thuộc

Một thành phần có thể có các phần phụ thuộc, chẳng hạn như thư viện biểu đồ như d3.js hoặc thư viện định dạng ngày như moment.js. Tác giả thành phần có thể ghi chép các phần phụ thuộc này và người dùng thành phần có đảm bảo đáp ứng các phần phụ thuộc này hay không.