Разрабатываем браузерное расширение легким движением руки

Hello, world!

В этом небольшом туториале мы с вами разработаем простое, но полезное расширение для браузера с помощью Plasmo.

Наше расширение будет представлять собой вызываемый сочетанием клавиш попап с инпутом для поиска информации на MDN с выводом 5 лучших результатов в виде списка. Кроме основного функционала, мы добавим страницу настроек для кастомизации цветов и отображения хлебных крошек. Мы будем разрабатывать расширения для Chrome, которое также будет работать в Firefox.

Вот как это будет выглядеть:

Для тех, кого интересует только код, вот ссылка на соответствующий репозиторий.

Интересно? Тогда прошу под кат.

Основной функционал — попап с поиском

Для работы с зависимостями будет использоваться Yarn.

Создаем шаблон приложения:

# mdn-finder - название приложения/расширения
yarn create plasmo mdn-finder

Переходим в созданную директорию и устанавливаем зависимости:

cd mdn-finder

yarn

Устанавливаем дополнительные зависимости, необходимые для работы поиска:

yarn add @plasmohq/storage downshift flexsearch fzf swr

• @plasmohq/storage — абстракция над Storage API, который может использоваться расширениями браузера для локального хранения данных;
• downshift — библиотека, предоставляющая примитивы для разработки простых, гибких, отвечающих всем критериям WAI-ARIA React-компонентов autocomplete/combobox или select/dropdown;
• flexsearch — библиотека для реализации полнотекстового поиска;
• fzf — библиотека для реализации неточного (fuzzy) поиска;
• swr — хуки React для получения, кэширования и мутации данных.

Структура проекта будет следующей:

- assets
  - icon.png
  - search-index.json
  - search.png
- src
  - components
    - Search.tsx
  - search
    - fuzzy-search.ts
    - search-utils.ts
    - search.tsx
  - background.ts
  - options.tsx
  - popup.tsx
  - storage.ts
  - style.css
  - ...

После переноса файлов в директорию src, необходимо немного отредактировать файл tsconfig.json:

{
  // ...
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "~*": [
        "./src/*"
      ]
    }
  }
}

О самом поиске я рассказывал в этой статье, поэтому в данном туториале мы сосредоточимся на Plasmo. Скопируйте файлы из директорий components, search и assets, а также файл style.css из репозитория проекта. Поисковый индекс (search-index.json), также можно копировать с MDN. Запросы к MDN из другого источника блокируются CORS, поэтому поисковый индекс хранится локально.

Для того, чтобы иметь возможность работать с поисковым индексом, необходимо немного отредактировать файл package.json:

{
  // ...
  "manifest": {
    "web_accessible_resources": [
      {
        "resources": [
          "assets/search-index.json"
        ],
        "matches": [
          "https://*/*"
        ]
      }
    ],
    "host_permissions": [
      "https://*/*"
    ]
  }
}

Точкой входа приложения Plasmo является файл popup.tsx. Как следует из названия, этот компонент отвечает за рендеринг попапа, в котором будет находиться инпут для поиска. Редактируем этот файл следующим образом:

import Search from './components/Search'
import './style.css'

function IndexPopup() {
  return <Search preload={true} />
}

export default IndexPopup

Запускаем сервер для разработки с помощью команды yarn dev. Выполнение этой команды приводит к генерации директории build/chrome-mv3-dev с файлами расширения.

Переходим по адресу chrome://extensions/ и загружаем расширение в браузер (кнопка "Загрузить распакованное расширение"/"Load unpacked extension"):

В режиме разработки расширение, загруженное в браузер, автоматически обновляется при изменении соответствующих файлов.

Сочетание клавиш для запуска расширения можно установить на странице chrome://extensions/shortcuts:

Для создания производственной сборки необходимо выполнить команду yarn build. По умолчанию создается сборка для Chrome. В настоящее время Plasmo также поддерживает создание сборок для Firefox. Команда для создания такой сборки: yarn build --target=firefox-mv2. Подробнее почитать об этом можно здесь.

Для тестирования расширения в Firefox необходимо сделать 2 вещи:

• создать в директории src файл background.ts следующего содержания:

export {}

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

• создать производственную сборку в виде архива с помощью команды yarn build --target=firefox-mv2 --zip.

Дополнительный функционал — страница настроек

Для инициализации страницы настроек достаточно создать файл options.tsx в директории src.

Простейшим способом обмена данными между попапом и страницей настроек (а также другими скриптами) является использование предоставляемого Plasmo хранилища.

Создаем в директории src файл storage.ts следующего содержания:

import { Storage } from '@plasmohq/storage'

// ключ объекта настроек
export const OPTIONS_KEY = 'mdn_finder_options'

// дефолтные настройки
export const defaultOptions = {
  // цвет фона
  backgroundColor: '#282c34',
  // цвет текста
  textColor: '#f7f7f7',
  // фон выделения
  selectionBackground: '#5cb85c',
  // цвет выделения
  selectionColor: '#282c34',
  // индикатор отображения хлебных крошек в списке результатов поиска
  showUrl: true
}

