Как да напиша Cordova Plugins

Cordova Plugins са едно от тъмните изкуства на развитието на хибридни приложения, помагащи на уеб приложенията, работещи с оригинален достъп до пълната мощност на устройството отдолу. Тяхната неизвестност разделя хесове от haves, като цели слоеве потребители на Cordova разчитат на сравнително малка група разработчици на плъгини, за да създадат и поддържат тези важни части от функционалността на своите приложения (като известния Еди Вербруген).

Не е нужно да е така. Повече разработчици на Cordova могат и трябва да се впуснат в разработката на плъгини на Cordova, защото това не е толкова трудно, колкото е пропукано, а екосистемата има нужда от повече хора, за да се намеси и да им помогне.

В Ionic идентифицирахме екосистемата на плъгини Кордова като една от най-важните и рискови части от опита на Кордова и работим усилено, за да променим това чрез образование, поддържане на съществуващи приставки и изграждане на нови приставки, които разширяват възможности и функции на Cordova out of the box.

Нека започнем с квадрат 1 и да преминем през процеса на превръщането в опитен разработчик на плъгини на Cordova. Мисля, че ще откриете, че е много по-малко плашещо, отколкото изглежда!

0. Какво е приставка за Кордова?

Преди да започнем да изграждаме първата си приставка за Кордова, нека направим крачка назад и да поговорим за това, което е приставката на Cordova, и, като допълнение, Кордова.

Кордова е набор от инструменти за командния ред и плъгин мост за изграждане на собствени приложения за магазините за приложения, който ни позволява да изграждаме нашето приложение в уеб изглед и да извикваме родния код от JavaScript. Когато инсталираме Cordova на нашия компютър, ние инсталираме набор от инструменти, които помагат да пакетирате това уеб съдържание, да го поставите в естествен контейнер за приложения, да го разгърнете на устройство или симулатор за тестване и да изградим двоични файлове за окончателно пускане към магазин за приложения.

Вътре в този контейнер е сравнително малък мост, който пренася определени JavaScript обаждания, които правим в съответния естествен код, за да дадем на приложението ни възможност да прави сложни, местни неща, които не са изпечени в стандартните уеб API.

Изграждането на Cordova плъгини означава, че пишем някакъв JavaScript, за да извикаме до някакъв Native (Obj-c / Swift, Java и т.н.) код, който също пишем, и връщаме резултата в нашия JavaScript.

В обобщение: създаваме Cordova плъгин, когато искаме да направим нещо, което все още няма аналог на Web API, като например достъп до данни на HealthKit в iOS или използване на скенера за пръстови отпечатъци на Android.

1. Първи стъпки: скеле на нашия първи плъгин

Плъгини плъгини навсякъде, но как да започнем нашите собствени? Има два начина да направите това: можем да използваме инструмента за добавяне, за да създадем бързо, или можем да получим цялата митоза на съществуващ плъгин, като го клонираме.

По принцип предпочитам да клонирам съществуващите плъгини, защото вие получавате по-бърз старт с попълнен код за всички платформи, които искате. Клонирах приставката за устройство на Cordova, тъй като е доста проста, но наскоро пуснахме шаблон за приставката на Cordova, който идва с голи кости. Нека git клонира шаблона.

Тук виждаме няколко файла и директории, но най-важното: plugin.xml, src и www:

plugin.xml е един от най-важните файлове тук. Това е, което Кордова анализира, за да разбере какви платформи поддържа вашият плъгин, предпочитанията, които потребителят може да конфигурира, изходните файлове, които ще включим в окончателната си версия на приложението и други. Освен това е малко езотерично, така че най-общо ще разгледаме други plugin.xml файлове и ще използваме нашия компютър Computer Science, за да копираме и поставим в нашия.

Следва src. Тук живее родният ни код. Ако надникнем тук, виждаме папка ios и android.

И накрая, www е мястото, където живее JavaScript кодът на нашия плъгин. Това се обажда първо и след това започва Кордова, за да се обади на родния ни код.

Нека продължим да копираме всички файлове и директории от шаблона, който клонирахме, в нова директория, където ще работим върху нашия плъгин. За този урок ще създаваме прост плъгин за „ехо“, така че можем да създадем директория за ехо-приставки.

