Расширения

Расширение — способ организации JS и CSS кода в 1С-Битрикс: Управление Сайтом и Битрикс24. Расширения помогают организовать код, обеспечивая его модульность и управляемость. Они позволяют объединять файлы JavaScript и CSS в бандлы, что упрощает их загрузку и использование в браузере. Бандлы — это объединенные файлы, которые помогают оптимизировать загрузку ресурсов.

Расположение расширений

Расширения, которые поставляются с продуктами 1С-Битрикс: Управление Сайтом и Битрикс24, расположены в директории bitrix. Клиентские расширения обычно размещаются в папке local.

/bitrix/js/<module>/<extension>/
/local/js/<module>/<extension>/

Структура

Пример структуры расширения myextension:

src — исходные файлы.
dist — бандлы для браузера.
bundle.config.js — конфигурационный файл для сборщика.
config.php — конфигурационный файл экстеншна.
lang — локализации.
test — тесты.
@types — файлы *.d.ts.

Обязательные элементы: src, dist, bundle.config.js, config.php.

Необязательные элементы: директории lang, test, @types.

Если у вас установлен консольный инструмент @bitrix/cli, то структуру расширения можно создать, выполнив команду bitrix create.

Директория src

В директории src размещаются исходные файлы в формате ES6. Из этих файлов на основании данных файла конфигурации и внутренних ссылок будут созданы финальные версии в формате ES5 — бандлы. Они используются для подключения в браузере.

Внутри файла можно использовать import других файлов из текущей директории или импортировать другие CoreJS расширения.

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

если в папке src есть файл file.js с экспортируемым классом SomeClass
```
import {SomeClass} from "./file";
        
```
для импорта file.css
```
import './file.css';
        
```

для импорта CoreJS 2.0

import {Loader} from 'main.loader';

для импорта библиотеки из CoreJS 1.0
```
import "main.date";
        
```

Директория dist

В директории dist располагаются файлы, автоматически созданные с помощью сборщика для последующего подключения в браузере. Обычно это файлы <extension>.bundle.js и <extension>.bundle.css.

Файл bundle.config.js

Файл конфигурации сборщика.

Базовая конфигурация.
```
module.exports = {
        	input: './src/app.js', 
        	output: './dist/app.bundle.js',
        };
        
```
В данном файле конфигурации не указываются файлы CSS. Их необходимо импортировать в файле, который указан в параметре input — точке входа сборки.
```
// Файл из input — src/app.js
        import './style.css';  // импорт CSS
        
```

Все параметры.

