Некоторые технические подробности по исходному коду расширения Поиск статей на Sci-Hub.
Применяемые технологии и API. Особенности установки и использования. Локализация.

В этой статье:

• Исходный код, интерфейс и API
  • Интерфейс управления и настроек
  • Применяемые API и отличия версий
  • Функция и вызов "Волшебной Кнопки"
• Локализация интерфейса и перевод
  • Поддержка перевода на другие языки
• Дополнительные примечания по исходному коду
  • Использование в браузерах старше CR49

Исходный код, интерфейс и API

Find Docs in Sci‑Hub RU не использует для работы никакие сторонние библиотеки (привет любителям JQuery)).

В коде применён только чистый JS (ES5), все неподдерживаемые в "старых" браузерах функции заменены на аналоги. Основной скрипт работает в "строгом" режиме – для гарантии выполнения функций и облегчения отлова ошибок.

Аддон загружается только в момент вызова, не имеет фонового процесса и не занимает память в покое. Кроме того, добавлена функция ускоренной выгрузки расширения из памяти после выполнения требуемых действий.

Все версии, начиная с 2021.9.14, имеют модульную структуру* скриптов (построена по принципам, отработанным ранее в другом моём аддоне, x.Block). Несмотря на некоторое увеличение общего размера установочного пакета, бонусом этого подхода является серьёзное облегчение постоянно используемого кода, работа с настройками и другие сервисные функции при этом не "болтаются" в памяти и подгружаются только при их вызове.

* Зачем/почему – основной модуль аддона уменьшен почти вдвое, выше его "отзывчивость" и скорость загрузки и работы. Теперь в основном скрипте оставлены только часто применяемые функции, такие как запуск поиска или ссылочные переходы. Все достаточно редкие функции, связанные с установкой или изменением пунктов контекстного меню (например, при изменении отдельных настроек) или с запуском проверки обновления версии, подгружаются только при необходимости. Падение производительности при этом чисто теоретическое, "на глаз" заметно не будет.

В текущей версии подгружаемые модули представлены следующими отдельными скриптами:

• scihub.js – основной скрипт, содержит все часто используемые функции и установки;

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

• cmenu.js – содержит функции проверки ключей настроек и установки контекстного меню;

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

• extlink.js – содержит функции автопроверки обновления, резервного копирования и прямых ссылочных переходов;

  Загружается только по требованию, при вызове из меню пунктов группы "Сведения о расширении" или при выполнении операций сохранения и восстановления настроек (соответствующие пункты в группе "Настройки и управление").

  При вызове из меню пункта "Проверить и скачать обновление") выполняет фоновый запрос и проверяет номер текущей стабильной версии на сайте, сравнивает его с версией, установленной в вашем браузере, и по результату проверки выдаёт соответствующее сообщение:
  
  ^{Щёлкните по изображению, чтобы просмотреть скриншот на другом языке.}

  Если установленная и официальная версия отличаются, выдаётся запрос на переход на страницу ченч-лога текущей официальной версии для ознакомления с изменениями в ней и самостоятельной загрузки* и установки обновления.

  * В текущей версии аддона при этом выполняется и автозапуск** загрузки CRX-установщика формата, соответствующего текущей версии вашего браузера (до версий CR67 всегда отдаётся CRXv2, для более новых CRXv3).

  ** В зависимости от "огороженности" браузера может потребоваться подтверждение скачивания "опасного файла". :)

• vsobro.js – содержит редко используемые функции для работы с браузерами версий старше CR47.

  Загружается только по требованию, при первичной установке или при обновлении версии браузера (если она тоже старая:)), а также при проверке доступности хоткея (CR29) и запроса дополнительного разрешения доступа ко вкладкам (опционально, если хоткей нужен на служебных страницах). Не связан с вызовом операций поиска, загрузки и изменением настроек.

Интерфейс управления и настроек

Расширение не имеет никакого интерфейса, кроме контекстного меню и кнопки на тулбаре. Все диалоги и сообщения выдаются с помощью стандартных операторов "alert" и "prompt". Все настройки выполняются через контекстное меню, отдельной страницы настроек нет (и не будет). Сохранение настроек производится автоматически, сразу же после их изменения. Перезапуск расширения или иные действия при этом не требуются.

В браузерах версий до CR49 все дополнительные настройки и сервисные ссылки доступны в контекстном меню страницы только при щелчке на её свободном месте (т.е. НЕ на ссылке, изображении или выделенном тексте).

В более новых версиях браузеров (CR49+) настройки доступны всегда – в меню кнопки на тулбаре:

