248  /  381

Создание новой библиотеки Bitrix Core JS

Просмотров: 902 (Статистика ведётся с 06.02.2017)
Анна Кокина
Сложность урока:
3 уровень - средняя сложность. Необходимо внимание и немного подумать.
1
2
3
4
5
Недоступно в редакциях:
Ограничений нет

Создание новой библиотеки Bitrix Core JS

Примечание: В данном уроке описывается новый формат Bitrix CoreJS библиотек.

Расположение и именование

Все библиотеки необходимо располагать в папке вашего модуля: /bitrix/modules/<module_name>/install/js/<module_name>/<library_name>/

Название создаваемой библиотеки должно отражать её предназначение. Название библиотеки может содержать:

  • латинские буквы в нижнем регистре (a-z)
  • цифры (0-9)
  • символ подчеркивания (_)

Подключение библиотеки

Подключить библиотеку можно одним из следующих способов:

  • В php-коде компонента (или страницы) сделать следующий вызов:
    \Bitrix\Main\UI\Extension::load('<module_name>.<library_name>');
    
  • Если эта библиотека используется в рамках другой библиотеки, указать её в зависимостях нужной библиотеки (в том числе и в библиотеках старого формата):
    'rel' => ['<module_name>.<library_name>']
    
  • Если эта библиотека используется не сразу (например, она может потребоваться только в редких случаях), то и загружать ее можно не сразу, а по мере необходимости через JavaScript метод:
    BX.loadExt('<module_name>.<library_name>').then(function() {
    	// вызов вашего кода
    });	
    

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

Структура библиотеки

/bitrix/modules/<module_name>/install/js/<library_name>/config.php
/bitrix/modules/<module_name>/install/js/<library_name>/<module_name>.<library_name>.bundle.js
/bitrix/modules/<module_name>/install/js/<library_name>/<module_name>.<library_name>.js
/bitrix/modules/<module_name>/install/js/<library_name>/<module_name>.<library_name>.bundle.css
/bitrix/modules/<module_name>/install/js/<library_name>/<module_name>.<library_name>.css
/bitrix/modules/<module_name>/install/js/<library_name>/lang/<lang>/config.php
/bitrix/modules/<module_name>/install/js/<library_name>/bundle.config.js

В файле config.php необходимо описать структуру библиотеки:

<?
if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED !== true)
{
	die();
}

return [
	'js' => [
		'/bitrix/modules/<module_name>/install/js/<library_name>/<module_name>.<library_name>.bundle.js',
	],
	'css' => [
		'/bitrix/modules/<module_name>/install/js/<library_name>/<module_name>.<library_name>.bundle.css',
	],
	'rel' => [
		'main.polyfill.complex',
	],
];

Доступные ключи:

  • js - путь до файла расширения;
  • css - путь до файла css расширения;
  • rel - список "зависимостей";
  • skip_core - при подключении расширения не требуется подключение core.js.
Примечание: Обратите внимание на зависимости: при подключении зависимости не нового формата (а старого), необходимо предварительно подключить через \Bitrix\Main\Loader::includeModule (исключения библиотеки главного модуля).

В файле <module_name>.<library_name>.js необходимо описать логику в формате ES6. Для него с помощью утилиты транспиляции будет создан файл <module_name>.<library_name>.bundle.js, который будет содержать код в формате ES5.

В файле <module_name>.<library_name>.css необходимо описать стили в формате CSS3. Для него будет с помощью утилиты транспиляции создан файл <module_name>.<library_name>.bundle.css, который будет содержать код в формате СSS3 + префиксы для старых браузеров.

Если в рамках вашей библиотеки вам необходимо использовать локализации, их можно расположить в /bitrix/modules/<module_name>/install/js/<library_name>/config.php, либо описать явно, откуда брать переводы через ключ 'lang' в файле config.php.

Примечание: Если вы не используете утилиты транспиляции, в файле config.php указывайте файлы без префикса bundle. Но если вы хотите модифицировать или скопировать расширения, написанные на ES6 и в которых есть bundle.config.js, использование транспилятора обязательно (подробнее читайте в уроке Использование ES6 Использование в старых браузерах

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

Подробнее...
).

В файле bundle.config.js описываются правила транспиляции (если у вас настроена утилита транспиляции).

module.exports = {
	input: './<module_name>.<library_name>.js',
	output: './<module_name>.<library_name>.bundle.js',
	namespaceFunction: null,
};

В ключе namespaceFunction можно указать null, если не нужно оборачивать все в namespace или "BX.namespace" (транспилятор автоматически создаст необходимые переменные).

Вложенные библиотеки

Библиотеки могут содержать вспомогательные библиотеки, которые могут быть подключены отдельно.

Полный путь в файловой системе:

`/bitrix/modules/<module_name>/install/js/<module_name>/<library_name>/<sub_library_name>/`

В таком формате вызов вашей библиотеки будет таким:

\Bitrix\Main\UI\Extension::load('<module_name>.<library_name>.<sub_library_name>');

либо

BX.loadExt('<module_name>.<library_name>.<sub_library_name>').then(...);

Количество вложенных папок не ограничено. Каждая новая папка должно быть указана в названии расширения через точку:

<module_name>.<library_name>.<sub_library_name>.<sub_library_name_2>.<sub_library_name_3>

В данном случае путь будет таким:

/bitrix/modules/<module_name>/install/js/<module_name>/<library_name>/<sub_library_name>/<sub_library_name_2>/<sub_library_name_3>/


2
Курсы разработаны в компании «1С-Битрикс»

Если вы нашли неточность в тексте, непонятное объяснение, пожалуйста, сообщите нам об этом в комментариях.
Развернуть комментарии