Jak napsat Cordova Pluginy

Pluginy Cordova jsou jedním z temných umění vývoje hybridních aplikací, které pomáhají webovým aplikacím běžícím nativně přistupovat k plnému výkonu zařízení pod nimi. Jejich nejasnost odděluje hávy od těch, které nemají, s celou řadou uživatelů Cordova, kteří se spoléhají na relativně malou skupinu vývojářů pluginů, aby mohli vytvářet a udržovat tyto klíčové funkce pro své aplikace (jako je slavný Eddy Verbruggen).

Nemusí to tak být. Více vývojářů Cordova se může a mělo by se pustit do vývoje doplňků Cordova, protože to není tak těžké, jak je rozbité a ekosystém potřebuje více lidí, aby vstoupili a pomohli ven.

V Ionic jsme identifikovali ekosystém pluginů Cordova jako jednu z nejdůležitějších a nejohroženějších částí Cordova zážitku a usilovně pracujeme na jeho změně prostřednictvím vzdělávání, udržováním stávajících pluginů a vytvářením nových pluginů, které rozšiřují možnosti a funkce Cordova již po vybalení.

Začněme na prvním místě a projdeme se procesem vývoje zkušeného vývojáře Cordova pluginů. Myslím, že zjistíte, že je to mnohem méně zastrašující, než se zdá!

0. Co je plugin Cordova?

Než se pustíme do budování našeho prvního Cordova pluginu, vraťme se o krok zpět a povídáme si o tom, co je Cordova plugin, a tedy o Cordovu.

Cordova je sada nástrojů příkazového řádku a pluginového mostu pro vytváření nativních aplikací pro obchody s aplikacemi, což nám umožňuje sestavovat naši aplikaci ve webovém zobrazení a volat nativní kód z JavaScriptu. Když nainstalujeme Cordova do našeho počítače, instalujeme sadu nástrojů, které pomáhají sbalit tento webový obsah, umístit jej do nativního kontejneru aplikace, nasadit jej do zařízení nebo simulátoru pro testování a sestavit binární soubory pro konečné vydání do obchod s aplikacemi.

Uvnitř tohoto kontejneru je relativně malý most, který přenáší určitá volání JavaScriptu, která provádíme, do odpovídajícího nativního kódu, což dává naší aplikaci možnost dělat složité, nativní věci, které nejsou upečeny do standardních webových rozhraní API.

Vytváření zásuvných modulů Cordova znamená, že píšeme nějaký JavaScript, který zavoláme na nějaký nativní (Obj-c / Swift, Java atd.) Kód, který také píšeme, a vracíme výsledek našemu JavaScript.

Abychom to shrnuli: stavíme plugin Cordova, když chceme udělat něco nativně, které zatím nemá analog Web API, jako je přístup k údajům HealthKit v systému iOS nebo používání skeneru otisků prstů v systému Android.

1. Začínáme: lešení našeho prvního pluginu

Pluginy pluginy všude, ale jak můžeme začít s našimi vlastními? Existují dva způsoby, jak to udělat: můžeme použít nástroj plugman k jeho rychlému vytvoření nebo klonováním jej můžeme získat všechny mitózy na existujícím pluginu.

Obecně dávám přednost klonování existujících pluginů, protože získáte rychlejší start s kódem vyplněným pro všechny platformy, které chcete. Klonovaný modul Cordova Device jsem naklonil jako poměrně jednoduchý, ale nedávno jsme vydali šablonu Cordova Plugin Template, která přichází docela holé kosti. Pojďme klonovat šablonu.

Zde vidíme několik souborů a adresářů, ale hlavně: plugin.xml, src a www:

plugin.xml je jedním z nejdůležitějších souborů zde. Cordova analyzuje, aby zjistila, jaké platformy váš plugin podporuje, jaké má preference, které může uživatel konfigurovat, zdrojové soubory, které zahrneme do naší konečné aplikace, a další. Je to také trochu esoterické, takže se obecně podíváme na další soubory plugin.xml a zkopírujeme je a vložíme do naší počítačové vědy.

Další je src. Zde žije náš rodný kód. Pokud se podíváme sem, uvidíme složku ios a android.

Konečně, www je místo, kde žije kód JavaScript pro náš plugin. To je to, čemu se říká první, a pak odstartuje Cordovu, aby zavolala na náš rodný kód.

Pojďme zkopírovat všechny soubory a adresáře ze šablony, kterou jsme naklonovali, do nového adresáře, kde budeme pracovat na našem pluginu. Pro tento tutoriál vytvoříme jednoduchý „echo“ plugin, takže můžeme vytvořit adresář echo-pluginů.