2. Конфигуриране на нашия Plugin

Сега за любимата ми част: писане на XML !!! 1

Добре, не е бляскаво, но файлът plugin.xml е мястото, където всичко се случва и е мястото, където трябва да започнем. Първо, трябва да дадем на нашия плъгин уникално име и идентификатор. Що се отнася до конвенциите за именуване, id обикновено е във формата this-is-a-plugin, като cordova-plugin-device (като пример):

След това ще зададем препратка към нашия JavaScript код:

С един поглед js-модулът указва JS кода, който ще се изпълнява, и задава под каква променлива на прозореца ще бъде експортиран приставката. Така че в този случай нашият скриптов файл е www / plugin.js и когато приложението ни стартира, ще имаме достъп до плъгина в window.MyCordovaPlugin.

След това посочваме платформите, които ще поддържаме, заедно с препратките към съответния естествен код за всеки, като се започне с Android:

Вътре в ние указваме името на нашия пакет за Android, а също и символът, който Кордова ще използва за идентифициране на нашия плъгин, в случая това е MyCordovaPlugin. И накрая, имаме препратка към основния ни Java код вътре в , където живее нашият роден код.

Нека да разгледаме ios:

В този фрагмент виждаме голяма част от същите неща от Android. Вътре в имаме подобен запис на Android, само без пакета на Java формат. Накрая изброяваме изходните файлове, които Кордова ще копира в нашето приложение преди изграждането, като не забравяйте да посочите както заглавни, така и изходни файлове, които ще включим. Забележка: Плъгините могат да бъдат изградени в Swift, но имайки предвид, че Кордова все още е в Objective-C и има малко прекомерно използване на Swift, засега ще се съсредоточим върху Objective-c.

3. Изграждане на нашия плъгин: JavaScript

Нека започнем с JavaScript API, който бихме искали да изложим на програмиста. В този случай нашият JavaScript код живее във www / plugin.js. Ето как изглежда:

В този случай имаме прост обект, който има ехо и getDate като функции, които програмистът може да извика. Когато стартирате, програмистът може да извика този плъгин чрез писане

