Utwórz pierwsze rozszerzenie, które wstawia nowy element na stronie.
Opis
Ten samouczek tworzy rozszerzenie, które dodaje oczekiwany czas odczytu do każdego rozszerzenia do Chrome i strony dokumentacji Chrome Web Store.
W tym przewodniku zostaną omówione następujące zagadnienia:
- Plik manifestu rozszerzenia.
- rozmiarów ikon używanych w rozszerzeniu.
- Umieszczanie kodu na stronach za pomocą skryptów treści.
- Jak korzystać z wzorców dopasowania.
- Uprawnienia rozszerzeń.
Zanim zaczniesz
W tym przewodniku zakładamy, że masz podstawowe doświadczenie w tworzeniu stron internetowych. Zachęcamy do zapoznania się z samouczkiem Hello world, w którym można poznać procedurę tworzenia rozszerzeń.
Tworzenie rozszerzenia
Na początek utwórz nowy katalog o nazwie reading-time, w którym będą przechowywane pliki rozszerzenia. Jeśli wolisz, możesz pobrać pełny kod źródłowy z GitHub.
Krok 1. Dodaj informacje o rozszerzeniu
Plik JSON manifestu jest jedynym wymaganym plikiem. Zawiera ważne informacje
na temat rozszerzenia. Utwórz plik manifest.json w katalogu głównym projektu i dodaj ten kod:
{
"manifest_version": 3,
"name": "Reading time",
"version": "1.0",
"description": "Add the reading time to Chrome Extension documentation articles"
}
Te klucze zawierają podstawowe metadane rozszerzenia. Określają sposób wyświetlania rozszerzenia na stronie rozszerzeń oraz po opublikowaniu rozszerzenia w Chrome Web Store. Aby dowiedzieć się więcej, sprawdź klucze "name", "version" i "description" na stronie przeglądu pliku manifestu.
💡 Inne fakty dotyczące pliku manifestu rozszerzenia
- Musi się on znajdować w katalogu głównym projektu.
- Jedyne wymagane klucze to
"manifest_version","name"i"version". - Obsługuje komentarze (
//) w trakcie tworzenia aplikacji, ale musisz je usunąć przed przesłaniem kodu do Chrome Web Store.
Krok 2. Dodaj ikony
Do czego służą ikony? Chociaż ikony są opcjonalne na etapie tworzenia, są wymagane, jeśli planujesz dystrybuować rozszerzenie w Chrome Web Store. Pojawiają się też w innych miejscach, np. na stronie zarządzania rozszerzeniami.
Utwórz folder images i umieść w nim ikony. Ikony możesz pobrać z GitHub. Następnie dodaj zaznaczony kod do pliku manifestu, aby zadeklarować ikony:
{
"icons": {
"16": "images/icon-16.png",
"32": "images/icon-32.png",
"48": "images/icon-48.png",
"128": "images/icon-128.png"
}
}
Zalecamy używanie plików PNG, ale są dozwolone inne formaty, z wyjątkiem SVG.
💡 Gdzie są wyświetlane ikony o różnych rozmiarach?
| Rozmiar ikony | Użycie ikon |
|---|---|
| 16 × 16 | Favikona na stronach rozszerzenia i w menu kontekstowym. |
| 32 × 32 | Komputery z systemem Windows często wymagają takiego rozmiaru. |
| 48 × 48 | Wyświetla się na stronie Rozszerzenia. |
| 128 × 128 | Wyświetla się podczas instalacji i w Chrome Web Store. |
Krok 3. Zadeklaruj skrypt treści
Rozszerzenia mogą uruchamiać skrypty odczytujące i modyfikujące zawartość strony. Są to tzw. skrypty treści. Mieszkają w odizolowanym świecie, co oznacza, że mogą wprowadzać zmiany w środowisku JavaScriptu bez konfliktów ze stroną hosta lub skryptami treści innych rozszerzeń.
Dodaj do manifest.json ten kod, aby zarejestrować skrypt treści o nazwie content.js.
{
"content_scripts": [
{
"js": ["scripts/content.js"],
"matches": [
"https://developer.chrome.com/docs/extensions/*",
"https://developer.chrome.com/docs/webstore/*"
]
}
]
}
Pole "matches" może mieć 1 lub więcej wzorców dopasowania. Dzięki temu przeglądarka może zidentyfikować witryny, w których ma wstrzyknąć skrypty zawartości. Wzorce dopasowania składają się z 3 części: <scheme>://<host><path>. Mogą zawierać znaki „*”.
💡 Czy to rozszerzenie wyświetla ostrzeżenie o uprawnieniach?
Gdy użytkownik zainstaluje rozszerzenie, przeglądarka informuje go, co ono może zrobić. Skrypty treści żądają uprawnień do działania w witrynach, które spełniają kryteria dotyczące wzorca dopasowania.
W tym przykładzie użytkownik zobaczy takie ostrzeżenie o uprawnieniach:
Więcej informacji na temat uprawnień dotyczących rozszerzeń znajdziesz w artykule Deklarowanie uprawnień i ostrzeganie użytkowników.
Krok 4. Oblicz i wstaw czas odczytu
Skrypty treści mogą odczytywać i zmieniać zawartość strony za pomocą standardowego modelu obiektu dokumentu (DOM). Rozszerzenie najpierw sprawdzi, czy strona zawiera element <article>.
Następnie policz wszystkie słowa w tym elemencie i utworzy akapit z całkowitym czasem czytania.
W folderze scripts utwórz plik o nazwie content.js i dodaj do niego ten kod:
const article = document.querySelector("article");
// `document.querySelector` may return null if the selector doesn't match anything.
if (article) {
const text = article.textContent;
const wordMatchRegExp = /[^\s]+/g; // Regular expression
const words = text.matchAll(wordMatchRegExp);
// matchAll returns an iterator, convert to array to get word count
const wordCount = [...words].length;
const readingTime = Math.round(wordCount / 200);
const badge = document.createElement("p");
// Use the same styling as the publish information in an article's header
badge.classList.add("color-secondary-text", "type--caption");
badge.textContent = `⏱️ ${readingTime} min read`;
// Support for API reference docs
const heading = article.querySelector("h1");
// Support for article docs with date
const date = article.querySelector("time")?.parentNode;
(date ?? heading).insertAdjacentElement("afterend", badge);
}
💡 W tym kodzie użyto ciekawego kodu JavaScript
- Wyrażenia regularne służące do zliczania tylko słów w elemencie
<article>. insertAdjacentElement(): służy do wstawiania węzła czasu odczytu po elemencie.- Właściwość classList służąca do dodawania nazw klas CSS do atrybutu klasy elementu.
- Opcjonalne łańcuchy umożliwiające dostęp do właściwości obiektu, która może być niezdefiniowana lub mieć wartość null.
- Nullish coalescing zwraca wartość
<heading>, jeśli<date>ma wartość null lub nie została zdefiniowana.
Sprawdź, czy to działa
Sprawdź, czy struktura pliku projektu wygląda tak:
Wczytaj rozszerzenie lokalnie
Aby wczytać rozszerzenie bez pakietu w trybie programisty, wykonaj czynności opisane w artykule Podstawy dla programistów.
Otwórz dokumentację rozszerzenia lub Chrome Web Store
Oto kilka stron, które możesz otworzyć, aby sprawdzić, ile czasu zajmie przeczytanie każdego artykułu.
Powinien on wyglądać podobnie do tego:
🎯 Potencjalne ulepszenia
Opierając się na zdobytych dzisiaj umiejętnościach, spróbuj zastosować którąś z tych metod:
- Dodaj kolejny wzorzec dopasowania w pliku manifest.json, aby obsługiwać inne strony deweloperów Chrome, takie jak Narzędzia deweloperskie w Chrome lub pole robocze.
- Dodaj nowy skrypt treści, który oblicza czas czytania w dowolnym z Twoich ulubionych blogów lub witryn z dokumentacją.
Twórz dalej
Gratulujemy ukończenia tego samouczka 🎉. Rozwijaj swoje umiejętności, korzystając z innych samouczków z tej serii:
| Rozszerzenie | Czego się nauczysz |
|---|---|
| Tryb pełnej koncentracji | Aby uruchomić kod na bieżącej stronie po kliknięciu działania rozszerzenia. |
| Menedżer kart | Aby utworzyć wyskakujące okienko do zarządzania kartami przeglądarki. |
Przeglądaj dalej
Mamy nadzieję, że tworzenie tego rozszerzenia do Chrome podobało Ci się i chcesz kontynuować naukę w zakresie programowania. Zalecamy skorzystanie z tej ścieżki szkoleniowej:
- Przewodnik dla programistów zawiera dziesiątki dodatkowych linków do dokumentacji dotyczącej zaawansowanego tworzenia rozszerzeń.
- Rozszerzenia mają dostęp do zaawansowanych interfejsów API poza tymi, które są dostępne w otwartym internecie. W dokumentacji interfejsów API Chrome omówione są poszczególne interfejsy API.