Uruchamianie skryptów na każdej stronie

Utwórz pierwsze rozszerzenie, które wstawia na stronie nowy element.

Omówienie

W tym samouczku tworzymy rozszerzenie, które dodaje przewidywany czas czytania do dowolnego rozszerzenia Chrome i strony dokumentacji Chrome Web Store.

W tym przewodniku omawiamy te zagadnienia:

• Plik manifestu rozszerzenia.
• Rozmiary ikon, których używa rozszerzenie.
• Jak wstrzykiwać kod na stronach za pomocą skryptów treści.
• Jak używać wzorów dopasowania.
• Uprawnienia rozszerzenia.

Zanim rozpoczniesz

W tym przewodniku zakładamy, że masz podstawowe doświadczenie w programowaniu stron internetowych. Aby zapoznać się z procesem tworzenia rozszerzeń, zalecamy obejrzenie samouczka Hello world.

Tworzenie rozszerzenia

Najpierw utwórz nowy katalog o nazwie reading-time, który będzie przechowywać pliki rozszerzenia. Jeśli wolisz, możesz pobrać pełny kod źródłowy z GitHub.

Krok 1. Dodaj informacje o rozszerzeniu

Plik manifestu w formacie JSON jest jedynym wymaganym plikiem. Zawiera on ważne informacje o rozszerzeniu. 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ą one sposób wyświetlania rozszerzenia na stronie rozszerzeń i w przypadku opublikowania – w Chrome Web Store. Aby uzyskać więcej informacji, sprawdź klucze "name", "version" i "description" na stronie przeglądu pliku manifestu.

💡 Inne informacje o pliku manifestu rozszerzenia

• Musi znajdować się w korzeniach projektu.
• Wymagane są tylko klucze "manifest_version", "name" i "version".
• Obsługuje komentarze (//) podczas tworzenia, ale należy je usunąć przed przesłaniem kodu do Chrome Web Store.

Krok 2. Prześlij ikony

Po co Ci ikony? Ikony są opcjonalne podczas tworzenia, ale są wymagane, jeśli planujesz rozpowszechniać 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 do pliku manifestu wyróżniony kod, 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 dozwolone są też inne formaty (z wyjątkiem plików SVG).

💡 Gdzie wyświetlają się ikony o różnych rozmiarach?

Krok 3. Zadeklaruj skrypt treści

Rozszerzenia mogą uruchamiać skrypty, które odczytują i modyfikują zawartość strony. Nazywamy je skryptami treści. Mają one oddzielne środowisko, co oznacza, że mogą wprowadzać zmiany w swoim środowisku JavaScript bez konfliktu z witryną hostującą lub skryptami treści innych rozszerzeń.

Aby zarejestrować skrypt treści o nazwie content.js, dodaj do pliku manifest.json ten kod:

{
  "content_scripts": [
    {
      "js": ["scripts/content.js"],
      "matches": [
        "https://developer.chrome.com/docs/extensions/*",
        "https://developer.chrome.com/docs/webstore/*"
      ]
    }
  ]
}

Pole "matches" może zawierać co najmniej 1 wzorzec dopasowania. Umożliwiają one przeglądarce określenie, do których witryn mają być wstrzyknięte skrypty treści. Wzorce dopasowania składają się z 3 części:<scheme>://<host><path>. Może zawierać znaki „*”.

💡 Czy to rozszerzenie wyświetla ostrzeżenie o przyznaniu uprawnień?

Gdy użytkownik instaluje rozszerzenie, przeglądarka informuje go o jego możliwościach. Skrypty treści proszą o zezwolenie na działanie w witrynach, które spełniają kryteria dopasowania wzorca.

W tym przykładzie użytkownik zobaczy takie ostrzeżenie o uprawnieniach:

Więcej informacji o uprawnieniach rozszerzeń znajdziesz w artykule Oświadczanie uprawnień i ostrzeganie użytkowników.

Krok 4. Oblicz i wstaw czas czytania

Skrypty treści mogą korzystać ze standardowego modelu DOM (Document Object Model) do odczytywania i zmieniania zawartości strony. Najpierw sprawdzi, czy strona zawiera element <article>. Następnie zlicza wszystkie słowa w tym elemencie i tworzy akapit, który zawiera łączny czas czytania.

Utwórz plik o nazwie content.js w folderze o nazwie scripts i dodaj ten kod:

function renderReadingTime(article) {
  // If we weren't provided an article, we don't need to render anything.
  if (!article) {
    return;
  }

  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);
}

renderReadingTime(document.querySelector("article"));

💡 Ciekawostki dotyczące 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 czytania po elemencie.
• Właściwość classList służy do dodawania nazw klas CSS do atrybutu klasy elementu.