2. Konfigurace našeho pluginu

Nyní k mé oblíbené části: psaní XML !!! 1

Dobře, není to okouzlující, ale soubor plugin.xml je místem, kde se všechno děje, a tam bychom měli začít. Nejprve musíme dát našemu pluginu jedinečné jméno a id. Pokud jde o konvence pojmenování, id je obvykle ve tvaru this-is-a-plugin, jako například Cordova-plugin-device (jako příklad):

Dále nastavíme odkaz na náš kód JavaScript:

Stručný přehled js-module určuje JS kód, který se bude spouštět, a nastavuje, jakou proměnnou okna bude plugin exportován. V tomto případě je tedy náš skriptový soubor www / plugin.js a když se naše aplikace spustí, budeme mít přístup k pluginu v okně.MyCordovaPlugin.

Dále určíme platformy, které budeme podporovat, spolu s odkazy na odpovídající nativní kód pro každou, počínaje Androidem:

V rámci určíme název našeho balíčku pro Android a také symbol Cordova použije k identifikaci našeho pluginu, v tomto případě je to MyCordovaPlugin. Nakonec máme odkaz na náš hlavní kód Java uvnitř , kde žije náš nativní kód.

Pojďme se podívat na ios:

V tomto úryvku vidíme mnoho stejných věcí z Androidu. Uvnitř máme podobný záznam jako Android bez formátu Java balíčku. Nakonec vyjmenujeme zdrojové soubory, které Cordova zkopíruje do naší aplikace před sestavením, a nezapomeňte zadat záhlaví i zdrojové soubory, které zahrneme. Poznámka: pluginy lze zabudovat do Swift, ale vzhledem k tomu, že Cordova je stále v Objective-C a použití Swift je trochu nadměrné, nyní se zaměříme na Objective-c.

3. Vytvoření našeho pluginu: JavaScript

Začněme s rozhraním JavaScript API, které bychom chtěli vystavit vývojáři. V tomto případě náš kód JavaScript žije na adrese www / plugin.js. Vypadá to takto:

V tomto případě máme jednoduchý objekt, který má echo a getDate jako funkce, které může vývojář volat. Při spuštění může vývojář volat tento plugin písemně