module.exports = {
        	// Файл, для которого необходимо выполнить сборку. 
        	// Необходимо указать относительный путь 
        	input: string, 
        	
        	// Путь к бандлу, который будет создан в результате сборки. 
        	// Обычно это ./dist/<extension_name>.bundle.js
        	// Необходимо указать относительный путь 
        	output: string || {js: string, css: string},
        	
        	// Неймспейс, в который будут добавлены все экспорты из файла, 
        	// указанного в input. Например, 'BX.Main.Filter'
        	namespace: string,
        	
        	// Списки файлов для принудительного объединения. 
        	// Файлы будут объединены без проверок на дублирование кода. 
        	// sourcemap's объединяются автоматически. 
        	// Необходимо указать относительные пути
        	concat: {
        		js: Array<string>,
        		css: Array<string>,
        	},
        	
        	// Разрешает или запрещает сборщику модифицировать config.php.
        	// По умолчанию true (разрешено)
        	adjustConfigPhp: boolean,
        	
        	// Разрешает или запрещает сборщику удалять неиспользуемый код. 
        	// По умолчанию true (включено)
        	treeshake: boolean,
        	
        	// Разрешает или запрещает пересобирать бандлы, 
        	// если сборка запущена не в корне текущего расширения. 
        	// По умолчанию `false` (разрешено)
        	'protected': boolean,
        	
        	plugins: {
        		// Переопределяет параметры Babel.
        		// Можно указать собственные параметры Babel
        		// https://babeljs.io/docs/en/options
        		// Если указать false, то код будет собран без транспиляции
        		babel: boolean | Object,
        		
        		// Дополнительные плагины Rollup, 
        		// которые будут выполняться при сборке бандлов 
        		custom: Array<string | Function>,
        	},
            // Определяет правила обработки путей к изображениям в CSS.
            // Доступно с версии 3.0.0
            cssImages: {
                // Определяет правило, по которому изображения должны 
                // быть обработаны:
                // 'inline' — преобразует изображения в инлайн 
                // 'copy' — копирует изображения в директорию 'output'
                // По умолчанию 'inline'
                type: 'inline' | 'copy', 
                // Путь к директории, в которую должны быть скопированы 
                // используемые изображения 
                output: string,
                // Максимальный размер изображений в кб, которые могут быть 
                // преобразованы в инлайн.
                // По умолчанию 14кб
                maxSize: number,
                // Использовать ли svgo для оптимизации svg. 
                // По умолчанию true 
                svgo: boolean, 
            },
            resolveFilesImport: {
                // Путь к директории, в которую должны быть скопированы 
                // импортированные изображения 
                output: string,
                
                // Определяет разрешенные для импорта типы файлов.
                // По умолчанию ['**/*.svg', '**/*.png', '**/*.jpg', '**/*.gif']
                // https://github.com/isaacs/minimatch
                include: Array<string>,
                // По умолчанию []
                exclude: Array<string>,
            },
            
            // Определяет правила Browserslist: 
            // false — не использовать (по умолчанию)
            // true — использовать файл .browserslist / .browserslistrc
            browserslist: boolean | string | Array<string>,
          
            // Включает или отключает минификацию. 
            // По умолчанию отключено. 
            // Может принимать объект настроек Terser:
            // false — не минифицировать (по умолчанию)
            // true — минифицировать с настройками по умолчанию 
            // object — минифицировать с указанными настройками 
            minification: boolean | object,
          
            // Включает или отключает преобразование нативных JS классов. 
            // По умолчанию значение параметра выставляется автоматически 
            // на основании browserslist
            transformClasses: boolean,
          
            // Включает или отключает создание Source Maps файлов 
            sourceMaps: boolean,
            
            // Настройки тестов 
            tests: {
                // Настройки локализации 
                localization: {
                    // Код языка локализации. По умолчанию 'en'
                    languageId: string,
                    // Включает или выключает автозагрузку фраз в тестах. 
                    // По умолчанию включено 
                    autoLoad: boolean,
                },
            },
        };

Файл config.php

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

При использовании @bitrix/cli файл config.php будет автоматически создан при сборке и будет обновляться по мере необходимости. Например, если в коде JS появится зависимость, которая не указана в config.php, она будет автоматически добавлена в rel.

Базовая конфигурация.

if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED !== true)
        {
        	die();
        }
        return [
        	'css' => './dist/loader.bundle.css',
        	'js' => './dist/loader.bundle.js',
        	'rel' => [
        		'main.core'
        	]
        ];

Все параметры.

