إنشاء مكونات مخصصة

نظرة عامة

تأتي واجهة برمجة التطبيقات inline 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 إمكانية الوصول إلى النموذج الأوّلي للمكون، لكنه لا يمنحك الوصول إلى المنشئة للمكون الخاص بك.

لمعالجة هذه المشكلة، عند إنشاء مكونات جديدة في inline 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.
});

في انتظار تجهيز المكتبة

يُحمِّل مقتطف واجهة برمجة التطبيقات المضمّنة المكتبة وكل تبعياتها بشكل غير متزامن. وهذا يعني أنّ طرقًا مثل createComponent لن تكون متاحة على الفور، وأنّ الرمز الذي يستدعي هذه الطرق يجب تأجيله إلى أن يتم تحميل كل البيانات.

توفّر واجهة برمجة التطبيقات inline 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() {
      // ...
    }
  });
});

استخدام مكونات تابعة لجهة خارجية

يتم عادةً حزمة مكوّنات واجهة برمجة التطبيقات المضمّنة التابعة لجهة خارجية كملفات JavaScript فردية يمكنك تضمينها في صفحتك باستخدام علامة <script>.

ترتيب التحميل مهم، لذا من المهم تضمين مقتطف واجهة برمجة التطبيقات أولاً، متبوعًا بالبرامج النصية للمكوّنات وأي من تبعياتها.

<!-- 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. الأمر متروك لمؤلف المكون لتوثيق هذه التبعيات وعلى مستخدم المكون لضمان تلبية هذه التبعيات.