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

نظرة عامة

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

إنشاء مكوّن مخصّص

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

لمعالجة هذه المشكلة، عند إنشاء مكوّنات واجهة برمجة تطبيقات تضمين تضمين جديدة، ستعمل هذه الأجهزة على البحث تلقائيًا عن توفُّر طريقة تُسمى 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 لن تكون متاحة على الفور، ويجب تأجيل الرمز الذي يستدعي هذه الطرق إلى أن يتم تحميل كل البيانات.

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