Wéi eng Workflow fir Polymer mat Angular z'integréieren?


Polymer. Seng Verspriechen d'Entwécklung vun UI Komponentebibliothéiken z'erméiglechen ouni an engem technesche Stack gespaart ze ginn, op déi (zukünfteg) Fäegkeeten vum Browser vertrauen. Schreift einfach seng Komponenten a benotzt se iwwerall mat der Garantie fir keng Nebenwirkungen ze generéieren. Et ass wënschenswäert, nee? Wann Dir mat verschiddene Webtechnologien schafft an e Katalog vu generesche UI Komponenten wëllt entwéckelen, kann Polymer wéi eng gutt Léisung schéngen.
Mir wäerten zesumme gesinn wéi een e Komponente geschriwwe mat Polymer 2.0 an enger Angular Applikatioun integréiert.

Preambel: Polymer a Web Komponenten

Wann et nëmmen eng Saach wier ze erënneren:
Polymer != Web Komponenten
Web Komponenten, déi fir d'éischt am Joer 2011 opgetaucht sinn, sinn eng Rei vu 4 Technologien fir Elementer ze kreéieren an ze benotzen, deenen hire Stil a Code aus dem Rescht vun der Applikatioun verschlësselt sinn. Dës 4 Technologien baséieren op W3C Spezifikatioune, e puer vun deenen sinn schonn am Liewensstandard Status.
Am Joer 2013 wollten d'Ingenieuren vu Google Web Komponenten zougänglech maachen andeems en Iwwerlager fir dës Technologien erstellt. Hir Zil ass et fäeg ze schreiwen an ze benotzen Web Komponenten ouni ze waarden op d'Spezifikatioune fir komplett ze sinn an a genuch Browser implementéiert. Dës Iwwerlagerung, séiss genannt Polymer, war bestëmmt fir méi hell ze ginn - oder souguer verschwannen - am Verhältnis zu der Browserofdeckung.
Dës 4 Technologien sinn:

Benotzerdefinéiert Elementer

Dëst sinn JS APIs fir Är HTML Elementer an hiert verbonne Verhalen ze definéieren. Nom Opruff un CustomElementRegistry.define(), Dir kënnt dann de entspriechende Tag an Ärem HTML benotzen.
Si definéieren och d'Liewenszyklus Callbacks vum Element dat Polymer ophëlt.

De Shadow DOM

Dëst ass wat et méiglech mécht d'HTML Struktur an de Stil vum Element ze kapsuléieren, ouni datt d'Äussewelt op eng onkontrolléiert Manéier stéiert.
Polymer geréiert de Shadow DOM fir eis, wärend et eis erlaabt et ze manipuléieren

HTML Schablounen

Dësen Techno definéiert zwee Elementer. <template>, wat Iech erlaabt unrendered HTML ze schreiwen, deen op Elementer kopéiert gëtt, déi se benotzen. den <slot> léisst eis e Raum an eiser HTML Struktur schreiwen wou d'Kannerelementer vun eisem Element agebaut ginn.

HTML Importer

Wann Dir Äre Webkomponent a senger dedizéierter .html Datei geschriwwen hutt, ass ee Wee fir se an Ärer Applikatioun ze benotzen et iwwer en HTML Import z'importéieren:

<link rel="import" href="myfile.html">

Dësen Techno ass kontrovers a wäert schlussendlech net vum Standard ugeholl ginn. Laut Firefox sinn déi aktuell an zukünfteg Tools (ES6 Modul) genuch a bidden méi Kontroll wéi HTML Import.

Polymer Ergänzunge

Zousätzlech fir dës 4 Technologien op all Browser ze schaffen, fannt Dir an der Polymer Toolbox eppes fir d'Entwécklung vu Webkomponenten ze erliichteren:
- Helper fir d'Eegeschafte vun eisem Komponent z'erklären (Standardwäert, nëmme liesen, berechent, Beobachterfunktioun, automatesch Deserialiséierung)
- Eventmanagement (automatesch Abonnement & Abonnement, gestural Eventer fir mobil Benotzer)
- Datemanagement, mat 2-Wee Dateverbindung
- Benotzerdefinéiert Elementer gläichwäerteg zu ngIf an ngFor vun Angular
- a verschidde Utilitys wéi en Debouncer fir ze vermeiden e Callback mat engem ze knappen Intervall ze ruffen
Zousätzlech zu dëse Basisfunktioune bitt Polymer Léisunge fir komplett Uwendungen z'entwéckelen (Routemanagement, Internationaliséierung, offline Gestioun), net ganz nëtzlech well et scho vun Angular geréiert gëtt.