^{Щёлкните по изображению, чтобы просмотреть скриншот на другом языке.}

В контекстном меню страницы в версиях CR49+ оставлен только пункт поиска:

Если в настройках включён режим прямой загрузки (опция "Загружать найденное без просмотра"), изменяется и контекстное меню страницы и, соответственно, действие по умолчанию для горячей клавиши и щелчка по кнопке на тулбаре. Изменённый пункт выглядит вот так:

В меню настроек при этом также указывается это же действие (вторая строчка на общем скриншоте выше).

Применяемые API и отличия версий

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

Для работы со вкладками задействуется API chrome.tabs. Также в манифесте запрашивается разрешение activeTab, упрощающее отдельные действия на текущих страницах.

Для вызова основной функции при щелчке по кнопке на тулбаре применяется API chrome.browserAction.

Для запуска основной функции через контекстное меню страницы применяется стандартный API chrome.contextMenus. Этим же API предоставляется доступ ко всем настройкам и дополнительным функциям.

Для локализации интерфейса контекстного меню, диалогов и сообщений применяется стандартный API chrome.i18n. Этот же API отвечает за локализацию имени и описания расширения в блоке аддона на странице chrome://extensions и за трансляцию описания горячей клавиши (через манифест).

Для вызова функции поиска по горячей клавише используется API chrome.commands.

С версии [2017.12.6] добавлена защита от удаления и автовосстановление URL поиска и редиректора.

С версии [2021.8.28] добавлена возможность работы с локальными файлами (опционально, потребуется включить соответствующую настройку в блоке аддона на странице chrome://extensions).

С версии [2021.9.8] для корректной работы функций прямой загрузки и просмотра файлов в манифесте аддона изменено опциональное разрешение [ "<all_urls>" ], теперь оно устанавливается не по желанию (как это было в предыдущей версии), а по умолчанию.

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

^{Щёлкните по изображению, чтобы просмотреть скриншот на другом языке.}

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

^{Щёлкните по изображению, чтобы просмотреть скриншот на другом языке.}

С версии [2021.9.18] для решения любых проблем с меню в аддон добавлена функция "Волшебной Кнопки" – ручного принудительного перестроения меню. Вызывается щелчком по кнопке на тулбаре (или по горячей клавише) на любой служебной странице браузера или на любой локальной странице.

После такого перестроения меню выдаётся сообщение:

^{Щёлкните по изображению, чтобы просмотреть скриншот на другом языке.}

С версии [2021.11.5] для корректной работы горячей клавиши на служебных страницах в браузерах версий старше CR31 в манифест аддона добавлено опциональное разрешение [ "<tabs>" ], оно не требуется в браузерах версий CR31+ и устанавливается только при явном подтверждении разрешения на доступ ко всем вкладкам.

В этой же версии окончательно определён подход к возможной проблеме некорректного запуска меню в браузерах версий старше CR36. Теперь решение проблемы явным образом отдаётся на усмотрение пользователя. :)

Локализация интерфейса и перевод на другие языки

Язык интерфейса: до версии 2021.9.8 – только русский (локализация жёсткая, зашита в коде), другие* локализации отсутствовали. Это было связано со значительным упрощением кода, а также с тем, что при создании расширения автор в первую очередь ориентируется на русскоязычных пользователей. На текущий момент, начиная с указанной версии, в аддоне имеется и вторая локализация, английская.

* Впрочем, если "дело пойдёт", прикрутить ещё и "басурманский" не является особой проблемой.
…и как вы уже поняли, с сентября 2021 года "процесс пошёл" и теперь для перевода на любой другой язык нужно только желание энтузиастов этого аддона, которые теперь могут сделать перевод хоть на албанский и использовать аддон на родном языке…)

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

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

В зависимости от текущей локали также меняется пояснение для горячей клавиши в настройках "Быстрых клавиш" и имя и описание расширения в его блоке на странице chrome://extensions:

^{Щёлкните по изображению, чтобы просмотреть скриншот на другом языке.}

В связи с добавкой в аддон локализации, URL пользовательского поиска по умолчанию также зависит от локали. Для англоязычных (en, en‑US, en‑GB) это домен google.com, для остальных локалей автоматически устанавливается региональный поисковик (для зоны ru, соответственно, это google.ru).

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

При смене языковой локали в браузере следует обязательно сделать перезапуск* для перестроения меню!

* Например, выбрав пункт "Перезагрузить и устранить ошибки" (в английской локали "Fast Restart and Reset any errors"):

^{Щёлкните по изображению, чтобы просмотреть скриншот на другом языке.}

