Обзор
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. });
Ждём готовности библиотеки
Фрагмент API внедрения загружает библиотеку и все ее зависимости асинхронно. Это означает, что такие методы, как createComponent
не будут доступны сразу, и код, вызывающий такие методы, должен быть отложен до тех пор, пока все не будет загружено.
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 обычно упаковываются в виде отдельных файлов JavaScript, которые вы можете включить на свою страницу с помощью тега <script>
.
Порядок загрузки имеет значение, поэтому важно сначала включить фрагмент 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 . Автор компонента должен документировать эти зависимости, а пользователь компонента должен гарантировать соблюдение этих зависимостей.