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