Aktualizacja komponentów sieciowych – więcej czasu na uaktualnienie do interfejsów API w wersji 1

Jonathan Bingham

Arthur Evans

Interfejsy API Web Components w wersji 1 są standardem platformy internetowej, który jest dostępny w Chrome, Safari, Firefoxie i (wkrótce) w Edge. Z interfejsów API w wersji 1 korzystają dosłownie miliony witryn, które docierają do miliardów użytkowników każdego dnia. Deweloperzy korzystający z wersji roboczej interfejsów API 0 przekazali cenne opinie, które wpłynęły na specyfikacje. Interfejsy API w wersji 0 były jednak obsługiwane tylko przez Chrome. Aby zapewnić interoperacyjność, pod koniec zeszłego roku ogłosiliśmy, że te wersje interfejsów API zostały wycofane i planujemy ich usunięcie w wersji Chrome 73.

Ponieważ wystarczająco dużo deweloperów poprosiło o dodatkowy czas na migrację, interfejsy API nie zostały jeszcze usunięte z Chrome. Interfejsy API wersji 0 draft zostaną usunięte w Chrome 80, około lutego 2020 roku.

Jeśli uważasz, że używasz interfejsów API w wersji 0, musisz wiedzieć:

• Przetestuj swoją stronę z wyłączonymi interfejsami API w wersji 0. Jeśli witryna działa zgodnie z oczekiwaniami, gratulujemy! Gotowe. Instrukcje znajdziesz w artykule Wracamy do przyszłości: wyłączanie interfejsów API w wersji 0.
• Jeśli używasz biblioteki Polymer w wersji 1 lub 2 – postępuj zgodnie z instrukcjami opublikowanymi wcześniej przez zespół Polymer.
• Jeśli używasz modelu Shadow DOM v0, elementów niestandardowych v0 lub importów HTML, musisz załadować niektóre polyfille. Zobacz Używanie polyfillów w wersji 0.
• Jeśli nie masz pewności, czego używasz, nie martw się. Zobacz Pomoc Nie wiem, których interfejsów API używam.

Powrót do przyszłości: wyłączanie interfejsów API w wersji 0

Aby przetestować swoją witrynę z wyłączonymi interfejsami API w wersji 0, musisz uruchomić Chrome z linii poleceń, korzystając z tych flag:

--disable-blink-features=ShadowDOMV0,CustomElementsV0,HTMLImports

Przed uruchomieniem Chrome z poziomu wiersza poleceń musisz zamknąć przeglądarkę. Jeśli masz zainstalowaną wersję Chrome Canary, możesz uruchomić test w Canary, zachowując tę stronę w Chrome.

Aby przetestować witrynę z wyłączonymi interfejsami API w wersji 0:

1. Jeśli używasz systemu Mac OS, otwórz folder chrome://version, aby znaleźć ścieżkę do pliku wykonywalnego Chrome. Będzie on potrzebny w kroku 3.
2. Zamknij Chrome.

3. Uruchom ponownie Chrome z flagami wiersza poleceń:

   --disable-blink-features=ShadowDOMV0,CustomElementsV0,HTMLImports

   Instrukcje uruchamiania Chrome z flagami znajdziesz w artykule Uruchamianie Chromium z flagami. Na przykład w Windowsie możesz uruchomić:

   chrome.exe --disable-blink-features=ShadowDOMV0,CustomElementsV0,HTMLImports
   

4. Aby sprawdzić, czy przeglądarka została uruchomiona prawidłowo, otwórz nową kartę, otwórz konsolę Narzędzi deweloperskich i uruchom to polecenie:

   console.log(
   "Native HTML Imports?", 'import' in document.createElement('link'),
   "Native Custom Elements v0?", 'registerElement' in document,
   "Native Shadow DOM v0?", 'createShadowRoot' in document.createElement('div'));
   

   Jeśli wszystko działa zgodnie z oczekiwaniami, powinieneś zobaczyć:

   Native HTML Imports? false Native Custom Elements v0? false Native Shadow DOM v0? false
   

   Jeśli przeglądarka zwraca wartość „PRAWDA” w przypadku dowolnej lub wszystkich tych funkcji, oznacza to, że coś jest nie tak. Przed ponownym uruchomieniem Chrome z flagami upewnij się, że całkowicie ją zamknąłeś(-a).

5. Na koniec załaduj aplikację i sprawdzaj jej funkcje. Jeśli wszystko działa zgodnie z oczekiwaniami, możesz zakończyć konfigurację.

Używanie polyfillów w wersji 0

W przypadku przeglądarek, które nie obsługują natywnej wersji interfejsu API v0, można użyć polyfillów Web Components v0. Jeśli po wyłączeniu interfejsów API w wersji 0 witryna nie działa w Chrome, prawdopodobnie nie wczytują się polyfille. Istnieje kilka możliwości:

• Wczytywanie polyfills nie jest w ogóle możliwe. W takim przypadku Twoja witryna powinna się nie wczytywać w innych przeglądarkach, takich jak Firefox czy Safari.
• Wczytujesz polyfille warunkowo na podstawie rozpoznawania przeglądarki. W takim przypadku Twoja witryna powinna działać w innych przeglądarkach. Przejdź do sekcji Wczytywanie polyfillów.

W przeszłości zespół projektu Polymer i inne osoby zalecały warunkowe wczytywanie polyfills na podstawie wykrywania funkcji. To podejście powinno działać dobrze w przypadku wyłączonych interfejsów API w wersji 0.

