bitrix-extensions

Bitrix JS/CSS 拡張機能

ベースライン：main 23.0+ · 検証済み：main 26.800.0、ui 26.687.0

ID → ディレクトリ

ID の各ドットはディレクトリ階層になります（Extension::getPath()）：vendor.module.editor → js/vendor/module/editor/。まず /local/js/、次に /bitrix/js/ が検索されます。セグメントは 2 つ以上必要で、それぞれ [a-z0-9_-] に一致する必要があります。ドットを含むディレクトリ（/local/js/vendor.module/editor/）は ID では読み込めません。

コード	場所
プロジェクト	/local/js/vendor/module/editor/ → ID vendor.module.editor
配布モジュール vendor.module	install/js/vendor/module/editor/。インストール時に /local/js/ へコピーされます
カーネル	/bitrix/js/<module>/<ext>/（ui.buttons）— 編集しないでください。同じパスのコピーを /local/js/ に置くと、そちらが優先され、更新されなくなります

public function InstallFiles(): void
{
    CopyDirFiles(__DIR__ . '/js', \Bitrix\Main\Application::getDocumentRoot() . '/local/js', true, true); // 4th arg = recursive
}

public function UnInstallFiles(): void
{
    DeleteDirFilesEx('/local/js/vendor/module'); // DeleteDirFiles() is flat, leaves nested dirs
}

レイアウト

/local/js/vendor/module/editor/
├── src/index.js         # ES6+ entry
├── dist/                # built bundles — commit and deploy
├── lang/ru/config.php   # optional $MESS phrases
├── bundle.config.js     # deploy too: server reads `namespace` from it
└── config.php

スキャフォールド：bitrix create。ビルド：拡張機能ディレクトリで bitrix build（@bitrix/cli）。

module.exports = {
    input: './src/index.js',
    output: './dist/editor.bundle.js',
    namespace: 'BX.Vendor.Module.Editor',
    browserslist: true,
};

• CSS：エントリーポイントで import './style.css'; を指定すると、dist/editor.bundle.css が生成されます。
• インポート：import { Loc, Runtime } from 'main.core';、旧 CoreJS 1.0 の場合は import 'main.date';。
• adjustConfigPhp: false でない限り、ビルド時にインポート内容に基づいて config.php の js、css、rel が書き換えられます。

config.php

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

return [
    'js' => './dist/editor.bundle.js',
    'css' => './dist/editor.bundle.css',
    'rel' => ['main.core', 'ui.buttons'],
    'skip_core' => false,
    'settings' => ['maxItems' => 50],
];

その他のキー：lang_additional（フレーズを計算）、oninit（呼び出し可能で、設定を受け取り、返します）、controllerEntrypoint（renderExtension() 用の JS 関数。bitrix-controllers を参照）。

JS での設定：Extension.getSettings('vendor.module.editor').get('maxItems', 20)（main.core）。

フレーズ

lang/ が存在する場合、カーネルは拡張機能とともに lang/<LANGUAGE_ID>/config.php を読み込み（lang キーは不要）、JS に公開します：Loc.getMessage('VENDOR_EDITOR_TITLE')。フレーズは 1 つのグローバルな BX.message を共有するため、コードにはベンダー名と拡張機能名をプレフィックスとして付けてください。

<?php
$MESS['VENDOR_EDITOR_TITLE'] = 'Editor';

読み込み

\Bitrix\Main\UI\Extension::load(['vendor.module.editor', 'ui.buttons']); // unknown ID = silent no-op

import { Runtime } from 'main.core';

Runtime.loadExtension('vendor.module.editor').then(({ Editor }) => {
    new Editor().render();
});

Runtime.loadExtension(...ids) は、要求された拡張機能の namespace からエクスポートをマージしたものを返す Promise を解決します。解決時には、JS/CSS/フレーズ/設定がページに読み込まれています。

チェックリスト

• ディレクトリのパスは、ドットを / に置き換えた ID と一致させます → /。モジュール拡張機能には vendor.module. をプレフィックスとして付けます。
• ID だけで読み込みます（Extension::load()、rel、Runtime.loadExtension()）。/local/js/… や /bitrix/js/… 内のファイルを <script src> / Asset::addJs() で読み込まないでください — 更新時にファイルの配置が変わることがあります（ui 26.675 では ui.actionpanel が dist/ に移動しました）。
• src/ の変更後に dist/ を再ビルドし、bundle.config.js も一緒にデプロイします。
• すべての依存関係を rel に記載します。
• UI の文字列は lang/<lang>/config.php に記述し、Loc.getMessage() で読み込みます。