window.MyCordovaPlugin.echo ('Ahoj!', function () {// callback})

Kód, který zde kouzlo, je vykonávací funkcí, kterou jsme importovali z Cordova / Exec. Když se tento plugin zavolá, řekne Cordovině vrstvě pluginů, aby našel plugin identifikovaný PLUGIN_NAME a odešle akci předanou buď na volání funkce (iOS) nebo přepínací funkci (android). Je dobré zajistit, aby název symbolu Cordova, který přidáme našemu pluginu (v tomto případě MyCordovaPlugin), odpovídal nastavení z našeho pluginu.xml, protože to bude proměnná okna, ke které přistupujeme.

Pro mnoho pluginů je to tak složité, jak se musí dostat na stranu JavaScriptu, protože nativní kód vykonává veškerou práci. Vyzývám však budoucí vývojáře zásuvných modulů Cordova, aby důrazně uvažovali o tom, že by místo skutečného kódu udělali více ze skutečné práce s gruntem v JavaScriptu. Například v nativním kódu se nemusíte vyhýbat například zpracování řetězců, kódování JSON atd., Protože byste si měli udržovat více kódu pro konkrétní platformu a JavaScript často tyto úkoly provádí s mnohem méně mentální režií pro vývojáře (čtení: zpracování řetězců v Objective-C je agonizující jako celé peklo). Zde je jeden z našich pluginů, který ve vrstvě JavaScriptu funguje hodně napříč platformami. K získání dat, která vrstva JS nemůže použít, používá pouze vrstvu Native.

4. Vytvoření našeho pluginu: Nativní iOS

Nyní pro zábavnou část: psaní nějakého nativního kódu iOS Objective-C.

Začněme souborem záhlaví Objective-C, v src / ios / MyCordovaPlugin.h:

Tento soubor záhlaví je specifikace funkcí, které implementujeme v našem odpovídajícím .m, MyCordovaPlugin.m:

Tyto metody se nazývají Cordova, když spustíme exec () z našeho JavaScriptu. Berou argument CDVInvokedUrlCommand *, který obsahuje argumenty, které jsme předali od JS, spolu s odkazem na zpětné volání, které uživatel předal. Můžeme nakonfigurovat zpětné volání tak, aby fungovalo pouze jednou, nebo aby bylo voláno opakovaně (pomocí [result setKeepCallbackAsBool]).

Jakmile v této metodě děláme holý objekt Objective-C. Cokoli, o čem si můžete snít o nativním dělání, můžete udělat zde. Až budete hotovi a budete chtít vrátit data zpět do JS, vytvořte objekt CDVPluginResult a odešlete jej na příkazDelegate, který odešle výsledek zpět do JS.

Ve výše uvedeném příkladu metoda echo pouze volá NSLog, aby odešla řetězec, který uživatel prochází, zatímco getDate získá nativní datum z iOS a poté jej převede na řetězec ISO a vrátí jej.

V žádném případě to není vyčerpávající úvod do vytváření modulů pro iOS Cordova. Nejlepší způsob, jak se odtud dostat k vytváření komplexních pluginů, je studovat stávající, jako je plugin Geolocation.

5. Vytvoření našeho pluginu pro Android

Budování části našeho pluginu pro Android je z koncepčního hlediska úplně stejné, ale pluginy pro Android mají trochu odlišnou sémantiku. Jak vypadá náš src / android / com / example / MyCordovaPlugin.java:

Pro Android máme jednu metodu execute, kterou Cordova volá s akcí, kterou vložíme do exec () na straně JS, spolu s argumenty a kontextem zpětného volání. Namísto toho, aby Cordova zavolala na naši metodu přímo, musíme zkontrolovat řetězec akce u každého názvu akce, které podporujeme, v tomto případě „echo“ a „getDate“. Poté provedeme akci a výsledek vrátíme stejně jako na straně iOS.

Chcete-li zobrazit složitější plugin pro Android, podívejte se znovu na zdroj pluginu Geolocation.

6. Testování pluginů

Rozbití naší klávesnice a výroba kódu je snadná část. Nyní musíme otestovat a ověřit, zda náš plugin skutečně funguje.

Chcete-li vyzkoušet plugin Cordova, potřebujeme, aby byla spuštěna aplikace Cordova / PhoneGap / Ionic. Pluginy Cordova nelze spustit samostatně.

Za předpokladu, že máme existující aplikaci Cordova, můžeme přidat plugin místně:

add plugin pro Cordova - link ~ / git / echo-plugin

Příznak odkazu přidá náš plugin jako symbolický odkaz, což znamená, že můžeme pracovat na našem kódu (přinejmenším nativním kódu) a znovu sestavit a spustit naši aplikaci, aniž bychom museli plugin přidávat znovu. Z nějakého důvodu se však stránka JavaScript našeho pluginu automaticky neaktualizuje. Když vytváříme a upravujeme stranu JS, musíme plugin rychle odebrat pomocí Cordova rm my-cordova-plugin a přidat jej zpět jako předtím.

Pro vyzkoušení pluginu spustíme naši aplikaci jako obvykle pomocí našich standardních technik ladění Cordova (připojte nástroje prohlížeče dev, použijte konzolu IDE atd.).

Pokud se něco stane zvráceným nebo synchronizovaným, zkuste plugin odebrat a přidat zpět. Pokud to nefunguje, odeberte adresář vaší platformy a ujistěte se, že všechny odkazy na váš plugin jsou odstraněny z adresáře pluginů. K tomu obvykle dochází, pokud změníte například ID nebo název pluginu.

7. Kam dál?

Účelem tohoto příspěvku bylo stanovit základní zásady vytváření zásuvného modulu. Každodenně není o nic víc než to, co jsem zde napsal, kromě mnohem více nativního kódu, který umožňuje dělat jakoukoli fantastickou věc, kterou se snažíme dělat.

Pokud byste se chtěli kopat trochu z trochu praktičtějšího úhlu, sestavil jsem Cordova Plugin Development Guide, který prochází vytvořením pluginu výše a příkazy, které použijete pro jeho přidání do projektu a jeho otestování , spolu s některými pokročilými tématy ke konci.

Kdykoli budu stavět plugin Cordova, vždycky jsem ohromen tím, jak je to jednoduché. Z nějakého důvodu to vždy vypadalo jako neuvěřitelně nepřístupné téma plné nezdokumentované magie, které vědělo jen málokdo. To v žádném případě není a já doufám, že tento příspěvek povzbudí více lidí, aby se pokusili sestavit své vlastní doplňky nebo vylepšit ty, které již existují.

Šťastný hacking!