ایجاد کامپوننت های سفارشی، ایجاد کامپوننت های سفارشی

بررسی اجمالی

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 معمولاً به‌عنوان فایل‌های جاوا اسکریپت جداگانه بسته‌بندی می‌شوند که می‌توانید با استفاده از تگ <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 داشته باشد. مستندسازی این وابستگی ها بر عهده نویسنده کامپوننت و اطمینان از برآورده شدن این وابستگی ها بر عهده کاربر مؤلفه است.