Перейти к основному содержанию

Использование Libraries API 3.x (для разработчика)

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

Зачем использовать API библиотек в Drupal 8?

В ядре Drupal 8 представлены улучшенные инструменты управления библиотеками (library.yml и загрузка унифицированной библиотеки), поэтому некоторые задаются вопросом, зачем все еще нужен модуль API библиотек. Несмотря на эти изменения, ядро ​​по-прежнему не предлагает решения для обработки зависимостей внешних библиотек, которые могут использоваться несколькими расширениями, что является основной проблемой, на которой продолжает фокусироваться проект Libraries API. Любые проекты, зависящие от внешних и / или разделяемых библиотек, могут получить несколько важных преимуществ API библиотек, в том числе:

Избегайте конфликтов нагрузки . Ядро Drupal 8 не предлагает способа канонического объявления зависимостей общих библиотек (например, часто используемой библиотеки javascript). Если несколько расширений объявляют одну и ту же зависимость только через API ядра, могут возникнуть различные конфликты (проблемы с версиями, ошибки двойного включения и т. д.). API библиотек обеспечивает центральную структуру, позволяющую избежать этих проблем при использовании собственных API-интерфейсов ядра Drupal для фактической загрузки библиотеки.

Централизованное ведение метаданных библиотеки . В отличие от версий API библиотек для Drupal 7, метаданные библиотеки теперь отделены от расширений, которые их используют. Эти метаданные (ранее определенные в ) вместо этого считываются из  общего реестра, к которому можно получить удаленный и прозрачный доступ. Это обеспечит множество преимуществ, включая большую согласованность для разработчиков сайтов, использующих различные версии библиотечно-зависимых модулей.hook_libraries_info()

Расширенный API и инструментарий для разработчиков . Инструменты для определения версий, настраиваемого управления источниками библиотек и других преимуществ , которые всегда были частью проекта Libraries API, по-прежнему доступны, и их не нужно дублировать.

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

Историческое примечание : многие из общих примечаний, используемых для объяснения философии версии 7.x-2.x, также применимы к 8.x-3.x.

Примечание по библиотекам PHP : поскольку Drupal 8 полагается на Composer для автозагрузки и разрешения зависимостей библиотек PHP, библиотеки ресурсов являются основным вариантом использования API библиотек, хотя базовая поддержка для управления и загрузки библиотек PHP все еще включена.

Определения библиотеки

Чтобы быть полезным для других модулей, API библиотек требуется список известных библиотек и основные метаданные о каждой из них. В Drupal 7 информация библиотеки может быть предоставлена ​​независимыми от модулей информационными файлами, но, как отмечалось выше, это вызывает многочисленные несоответствия. В 8.x-3.x метаданные библиотеки управляются отдельно как переносимые файлы JSON, к которым можно получить доступ из множества мест. API изначально использует два места в «реестре» для этих определений:

Удаленный реестр (URL-адрес по умолчанию: https://git.drupalcode.org/project/libraries_registry/tree/8.x-1.x/registry/8 ) является «главным» источником определений библиотек, которые используются в нескольких Drupal. экземпляры и обычно доступны через http. Проект реестра библиотек - это попытка предоставить коллективный удаленный реестр для сообщества Drupal. Это также удаленный реестр, который API библиотек настроен для использования по умолчанию, хотя это можно настроить (можно ссылаться на любой URI, и можно объявить несколько удаленных реестров).

Локальный реестр (URI по умолчанию: public: // library-definitions /, обычно в / sites / all / files / library-definitions /) является локальным хранилищем файлов для каждого экземпляра для всех определений библиотек, необходимых для конкретного сайта. Это основной источник всех метаданных библиотеки во время выполнения любых операций. Когда требуется определение (например, установлен модуль, использующий API библиотек, или новая библиотека загружается в первый раз), удаленный реестр проверяется, и, если определение найдено, оно копируется в этот локальный реестр для постоянного использования.

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

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

Если файл определения еще не существует или файл, доступный в проекте реестра библиотек, требует модификации, вам потребуется создать новый файл определения. Пожалуйста, обратитесь к структуре определения библиотеки для уточнения деталей по этому поводу . Вы можете вручную поместить это определение в локальный реестр (обычно в / sites / all / files / library-definitions /) для любых экземпляров разработки, с которыми вы работаете, для немедленного использования. Как только файл определения будет завершен и вы будете готовы поделиться своим расширением (например, как выпуск на drupal.org), лучше всего отправить его обратно в проект реестра библиотек для универсального удаленного доступа на всех сайтах, которые будут использовать ваше расширение.

Применение

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

Базовая настройка

Сначала вам нужно будет объявить зависимость от API библиотек в вашем модуле или файле темы info.yml:

dependencies: - libraries

Фактические зависимости внешних библиотек также должны быть объявлены в файле info.yml с помощью ключа "library_dependencies" и последовательности имен машинных имен, например:

library_dependencies: - flexslider - jquery_mobile

Вы должны проинструктировать своих пользователей разместить внешние источники библиотеки в месте в их локальной файловой структуре Drupal, о котором известно API библиотек, обычно / sites / all / assets / vendor / [lib_machine_name] (для библиотек ресурсов) или / sites / all / библиотеки / [lib_machine_name] (для библиотек PHP). Вы можете добавить примечания об этом в документацию к вашему модулю или просто направить пользователей к  установке внешней библиотеки, которая требуется для страницы дополнительного модуля документации API библиотек. Конечно, вам также нужно будет убедиться, что исходные коды библиотеки правильно расположены в любых средах разработки, которые вы используете.

Загрузка библиотеки - Присоединение библиотек ресурсов

API библиотек использует основные концепции работы с библиотеками непосредственно для загрузки / присоединения библиотек ресурсов. Это означает, что все прилагаемые примечания из основной документации применимы напрямую. Например, чтобы загрузить библиотеку через свойство #attached массива рендеринга, вы можете использовать:

$build['the_element_that_needs_the_asset_library']['#attached']['library'][] = 'libraries/flexslider';

Важное примечание : прикрепленное значение всегда должно использовать «библиотеки» в качестве метки модуля. Это связано с тем, что внешняя библиотека была зарегистрирована канонически через API библиотек от имени вашего модуля и всех других модулей, которые также могут использовать ту же библиотеку.libraries/lib_machine_namemymodule/lib_machine_name

Загрузка библиотеки - включая библиотеки PHP

Для обеспечения паритета функций с версией этого модуля для Drupal 7 доступна базовая поддержка библиотеки PHP для загрузки списка файлов PHP по запросу. Как правило, рекомендуется использовать Composer и полностью избегать API библиотек для библиотек PHP, но в случаях, когда управление на основе Composer невозможно, библиотеки PHP могут быть включены через службу диспетчера библиотек. Простой вызов \ Drupal \ libraries \ ExternalLibrary \ LibraryManagerInterface :: load () включит все файлы, которые определены как часть библиотеки PHP, например:

\Drupal::service('libraries.manager')->load('php_library_machine_name');