Sådan skrives Cordova-plugins

Cordova-plugins er en af ​​de mørke kunstarter inden for hybrid-appudvikling, hvilket hjælper webapps, der kører med nativ adgang til enhedens fulde magt nedenunder. Deres uklarhed adskiller haves fra have nots, med hele skår af Cordova-brugere, der er afhængige af en relativt lille gruppe af plugin-udviklere til at opbygge og vedligeholde disse vigtige stykker funktionalitet til deres apps (som den berømte Eddy Verbruggen).

Det behøver ikke være sådan. Flere Cordova-udviklere kan og bør vove sig med at udvikle Cordova-plugin-udviklingen, fordi det ikke er så svært, som det er slået op for at være, og økosystemet har brug for flere mennesker til at træde ind og hjælpe med.

Hos Ionic har vi identificeret Cordova-plugin-økosystemet som en af ​​de vigtigste og mest udsatte dele af Cordova-oplevelsen, og vi arbejder hårdt for at ændre det gennem uddannelse, vedligeholdelse af eksisterende plugins og opbygning af nye plugins, der udvider muligheder og funktioner i Cordova out-of-the-box.

Lad os starte ved firkant et og gå gennem processen med at blive en erfaren Cordova plugin-udvikler. Jeg tror, ​​du finder ud af, at det er meget mindre skræmmende, end det ser ud til!

0. Hvad er et Cordova-plugin?

Før vi begynder at opbygge vores første Cordova-plugin, lad os tage et skridt tilbage og tale om, hvad et Cordova-plugin er, og i forlængelse heraf er Cordova.

Cordova er et sæt kommandolinjeværktøjer og en plugin-bro til opbygning af indbyggede apps til app-butikker, der giver os mulighed for at opbygge vores app i en webvisning og ringe til oprindelig kode fra JavaScript. Når vi installerer Cordova på vores computer, installerer vi et sæt værktøjer, der hjælper med at pakke dette webindhold, placere det i en indbygget appbeholder, distribuere den til en enhed eller simulator til test og opbygge binære filer til endelig frigivelse til app butik.

Inde i denne beholder er en relativt lille bro, der transporterer visse JavaScript-opkald, vi foretager til tilsvarende indbygget kode for at give vores app mulighed for at gøre komplekse, indfødte ting, som ikke bages i standard Web API'er.

At opbygge Cordova-plugins betyder, at vi skriver noget JavaScript for at nedkalde til nogle Native (Obj-c / Swift, Java osv.) -Koder, vi også skriver, og returnerer resultatet til vores JavaScript.

For at opsummere det: vi bygger et Cordova-plugin, når vi vil gøre noget indfødt, som endnu ikke har en Web API-analog, som adgang til HealthKit-data på iOS eller ved hjælp af Fingerprint-scanneren på Android.

1. Kom godt i gang: stillads vores første plugin

Plugins plugins overalt, men hvordan starter vi vores egne? Der er to måder at gøre dette på: vi kan bruge plugman-værktøjet til at oprette et hurtigt, eller vi kan få al mitose på et eksisterende plugin ved at klone det.

Generelt foretrækker jeg at klone eksisterende plugins, fordi du får en hurtigere start med kode udfyldt til alle de platforme, du ønsker. Jeg har klonet Cordova Device-pluginet, da det er temmelig enkelt, men for nylig har vi frigivet en Cordova Plugin-skabelon, der kommer temmelig bare knogler. Lad os klone skabelonen.

Vi ser et par filer og mapper her, men vigtigst af alt: plugin.xml, src og www:

plugin.xml er en af ​​de vigtigste filer her. Det er, hvad Cordova analyserer for at finde ud af, hvilke platforme dit plugin understøtter, præferencer, det har, som brugeren kan konfigurere, kildefiler, vi vil medtage i vores endelige app build, og mere. Det er også en smule esoterisk, så vi generelt ser på andre plugin.xml-filer og bruger vores Computer Science-baggrund til at kopiere og indsætte i vores.

Næste er src. Det er her vores oprindelige kode bor. Hvis vi kigger ind her, ser vi en ios- og Android-mappe.

Endelig er www, hvor JavaScript-koden til vores plugin bor. Det er dette, der først kaldes op og derefter sparkes i gang fra Cordova for at kalde vores oprindelige kode.

