mcpField
B
bitrix-extensions

bitrix-extensions

github.com/bxmaximum开发47268 次安装2 周前更新
代码仓库

关于 bitrix-extensions

bitrix-extensions 是面向 Bitrix 开发的技能，说明如何组织、构建、配置和加载 JavaScript/CSS 扩展，涵盖扩展 ID、依赖、语言资源及部署细节。

主要功能

  1. 01将扩展 ID 映射到目录
  2. 02构建 JavaScript 和 CSS 包
  3. 03配置依赖与设置
  4. 04按 ID 加载扩展
  5. 05管理本地化文本

适用场景

  1. 01创建 Bitrix 扩展
  2. 02打包分发模块
  3. 03在 PHP 或 JavaScript 中加载扩展
  4. 04部署更新后的包和配置

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/bxmaximum/bitrix-framework-skills --skill bitrix-extensions

安装后在 Claude Code 中输入/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.moduleinstall/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')。短语共用一个全局 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) 会在页面上加载 JS/CSS/短语/设置后，使用请求扩展的合并导出项（来自它们的 namespace）进行解析。

检查清单

  • 目录路径与 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() 读取。

评论

支持 Markdown