window.MyCordovaPlugin.echo („Здравейте!“, функция () {// callback})

Кодът, който прави магията тук, е функцията exec, която сме импортирали от cordova / exec. Когато се извиква, тази приставка казва на слоя на приставката на Кордова да намери приставката, идентифицирана от PLUGIN_NAME, и да изпрати действието, предавано или във функционално обаждане (iOS), или в функция за превключване (android). Добра практика е да се уверим, че името на символа Cordova, на което даваме своя плъгин (в този случай MyCordovaPlugin), съвпада с настройката от нашия plugin.xml, тъй като това ще бъде променливата на прозореца, до която имаме достъп.

За много плъгини това е толкова сложно, колкото ще трябва да попаднат от страна на JavaScript, тъй като родният код върши цялата работа. Въпреки това, препоръчвам на бъдещите разработчици на плъгини на Cordova силно да обмислят да направят повече от действителната грунтова работа в JavaScript, вместо кода Native. Например, избягвайте неща като String обработка, кодиране JSON и др. В Native код, защото ще имате повече специфичен за платформата код и често JavaScript изпълнява тези задачи с много по-малко умствени разходи за разработчика (прочетете: обработка на струни в Objective-C е агонизиращ като всички ада). Ето един от нашите плъгини, който върши много кросплатформена работа в JavaScript слоя, използвайки само Native слой за получаване на данни, който JS слой не може.

4. Изграждане на нашия плъгин: Native iOS

Сега за забавната част: писане на някакъв нативен iOS Objective-C код.

Да започнем с заглавния файл на Objective-C, в src / ios / MyCordovaPlugin.h:

Този заглавен файл е спецификация на функциите, които ще внедрим в съответния .m, MyCordovaPlugin.m:

Тези методи се извикват чрез Кордова, когато стартираме exec () от нашия JavaScript. Те вземат CDVInvokedUrlCommand * аргумент, който съдържа аргументите, които предадохме от JS, заедно с препратка към обратния разговор, който потребителят е преминал. Можем да конфигурираме обратния разговор да работи само веднъж или да бъде извикван многократно (използвайки [резултат setKeepCallbackAsBool]).

След като използваме този метод, ние правим обикновен ol 'Objective-C. Всичко, което можете да мечтаете да направите местно, можете да направите тук. Когато сте готови и искате да върнете данните обратно в JS, създайте CDVPluginResult обект и го изпратете до commandDelegate, който изпраща резултата обратно в JS.

В горния пример методът echo просто призовава NSLog да ехо на низа, който потребителят преминава, докато getDate получава начална дата от iOS и след това го преобразува в ISO низ и го връща.

Това в никакъв случай не е изчерпателно въведение в изграждането на iOS Cordova плъгини. Най-добрият начин да преминете от тук към изграждането на сложни приставки е да изучавате съществуващите, като приставката Geolocation.

5. Изграждане на нашия Android плъгин

Изграждането на Android част от нашия плъгин е абсолютно същото концептуално, но плъгините за Android имат малко по-различна семантика. Ето как изглежда нашия src / android / com / пример / MyCordovaPlugin.java:

За Android имаме един единствен метод на изпълнение, който Кордова извиква с действието, което поставяме в exec () от страна на JS, заедно с контекста на аргументите и обратния разговор. По този начин, вместо да накараме Cordova да извика директно нашия метод, трябва да проверим низът за действие спрямо всяко име на действие, което поддържаме, в случая „ехо“ и „getDate“. След това изпълняваме действието и връщаме резултата точно както на iOS Side.

Отново, за да видите по-сложен плъгин за Android, разгледайте източника на плъгини Geolocation.

6. Тестване на приставки

Разбиването на клавиатурата и създаването на код е лесната част. Сега трябва да тестваме и да проверим, че плъгинът действително работи.

За да тестваме плъгин Cordova, трябва да имаме приложение Cordova / PhoneGap / Ionic, което да работи. Кордовите плъгини не могат да се изпълняват сами.

Ако приемем, че имаме съществуващо приложение Кордова, можем да добавим нашия плъгин локално:

кордова добавка добавете --link ~ / git / echo-плъгин

Флагът на връзката добавя нашия плъгин като символна връзка, което означава, че можем да работим върху кода си (поне на родния код) и да възстановим и стартираме нашето приложение, без да се налага отново да добавяме приставката. По някаква причина обаче, страната на JavaScript на нашия плъгин не се актуализира автоматично. Докато изграждаме и модифицираме страницата на JS, трябва бързо да премахнем приставката с помощта на cordova rm my-cordova-plugin и да я добавим обратно, както преди.

За да тестваме приставката, ние просто стартираме нашето приложение като нормално, използвайки нашите стандартни техники за отстраняване на грешки в Cordova (прикрепете инструменти за разработка на браузъра, използвайте IDE конзола и т.н.).

Ако нещо някога стане неудобно или не се синхронизира, просто опитайте да премахнете приставката и да я добавите обратно. Ако това не работи, премахнете вашата директория на платформата и се уверете, че всички препратки към вашия плъгин са изчезнали от директорията с приставки. Това може да се случи, ако промените неща като идентификатор или име на приставката.

7. Къде да отида от тук

Тази публикация имаше за цел да изложи основите на изграждането на плъгин. Ежедневно няма много повече от това, което съм писал тук, освен много повече местен код, за да направим каквото и да е фантастично нещо, което се опитваме да правим.

Ако искате да копаете малко от малко по-практичен ъгъл, съставих Ръководство за разработка на плъгини на Cordova, което преминава през изграждането на приставката по-горе и командите, които ще използвате, за да го добавите към вашия проект и да го тествате , заедно с някои напреднали теми към края.

Винаги когато създавам плъгин на Cordova, винаги се удивлявам колко е прав. По някаква причина, това винаги изглеждаше като невероятно недостъпна тема, пълна с недокументирана магия, която само няколко души знаеха. Това изобщо не е така и се надявам, че тази публикация насърчава повече хора да опитат да създадат свои собствени приставки или да подобрят тези, които вече съществуват там.

Честито хакване!