Запуск скриптов на каждой странице

Создайте свое первое расширение, которое вставляет новый элемент на страницу.

Обзор

В этом руководстве создается расширение, которое добавляет ожидаемое время чтения к любому расширению Chrome и странице документации Интернет-магазина Chrome.

В этом руководстве мы объясним следующие понятия:

• Манифест расширения.
• Какие размеры значков использует расширение.
• Как внедрить код на страницы с помощью контент-скриптов .
• Как использовать шаблоны совпадений.
• Разрешения на расширение.

Прежде чем ты начнешь

В этом руководстве предполагается, что у вас есть базовый опыт веб-разработки. Мы рекомендуем ознакомиться с руководством Hello world , чтобы познакомиться с рабочим процессом разработки расширений.

Создайте расширение

Для начала создайте новый каталог с именем reading-time для хранения файлов расширения. При желании вы можете скачать полный исходный код с GitHub .

Шаг 1. Добавьте информацию о расширении.

Файл манифеста JSON — единственный обязательный файл. Он содержит важную информацию о расширении. Создайте файл manifest.json в корне проекта и добавьте следующий код:

{
  "manifest_version": 3,
  "name": "Reading time",
  "version": "1.0",
  "description": "Add the reading time to Chrome Extension documentation articles"
}

Эти ключи содержат основные метаданные расширения. Они контролируют, как расширение отображается на странице расширений и, после публикации, в Интернет-магазине Chrome. Чтобы погрузиться глубже, ознакомьтесь с ключами "name" , "version" и "description" на странице обзора манифеста .

💡 Другие факты о манифесте расширения

• Он должен находиться в корне проекта.
• Единственные необходимые ключи — это "manifest_version" , "name" и "version" .
• Он поддерживает комментарии ( // ) во время разработки, но их необходимо удалить перед загрузкой кода в Интернет-магазин Chrome.

Шаг 2. Предоставьте значки

Итак, зачем нужны иконки? Хотя значки не являются обязательными во время разработки, они необходимы, если вы планируете распространять свое расширение в Интернет-магазине Chrome. Они также появляются в других местах, например на странице управления расширениями.

Создайте папку images и поместите туда значки. Скачать иконки можно на GitHub . Затем добавьте выделенный код в свой манифест для объявления значков:

{
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  }
}

Мы рекомендуем использовать файлы PNG, но допускаются и другие форматы файлов, кроме файлов SVG.

💡 Где отображаются значки разного размера?

Шаг 3. Объявите сценарий содержимого.

Расширения могут запускать сценарии, которые читают и изменяют содержимое страницы. Это так называемые сценарии контента . Они живут в изолированном мире , а это означает, что они могут вносить изменения в свою среду JavaScript, не вступая в конфликт со своей хост-страницей или сценариями содержимого других расширений.

Добавьте следующий код в файл manifest.json , чтобы зарегистрировать скрипт контента с именем content.js .

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

Поле "matches" может содержать один или несколько шаблонов совпадений . Они позволяют браузеру определять, на какие сайты следует вставлять сценарии контента. Шаблоны совпадений состоят из трех частей: <scheme>://<host><path> . Они могут содержать символы « * ».

💡 Отображает ли это расширение предупреждение о разрешении?

Когда пользователь устанавливает расширение, браузер сообщает ему, что может делать это расширение. Скрипты контента запрашивают разрешение на запуск на сайтах, соответствующих критериям шаблона соответствия.

В этом примере пользователь увидит следующее предупреждение о разрешении:

Более подробно о разрешениях расширений см. в разделе « Объявление разрешений и предупреждение пользователей» .

Шаг 4. Рассчитайте и укажите время чтения.

Сценарии содержимого могут использовать стандартную объектную модель документа (DOM) для чтения и изменения содержимого страницы. Расширение сначала проверит, содержит ли страница элемент <article> . Затем он подсчитает все слова в этом элементе и создаст абзац, отображающий общее время чтения.

Создайте файл content.js внутри папки scripts и добавьте следующий код:

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

💡 В этом коде использован интересный JavaScript

• Регулярные выражения используются для подсчета только слов внутри элемента <article> .
• insertAdjacentElement() используется для вставки узла времени чтения после элемента.
• Свойство classList используется для добавления имен классов CSS к атрибуту класса элемента.
• Необязательная цепочка, используемая для доступа к свойству объекта, которое может быть неопределенным или иметь значение NULL.
• Нулевое объединение возвращает <heading> , если <date> имеет значение NULL или не определено.

Проверьте, что это работает

Убедитесь, что файловая структура вашего проекта выглядит следующим образом:

Загрузите расширение локально

Чтобы загрузить распакованное расширение в режиме разработчика, выполните действия, описанные в разделе «Основы разработки» .

Откройте расширение или документацию Интернет-магазина Chrome.

Вот несколько страниц, которые вы можете открыть, чтобы увидеть, сколько времени займет чтение каждой статьи.

• Публикация в Интернет-магазине Chrome
• Понимание сценариев контента

Это должно выглядеть так:

🎯 Возможные улучшения

Основываясь на том, что вы узнали сегодня, попробуйте реализовать любое из следующих действий:

• Добавьте еще один шаблон соответствия в файл манифеста.json для поддержки других страниц разработчиков Chrome , например Chrome DevTools или Workbox .
• Добавьте новый скрипт контента, который рассчитывает время чтения, в любой из ваших любимых блогов или сайтов документации.

Продолжайте строить

Поздравляем с завершением этого урока 🎉. Продолжайте совершенствовать свои навыки, выполнив другие уроки из этой серии:

Продолжить изучение

Мы надеемся, что вам понравилось создавать это расширение Chrome, и мы рады продолжить обучение разработке Chrome. Мы рекомендуем следующий путь обучения:

• Руководство разработчика содержит десятки дополнительных ссылок на документацию, относящуюся к созданию расширенных расширений.
• Расширения имеют доступ к мощным API, помимо тех, которые доступны в открытой сети. В документации по API Chrome описан каждый API.