an Angular?

Angular ugefaang no Polymer, am September 2014. Awer am Géigesaz zu Polymer sinn Angular Komponenten net Webkomponenten. Si benotzen Techniken spezifesch fir dës, wéi eng Emulatioun vun der Shadow Dom (déi kann och nativ aktivéiert ginn) fir d'Encapsulation vum Stil, mee du kanns net eng Angular Komponent an engem Ëmfeld aner wéi Angular benotzen.

Angular & Polymer Integratioun

Fir dës Integratioun ze illustréieren, wäerte mir zwee Weeër gesinn: eng einfach a séier, praktesch fir ze testen, an déi aner méi gëeegent fir e Produktiounsëmfeld.
Egal wéi, Dir braucht Bower.

Déi einfach Manéier

An dësem Fall wäerten d'Zollelementer lokal entwéckelt ginn, am Zesummenhang mam Angular Projet. D'Elementer ginn an den index.html importéiert.

  1. Um Wuerzel vun Ärem Projet, initialize bower mat
$ bower init

Prompt Ufroe sinn net interessant well mir net via Bower publizéieren. Eis Notzung wäert limitéiert sinn fir Polymer Ofhängegkeeten ze managen.

  1. Nach ëmmer bei der Root, erstellt eng Datei .bowerrc mat dësem Inhalt:
{
  "directory": "src/assets/bower_components/"
}

wou assets entsprécht Ärem Angular Assets Verzeichnis.

  1. An der .gitignore, Füügt dee selwechte Wee wéi de directory du .bowerrc.

Fir d'Beispill benotze mir Elementer entwéckelt vum Polymer Team.

  1. Installéiert d'Elementer paper-slider et paper-card
$ bower install --save PolymerElements/paper-slider PolymerElements/paper-card
  1. Füügt Är Ofhängegkeeten am index.html.
<head>
  <link rel="import" href="assets/bower_components/paper-card/paper-card.html">
  <link rel="import" href="assets/bower_components/paper-slider/paper-slider.html">
</head>
<body>
  <app-root></app-root>