// создаем экземпляр хранилища
const storage = new Storage()

// и экспортируем его
export default storage

Редактируем файл options.tsx следующим образом:

import { useRef } from 'react'
import storage, { defaultOptions, OPTIONS_KEY } from '~storage'
import './style.css'

export default function IndexOptions() {
  // ссылка на кнопку отправки формы
  const btnRef = useRef<HTMLButtonElement | null>(null)

  // обработчик отправки формы
  const onSubmit: React.FormEventHandler = async (e) => {
    e.preventDefault()

    // получаем данные формы в виде объекта
    const formData = Object.fromEntries(
      new FormData(e.target as HTMLFormElement).entries(),
    )

    try {
      // записываем настройки в хранилище
      await storage.set(OPTIONS_KEY, formData)

      // меняем текст кнопки
      if (btnRef.current) {
        btnRef.current.textContent = 'Saved'

        const id = setTimeout(() => {
          btnRef.current.textContent = 'Save'
          clearTimeout(id)
        }, 1000)
      }
    } catch (e) {
      console.log(e)
    }
  }

  return (
    <form className='options' onSubmit={onSubmit}>
      <label>
        Background color:{' '}
        <input
          type='color'
          name='backgroundColor'
          defaultValue={defaultOptions.backgroundColor}
        />
      </label>
      <label>
        Result item color:{' '}
        <input
          type='color'
          name='textColor'
          defaultValue={defaultOptions.textColor}
        />
      </label>
      <label>
        Selection background:{' '}
        <input
          type='color'
          name='selectionBackground'
          defaultValue={defaultOptions.selectionBackground}
        />
      </label>
      <label>
        Selection color:{' '}
        <input
          type='color'
          name='selectionColor'
          defaultValue={defaultOptions.selectionColor}
        />
      </label>
      <label>
        Show URL:{' '}
        <input
          type='checkbox'
          name='showUrl'
          defaultChecked={defaultOptions.showUrl}
        />
      </label>
      <button ref={btnRef}>Save</button>
    </form>
  )
}

Для того, чтобы попасть на страницу настроек, необходимо кликнуть по иконке расширения и выбрать пункт "Параметры"/"Options":

Возвращаемся к попапу. Редактируем файл search/search.tsx. Импортируем хранилище и извлекаем из него настройки:

import storage, { defaultOptions, OPTIONS_KEY } from '~storage'

// ...

function InnerSearchNavigateWidget(props: InnerSearchNavigateWidgetProps) {
  // ...
  const [options, setOptions] = useState(defaultOptions)

  // ...
  useEffect(() => {
    storage.get<typeof options>(OPTIONS_KEY).then((opts) => {
      if (opts) {
        setOptions(opts)
      }
    })
  }, [])

  // далее работаем с этим компонентом
}

Индикатор отображения хлебных крошек (options.showUrl) используется при формировании списка результатов поиска:

resultItems.map((item, i) => (
  <div
    {...getItemProps({
      key: item.url,
      className:
        'result-item ' + (i === highlightedIndex ? 'highlight' : ''),
      item,
      index: i,
    })}
  >
    <HighlightMatch title={item.title} q={inputValue} />
    {/* ! */}
    {Boolean(options.showUrl) ? (
      <>
        <br />
        <BreadcrumbURI uri={item.url} positions={item.positions} />
      </>
    ) : null}
  </div>
))

Цвет фона (options.backgroundColor) передается элементу формы:

<form
  // ...
  style={
    {
      '--background-color': options.backgroundColor,
    } as React.CSSProperties
  }
>
  {/* ... */}
</form>

В файле style.css у нас имеются такие строки:

.search-form {
  --background-color: var(--dark);

  /* ... */
  background-color: var(--background-color);
}

Остальные цвета передаются контейнеру с результатами поиска:

<div
  className='search-results'
  style={
    {
      '--text-color': options.textColor,
      '--selection-background': options.selectionBackground,
      '--selection-color': options.selectionColor,
    } as React.CSSProperties
  }
>
  {searchResults}
</div>

В style.css у нас имеются такие строки:

.search-results {
  --text-color: var(--light);
  --selection-background: var(--success);
  --selection-color: var(--dark);
}

.result-item span,
.result-item small {
  color: var(--text-color);
}

.result-item mark {
  background-color: var(--selection-background);
  color: var(--selection-color);
}

Спасибо переменным CSS за их динамичность :)

Меняем настройки:

Запускаем расширение:

Видим, что настройки благополучно применяются к попапу.

Следует отметить, что проект, созданный с помощью Plasmo CLI, включает в себя GitHub Action Browser Platform Publisher для автоматической публикации расширения во всех поддерживаемых сторах. Подробнее почитать об этом можно здесь. Соответствующий файл можно найти в директории .github/workflows.

К слову, поисковый индекс со статьями на русском языке можно найти здесь.

Надеюсь, вы узнали что-то новое и не зря потратили время.

Happy coding!