Lad os gå videre og kopiere alle filer og mapper fra den skabelon, vi klonede til et nyt bibliotek, hvor vi skal arbejde på vores plugin. Til denne tutorial opretter vi et simpelt "echo" -plugin, så vi kan oprette et echo-plugin-bibliotek.

2. Konfiguration af vores plugin

Nu til min yndlingsdel: at skrive XML !!! 1

Okay, det er ikke glamorøst, men plugin.xml-filen er, hvor alt sker, og det er her, vi skal starte. Først skal vi give vores plugin et unikt navn og id. For så vidt angår navnekonventioner, er id'et normalt i formen denne-er-en-en-plugin, som cordova-plugin-enhed (som et eksempel):

Dernæst sætter vi en henvisning til vores JavaScript-kode:

Kort overblik specificerer js-module den JS-kode, der skal køres, og indstiller hvilket vinduesvariabel plugin skal eksporteres under. Så i dette tilfælde er vores script-fil www / plugin.js, og når vores app kører, kan vi få adgang til plugin ved windows.MyCordovaPlugin.

Dernæst specificerer vi de platforme, vi skal understøtte, sammen med henvisninger til den tilsvarende native kode for hver, startende med Android:

Inde i specificerer vi vores Android-pakkenavn og også symbolet, som Cordova vil bruge til at identificere vores plugin, i dette tilfælde er det MyCordovaPlugin. Endelig har vi en henvisning til vores vigtigste Java-kode inde i , hvor vores oprindelige kode bor.

Lad os se på ios:

I dette uddrag ser vi meget af det samme fra Android. Inde i har vi en lignende indgang til Android bare uden Java-pakkeformat. Endelig lister vi kildefilerne, som Cordova vil kopiere til vores app, før de bygger, og sørger for at specificere både header- og kildefiler, vi vil inkludere. Bemærk: plugins kan bygges i Swift, men i betragtning af at Cordova stadig er i Objekt-C og der er lidt overhead til at bruge Swift, vil vi fokusere på Objekt-c lige nu.

3. Opbygning af vores plugin: JavaScript

Lad os starte med JavaScript API, som vi gerne vil udsætte for udvikleren. I dette tilfælde lever vores JavaScript-kode på www / plugin.js. Sådan ser det ud:

I dette tilfælde har vi et simpelt objekt, der har ekko og getDate som funktioner, som udvikleren kan kalde. Når det køres, kan udvikleren kalde dette plugin ved at skrive