</body>
  1. Fir Är nei Elementer ze benotzen, musst Dir Tags autoriséieren onbekannt fir Angular. An all Modul deklaréiert Komponenten mat personaliséierten Elementer, musst Dir de Wäert uwenden CUSTOM_ELEMENTS_SCHEMA op d'Propriétéit schemas :
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from "@angular/core";
@NgModule({
  declarations: [AppComponent],
  bootstrap: [AppComponent],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

An do gitt Dir! Wann Dir Är WebComponents lokal wëllt entwéckelen, setzt se an en Dossierassets. Benotzt net Polymer-Cli deen alles generéiert wat Dir braucht fir ze publizéieren, a wäert mat Stuff an Konflikt kommen bower_components.
An Ärem HTML, deen Äre WebComponent definéiert, kënnt Dir de Polymer importéieren, deen no der Installatioun vun Elementer vum Bower installéiert ass:

<link rel="import" href="../bower_components/polymer/polymer.html">

De richtege Wee fir ze produzéieren

Anstatt all Är Komponenten an den Entréespunkt vun Ärer Applikatioun ze lueden, importéiert Dir se an Är Angular Komponenten op der TypeScript Säit. Dës ginn am Stéck agebonnen entspriechend dem Modul vun Ärem Komponent, wat interessant ass wann Dir Är Moduler faul luet. Also reduzéiert Dir déi initial Belaaschtung staark.
Dëst ass méiglech duerch de Projet Polymer Webpack Loader déi Är HTML Element Definitiounen an e JS Bündel transforméiert.
PolymerWebackLoader Operatioun
Dat ass gutt, Webpack ass scho präsent a konfiguréiert iwwer Angular CLI. Dir kënnt d'CLI generéiert Konfiguratioun patchen mat Origami (Polymer + Angular) a kuckt e Benotzungsbeispill mat dësem Starter-Kit.
Sidd awer virsiichteg, wann Är Elementer Biller hosten, musst Dir d'Art a Weis wéi se benotzt ginn änneren. Entweder andeems Dir d'Biller an den Asset Dossier vun Angular réckelt, sou datt de importPath vum Polymer entsprécht, entweder andeems se et iwwer eng Variabel referéiert:

const img = require('./checked.png');

sou datt d'Bild am Bündel abegraff ass.

Integratioun mat Angular Formen

Fir e Polymer Element an eng Angular Form z'integréieren, musst Dir sécher sinn datt se déiselwecht Sprooch schwätzen!
Direktiv benotzt ngDefaultControl op Är Komponent, Dir sécherstellen, datt Angular wäert Evenementer Rechnung huelen input vun Ärem Komponent emittéiert. Dat ass, wann Dir wëllt de Wäert vun der FormControl Angular gëtt vum Polymer Element erfrëscht, Dir musst en Event ofginn input. Zum Beispill fir en Textfeld, input kann no all Tastatur emittéiert ginn.

class DemoElem extends Polymer.Element {
  static get is() { return 'demo-elem'; }
  static get properties() {
    return {
      value: {
        type: String
      }
    };
  }
  notifyChange() {
    this.dispatchEvent(new CustomEvent('input'));
  }
}

Da wäert Angular den aktuelle Wäert iwwer d'Propriétéit recuperéieren value vun der Komponent.
Wann Dir e gesammelt WebComponent benotzt deen net emittéiert input, Dir kënnt eng Direktiv passéieren déi ëmsetzen ControlValueAccessor. D'Angular Team huet eng gutt Partie vun hinnen entwéckelt (ICI) déi mir als Modell benotze kënnen wa mir net fannen wat mir sichen. Dëst ass wou Dir de Komponentevent lauschtere kënnt an d'Resultat interpretéiere ier Dir et an d'Angular Form passéiert, a vice versa wann d'Angular Form e Wäert fir dës Kontroll setzen wëllt.
Dir kënnt e Beispill vun der Ëmsetzung am Repo vun fannen Demo.
Normalerweis gëtt d'Validatioun vun enger Kontroll ëmmer op der Angular Säit gemaach, iwwer de Validators. Angular kann e WebComponent soen datt et ongëlteg ass iwwer Dateverbindung. Et gëtt geréiert vun de WebComponents entwéckelt vum Polymer Team deen eng Immobilie ubitt invalid et error-message. An e puer komplexe Fäll wëllt Dir d'Validitéit an der Komponent verwalten (fir eng besser Kontroll iwwer d'Formatéierung ze hunn, zum Beispill). Fir Angular d'Invaliditéit vun dëser Komponent bewosst ze maachen, anstatt de Validatiounscode ze duplizéieren, kënnt Dir en Event erfaassen deen vun der Komponent generéiert gëtt fir unzeweisen datt säi Validitéitszoustand geännert huet.

Fazit: D'Zukunft vu Webkomponenten mat Angular

Mir hu gesinn datt d'Integratioun vu Polymer 2.0 an Angular de Workflow komplizéiere kéint (besonnesch wann et eng Form Kontroll ass). Mat Polymer 3.0 wäerte mir vu Bower op NPM a vun HTML Import op ES6 Moduler plënneren, wat de Bauschrëtt noutwendeg mécht. Als Alternativ entwéckelt Angular Angular Elements, déi eis erlaben eis Angular Komponenten an Webkomponenten ze exportéieren déi iwwerall benotzt kënne ginn! An Zukunft mengen ech, datt et also manner Interessi gëtt fir Polymer nieft Angular ze benotzen, wa béid esou vill Wiederverwendbarkeet erlaben ... Et wäert eng Saach vu Goût sinn!
Github Demo Projet
Thibault Chevrin, JS-Craftsman @JS-Republic