...
        return [
        	// Путь к `css` файлу или массив путей 
        	// Рекомендуем указывать относительный путь 
        		'css' => String | Array<String>,
        	
        	// Путь к `js` файлу или массив путей к `js` файлам 
        	// Рекомендуем указывать относительный путь 
        	'js' => String | Array<String>,
        	
        	// Список зависимостей
        	// Необходимо указать имена расширений, которые должны быть 
        	// подключены перед подключением текущего расширения
        	// Зависимости подключаются рекурсивно и с учетом указанного порядка 
        	'rel' => String | Array<String>,
        	
        	// Путь к файлу с языковыми фразами или массив путей. 
        	// Файл `lang//config.php` подключается автоматически, 
        	// здесь его можно не указывать
        	'lang' => String | Array<String>,
        	
        	// Запрещает подключать `main.core` автоматически как зависимость.
        	// По умолчанию `false` — `main.core` подключается. 
        	// При сборке бандла значение параметра устанавливается автоматически,
        	// если в коде нет прямой зависимости на `main.core`
        	'skip_core' => Boolean,
        	
        	// Обработчик, который вызывается перед подключением расширения на странице.
        	// В качестве первого параметра будет передан массив конфигурации расширения.
        	// Обработчик может модифицировать этот массив и вернуть из функции.
        	// Это полезно, когда необходимо добавить в языковые фразы 
        	// какие-то данные с сервера
        	'oninit' => Function,
        	
        	// Дополнительные языковые фразы.
        	// Это полезно для передачи вычисляемых значений языковых фраз.
        	// Принимает массив. В качестве ключей необходимо указывать идентификаторы языковых фраз
        	'lang_additional' => Array<string, string>,
        	// Параметр доступен с версии 20.5.100 модуля main.
        	// Параметр позволяет указать настройки,
        	// которые могут быть получены в JS
        	// с помощью метода Extension.getSettings().
        	'settings' => Array
        ];

Директория @types

Директория может содержать файлы <name>.d.ts с описанием публичного JS API расширения на TypeScript. Рекомендуем использовать файлы *.d.ts для описания API библиотек, написанных на ES5. Описывать код ES6 не нужно.

Пример описания расширения main.loader.

declare module 'main.loader' 
        {
        	type loaderOptions = {
        		target?: HTMLElement,
        		size?: number,
        		mode?: 'absolute' | 'inline' | 'custom',
        		offset?: {
        			top?: string,
        			left?: string
        		},
        		color?: string
        	};
            
        	class Loader 
        	{
        		constructor(options?: loaderOptions);
        		readonly layout: HTMLElement;
        		readonly circle: HTMLElement;
        		createLayout(): HTMLElement;
        		show(target?: HTMLElement): Promise<any>;
        		hide(): Promise<any>;
        		isShown(): boolean;
        		setOptions(options: loaderOptions): void;
        		destroy(): void;
        	}
        }

Директория test

Директория должна содержать вложенные директории и файлы Mocha-тестов. Для каждого файла необходимо создать директорию с именем тестируемого файла и файлом с тестами в формате <sourceName>.test.js.

Если структура src имеет вид:

src
- entity
  - column.js
  - row.js
- app.js

Директория test должна иметь следующую структуру:

test
- entity
  - column
    - column.test.js
  - row
    - row.test.js
- app
  - app.test.js

Использование расширений

В PHP загрузите и подключите расширение на странице с помощью метода\Bitrix\Main\UI\Extension::load. Этот метод принимает в качестве параметра имя расширения либо массив имен.

\Bitrix\Main\UI\Extension::load('main.loader');

В JS можно импортировать экспорты расширения или выполнить отложенное подключение.

Импорт экспортов расширения.
```
import {Loader} from 'main.loader';
        
```
Если вы хотите импортировать старое расширение, которое не поддерживает import ES6, укажите импорт без экспорта расширения.
```
import "main.date";
        
```
При импорте расширения в JS сборщик автоматически добавляет это расширение как зависимость в config.php.
Отложенное подключение.
```
import {Runtime} from 'main.core';
        Runtime.loadExtension('main.loader').then((exports) => {
        	// Код, который использует `main.loader`
        	// В `exports` будут все экспорты из `main.loader`
        });
        
```
Отложенная загрузка полезна, когда функционал используется на странице не сразу. Например, когда пользователь откроет всплывающее окно или выполнит какое-нибудь действие.

Компоненты

Объект приложения и контекст

Расширения

Расположение расширенийРасположение расширений

СтруктураСтруктура

Директория srcДиректория src

Директория distДиректория dist

Файл bundle.config.jsФайл bundle.config.js

Файл config.phpФайл config.php

Директория @typesДиректория @types

Директория testДиректория test

Использование расширенийИспользование расширений