window.MyCordovaPlugin.echo ('Hej!', funktion () {// callback})

Koden, der udfører magien her, er exec-funktionen, vi har importeret fra cordova / exec. Når det kaldes, fortæller dette plugin Cordovas plugin-lag at finde det plugin, der er identificeret af PLUGIN_NAME, og sende handlingen, der er videregivet til enten et funktionsopkald (iOS) eller en skiftefunktion (Android). Det er en god praksis at sikre, at Cordova-symbolnavnet, vi giver vores plugin (i dette tilfælde MyCordovaPlugin) matcher -indstillingen fra vores plugin.xml, da det vil være den vinduesvariabel, vi får adgang til.

For mange plugins er dette så komplekst, som de bliver nødt til at komme på JavaScript-siden, da den oprindelige kode gør alt det arbejde. Jeg beder dog fremtidige Cordova-pluginudviklere om kraftigt at overveje at gøre mere af det faktiske grynt arbejde i JavaScript i stedet for indfødt kode. Undgå for eksempel ting som strengbearbejdning, JSON-kodning osv. I indfødt kode, fordi du har en mere platformspecifik kode til at vedligeholde, og ofte udfører JavaScript disse opgaver med meget mindre mental overhead for udvikleren (læs: strengbehandling i Objektiv-C er pinefuld som hele helvede). Her er en af ​​vores plugins, der fungerer meget på tværs af platforme i JavaScript-laget, kun ved at bruge det indfødte lag til at få data, som JS-laget ikke kan.

4. Opbygning af vores plugin: Native iOS

Nu til den sjove del: at skrive en oprindelig iOS Objekt-C-kode.

Lad os starte med objektiv-C header-filen i src / ios / MyCordovaPlugin.h:

Denne overskriftsfil er en specifikation af de funktioner, vi vil implementere i vores tilsvarende .m, MyCordovaPlugin.m:

Disse metoder kaldes via Cordova, når vi kører exec () fra vores JavaScript. De tager et CDVInvokedUrlCommand * -argument, der indeholder de argumenter, vi sendte fra JS, sammen med en henvisning til det tilbagekald, som brugeren har givet. Vi kan konfigurere tilbagekaldet til kun at arbejde en gang eller til at blive kaldt gentagne gange (ved at bruge [result setKeepCallbackAsBool]).

En gang i denne metode laver vi almindelig mål 'C. Alt hvad du kan drømme om at gøre nativt kan du gøre her. Når du er færdig og vil returnere data til JS, skal du oprette et CDVPluginResult-objekt og sende det til kommandoen Delate, der sender resultatet tilbage til JS.

I eksemplet ovenfor opkalder ekkometoden NSLog for at ekko den streng, som brugeren sender, mens getDate får en oprindelig dato fra iOS og derefter konverterer den til en ISO-streng og returnerer den.

Dette er på ingen måde en udtømmende introduktion til opbygning af iOS Cordova-plugins. Den bedste måde at gå herfra til at bygge komplekse plugins er at studere eksisterende, som f.eks. Geolocation-plugin.

5. Opbygning af vores Android-plugin

Opbygning af Android-delen af ​​vores plugin er nøjagtigt den samme konceptuelt, men Android-plugins har lidt anderledes semantik. Sådan ser vores src / android / com / eksempel / MyCordovaPlugin.java ud:

For Android har vi en enkelt udførelsesmetode, som Cordova kalder med den handling, vi udfører () på JS-siden, sammen med argumenter og tilbagekaldssammenhæng. I stedet for at få Cordova til at kalde vores metode direkte, er vi nødt til at kontrollere handlingsstrengen mod hvert aktionsnavn, vi understøtter, i dette tilfælde "ekko" og "getDate". Derefter udfører vi handlingen og returnerer resultatet ligesom på iOS Side.

Igen for at se et mere komplekst Android-plugin skal du tage et kig på Geolocation-plugin-kilden.

6. Test af plugins

At smadre vores tastatur og producere kode er den lette del. Nu skal vi teste og verificere, at vores plugin faktisk fungerer.

For at teste et Cordova-plugin skal vi have en Cordova / PhoneGap / Ionic-app til at køre. Cordova-plugins kan ikke køres alene.

Hvis vi antager, at vi har en eksisterende Cordova-app, kan vi tilføje vores plugin lokalt:

cordova plugin tilføj - link ~ / git / echo-plugin

Linkflaget tilføjer vores plugin som et symbolsk link, hvilket betyder, at vi kan arbejde på vores kode (i det mindste den oprindelige kode) og genopbygge og køre vores app uden at skulle tilføje plugin igen. Af en eller anden grund opdateres JavaScript-siden af ​​vores plugin ikke automatisk. Når vi bygger og ændrer JS-siden, er vi nødt til at fjerne plugin hurtigt ved hjælp af cordova rm my-cordova-plugin og tilføje det tilbage, som vi gjorde før.

For at teste plugin kører vi bare vores app som normalt ved hjælp af vores standard Cordova debugging teknikker (vedhæft browser-dev-værktøjer, brug IDE-konsol osv.).

Hvis noget nogensinde bliver vanvittigt eller synkroniseret, skal du bare prøve at fjerne pluginet og tilføje det tilbage. Hvis det ikke fungerer, skal du fjerne din platformkatalog og sørge for, at alle referencer til dit plugin er væk fra plugins-biblioteket. Dette har en tendens til at ske, hvis du ændrer ting som plugin-id eller navn.

7. Hvor skal man hen herfra

Dette indlæg var beregnet til at skabe det grundlæggende ved opbygning af et plugin. Dag til dag er der ikke meget mere ud over, hvad jeg har skrevet her, bortset fra meget mere indfødt kode til at gøre hvad som helst smarte ting vi prøver at gøre.

Hvis du gerne vil grave dig ind fra en lidt mere praktisk vinkel, har jeg sammensat en Cordova Plugin Development Guide, der løber gennem opbygning af plugin ovenfor og de kommandoer, du vil bruge til at føje det til dit projekt og teste det sammen med nogle avancerede emner mod slutningen.

Hver gang jeg bygger et Cordova-plugin, er jeg altid forbløffet over, hvor ligetil det er. Af en eller anden grund virkede det altid som et utroligt utilgængeligt emne fuld af udokumenteret magi, som kun et par mennesker kendte. Det er slet ikke tilfældet, og jeg håber, at dette indlæg opfordrer flere mennesker til at prøve at opbygge deres egne plugins eller forbedre dem, der allerede findes derude.

God hacking!