Такая необходимость обусловлена тем, что в общем* случае построение меню производится однократно и только при установке или обновлении версии.

* Если версия браузера новее CR47 или если не используется режим стартового автопостроителя меню.

Исходя из сказанного, при смене языковой локали во всех браузерах лучше разово перезапустить расширение, чем удивляться "а почему я переключил на русский, а оно на английском". Пример подобной "непонятки" отлично виден на приведённом выше скриншоте. :)

Во избежание вопросов из серии "у меня всё равно не получается", следует помнить, что:

0. Самый простой способ ручного перестроения меню – это функция "Волшебной Кнопки", работающая независимо от версии браузера или иных условий.

1. Начиная с версии 2021.11.5 перезагрузка через указанный выше пункт является штатным способом принудительного перестроения меню в любом случае, независимо от смены локали. Теперь это работает независимо от версии браузера и способа установки расширения

2. Если расширение установлено "обычным способом" (из загруженного CRX‑файла), для перестроения меню при изменении текущей локали браузера можно просто переустановить* аддон обновлением поверх установленной версии, любым способом, например – перетаскиванием CRX‑файла нужной версии на страницу chrome://extensions. Никакие настройки при этом не теряются, но меню будет автоматически перестроено по языку текущей локали браузера.

* Этот вариант всегда сработает корректно и применим ко всем версиям браузеров.

2А. В случае установки в режиме разработчика (Developer Mode) вы можете использовать стандартную* функцию браузера в этом режиме, нажав ссылку-кнопку "Обновить" в блоке расширения на странице chrome://extensions.

* Этот вариант всегда сработает корректно и применим к любым версиям браузеров. Действие, по сути, аналогично обновлению аддона путём переустановки поверх, меню при этом будет автоматически пересоздано с учётом текущей локали браузера.

3. В браузерах версий до CR48 переустановка или ручной перезапуск НЕ потребуются, если был включен режим принудительного* стартового перестроения меню, оно автоматически перестраивается при каждом перезапуске.

Поддержка перевода на другие языки

Для локализации интерфейса расширения используется стандартный API и перевод на любой язык может быть выполнен простой добавкой в комплект аддона дополнительного текстового файла в формате JSON.

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

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

Короче, велкам… :)

Дополнительные примечания по исходному коду

Практических ограничений по версии браузера не имеется, используемые API работают в версиях 19+ (минимум для работы основных функций, для вызова по горячей клавише требуется версия 25+). Рекомендуемая "беспроблемная" версия с полной поддержкой всех функций аддона – не ниже 36+.

Исходный код текущей версии расширения можно просмотреть в режиме онлайн на любом из ресурсов, приведённых в материале Поиск статей на Sci-Hub : LBSC*.

* См.также: LBSC: Что это такое и как работать с этим архивом.

Об использовании расширения в браузерах версий старше CR49

При использовании "Find Docs in Sci-Hub RU" в браузерах достаточно старых версий возможна некорректная работа функции просмотра найденных статей. Это не является ошибкой расширения и связано с отсутствием в некоторых браузерах нативной поддержки файлов в формате PDF.

Подобная ситуация возможна при работе с любым браузером версии старше CR42. В частности, она наблюдается в браузере SRWare Iron 29. Подробнее об этой проблеме и способах её решения читаем в комментарии разработчика в разделе технической поддержки.

Кроме того, в достаточно старых браузерах не исключены и другие проблемы с доступом к базе данных сервиса Sci-Hub, обусловленные применением современных технологий (скрипты, стили и т.д.). Это не связано с ошибками в аддоне и зависит только от разработчиков самого сервиса и его сайтов.

Помимо перечисленных, в старых браузерах могут проявляться и проблемы, связанные с некорректной поддержкой применяемых в аддоне API или с теми или иными особенностями конкретных версий. Это также не связано с ошибками в аддоне и зависит только от отдельных версий (и даже сборок). Некоторая часть таких проблем решена при разработке, однако, эти решения требуют написания и поддержки "лишнего" кода, не требующегося в браузерах версий CR49+.

В общем и целом, инженерное тестирование этого расширения (на этапе разработки) в браузерах версий старше CR49 проводится по остаточному принципу и в большинстве случаев связано только с проверкой общей работоспособности основных ключевых функций аддона и только если эти версии заявлены в числе поддерживаемых.

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

Тем не менее, при реальной необходимости полная поддержка может быть добавлена и для достаточно старых версий браузеров путём дополнительной доработки исходного кода. Эта доработка может быть выполнена автором на условиях частного партнёрства с конкретным заказчиком (по обоюдной договорённости).