Zainstaluj polyfilly w wersji 0.

Biblioteki polyfill Web Components v0 nigdy nie zostały opublikowane w rejestrze npm. Jeśli Twój projekt korzysta już z Bowera, możesz zainstalować polyfilly za pomocą Bower. Możesz też zainstalować go z pliku ZIP.

• Aby zainstalować za pomocą Bower:

  bower install --save webcomponents/webcomponentsjs#^0.7.0

• Aby zainstalować z pliku ZIP, pobierz najnowszą wersję 0.7.x z GitHuba:

  https://github.com/webcomponents/webcomponentsjs/releases/tag/v0.7.24

  Jeśli instalujesz z pliku ZIP, w przypadku wydania nowej wersji polyfills musisz je zaktualizować ręcznie. Warto sprawdzić, czy polyfills działają prawidłowo z Twoim kodem.

Załaduj polyfille w wersji 0.

Komponenty internetowe w wersji 0 są dostępne w dwóch osobnych pakietach:

webcomponents-min.js	Obejmuje wszystkie polyfille. Ten pakiet zawiera polyfill dla shadow DOM, który jest znacznie większy niż inne polyfille i ma większy wpływ na wydajność. Używaj tego pakietu tylko wtedy, gdy potrzebujesz obsługi shadow DOM.
webcomponents-lite-min.js	Obejmuje wszystkie polyfille z wyjątkiem shadow DOM. Uwaga: użytkownicy wersji 1.x biblioteki Polymer powinni wybrać ten pakiet, ponieważ emulacja Shadow DOM została uwzględniona bezpośrednio w bibliotece Polymer. Użytkownicy wersji 2.x biblioteki Polymer potrzebują innej wersji polyfill. Więcej informacji znajdziesz w poście na blogu projektu Polymer.

W ramach pakietu polyfill dla komponentów internetowych dostępne są też pojedyncze polyfille. Korzystanie z pojedynczych polyfilli jest tematem zaawansowanym i nie jest omawiane w tym artykule.

Aby bezwarunkowo wczytać polyfille:

<script src="/bower_components/webcomponents/webcomponentsjs/webcomponents-lite-min.js">
</script>

Lub:

<script src="/bower_components/webcomponents/webcomponentsjs/webcomponents-min.js">
</script>

Jeśli polyfills zostały zainstalowane bezpośrednio z GitHuba, musisz podać ścieżkę do folderu, w którym zostały zainstalowane.

Jeśli warunkowo wczytujesz polyfille na podstawie wykrywania funkcji, Twoja witryna powinna nadal działać, gdy usuniesz obsługę wersji 0.

Jeśli warunkowo wczytujesz polyfille za pomocą rozpoznawania przeglądarki (czyli wczytujesz polyfille w przeglądarkach innych niż Chrome), Twoja witryna nie będzie działać, gdy wsparcie dla wersji 0 zostanie usunięte z Chrome.

Dlaczego Nie wiem, których interfejsów API używam

Jeśli nie wiesz, czy używasz interfejsów API w wersji 0, możesz sprawdzić dane konsoli w Chrome.

1. Jeśli Chrome zostało uruchomione z flagami wyłączającymi interfejsy API v0, zamknij przeglądarkę i uruchom ją ponownie.
2. Otwórz nową kartę w Chrome i załaduj swoją witrynę.
3. Aby otworzyć konsolę w narzędziach dla programistów, naciśnij Ctrl + Shift + J (Windows, Linux, ChromeOS) lub Command + Option + J (Mac).
4. Sprawdź, czy w wyjściu konsoli nie ma komunikatów o wycofaniu. Jeśli konsola zwraca dużo danych, w polu Filtr wpisz „Deprecation” (Wycofanie).

Powinny się wyświetlić komunikaty o wycofaniu dla każdego interfejsu API w wersji 0, którego używasz. Wynik powyżej zawiera komunikaty dotyczące importów HTML, elementów niestandardowych w wersji 0 i domunie cieniowanego w wersji 0.

Jeśli używasz co najmniej jednego z tych interfejsów API, zapoznaj się z artykułem Używanie polyfillów w wersji 0.

Dalsze kroki: rezygnacja z wersji 0

Załadowanie polyfilli v0 powinno zapewnić, że Twoja witryna będzie działać, gdy interfejsy API v0 zostaną usunięte. Zalecamy przejście na interfejsy API Web Components w wersji 1, które są powszechnie obsługiwane.

Jeśli używasz biblioteki Web Components, takiej jak biblioteka Polymer, X-Tag czy SkateJS, najpierw sprawdź, czy są dostępne nowsze wersje biblioteki, które obsługują interfejsy API w wersji 1.

Jeśli masz własną bibliotekę lub napisałeś elementy niestandardowe bez biblioteki, musisz zaktualizować je do nowych interfejsów API. Te materiały mogą Ci się przydać:

• Co nowego w elementach niestandardowych
• Co nowego w Shadow DOM w wersji 1

Podsumowanie

Interfejsy API Web Components v0 w wersji roboczej zostaną wycofane. Jeśli z tego wpisu zapamiętasz tylko jedną rzecz, nie zapomnij przetestować aplikacji z wyłączonymi interfejsami API w wersji 0 i w razie potrzeby wczytać polyfille.

Zachęcamy do przejścia na najnowsze interfejsy API i dalszego używania komponentów sieciowych.