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

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

Обзор

В этом руководстве создается расширение, которое добавляет ожидаемое время чтения к любому расширению 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.

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

Размер значка Использование значков
16x16 Фавиконка на страницах расширения и в контекстном меню.
32x32 Компьютерам под управлением Windows часто требуется этот размер.
48x48 Отображается на странице «Расширения».
128x128 Отображается при установке и в Интернет-магазине Chrome.

Шаг 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 или не определено.

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

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

Содержимое папки времени чтения: манифест.json, content.js в папке сценариев и папка изображений.

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

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

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

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

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

Время чтения на странице приветствия
Страница приветствия расширения с расширением «Время чтения»

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

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

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

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

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

Расширение Что вы узнаете
Режим фокусировки Чтобы запустить код на текущей странице после нажатия на действие расширения.
Менеджер вкладок Создать всплывающее окно, управляющее вкладками браузера.

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

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

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