mcpField
B
bitrix-vue

bitrix-vue

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

关于 bitrix-vue

面向 Bitrix 开发者的 Vue 3 使用指南，介绍如何通过 `ui.vue3` 在扩展或 PHP 页面中创建应用，并使用 Bitrix 提供的组件和服务。内容还涵盖 Vue 2 迁移、状态管理及调试。

主要功能

  1. 01通过 `ui.vue3` 创建 Vue 3 应用
  2. 02在扩展和 PHP 页面中加载
  3. 03使用 Bitrix 本地化与事件服务
  4. 04接入 Pinia、Vuex 和路由
  5. 05异步及可扩展组件支持
  6. 06Vue 2 迁移与调试

适用场景

  1. 01在 Bitrix 扩展中构建 Vue 界面
  2. 02在 PHP 页面挂载 Vue 应用
  3. 03将旧版 `ui.vue` 代码迁移至 Vue 3

安装

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

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

安装后在 Claude Code 中输入/bitrix-vue确认已加载。

详细介绍

BitrixVue 3

基线：main 23.0+ · 已验证：main 26.800.0，ui 26.687.0

ui.vue3 = Vue 3 + BitrixVue 插件（$Bitrix），整个页面共用一个 Vue。运行时模板编译；不使用 SFC .vue，不支持 SSR。Vue 2（ui.vue、全局 BX.BitrixVue）已过时——不要用它编写新代码。

在扩展中使用（首选）

import { BitrixVue, ref } from 'ui.vue3';

BitrixVue.createApp({
    setup() {
        return { items: ref([]) };
    },
    mounted() {
        BX.ajax.runAction('vendor:module.item.list').then((r) => {
            this.items = r.data.items;
        });
    },
    template: `
        <h2>{{ $Bitrix.Loc.getMessage('VENDOR_ITEMS_TITLE') }}</h2>
        <div v-for="item in items" :key="item.id">{{ item.name }}</div>
    `,
}).mount('#vendor-items');
  • 从 ui.vue3 导入 BitrixVue 和所有 Vue API（ref、computed、markRaw、defineComponent 等）（内核规范路径，不是 ui.vue3.bitrixvue）；rel: ['ui.vue3'] 即可。
  • 扩展设置和短语：bitrix-extensions。

在 PHP 页面中使用（无需构建）

\Bitrix\Main\UI\Extension::load('ui.vue3');

<div id="vendor-app"></div>
<script>
    BX.Vue3.BitrixVue.createApp({ template: '<div>Hello</div>' }).mount('#vendor-app');
</script>

全局对象是 BX.Vue3.BitrixVue。BX.BitrixVue 属于 Vue 2：此处未定义；若页面同时加载了 ui.vue，则会静默使用 Vue 2。

$Bitrix（每个组件中可用）

成员用途
$Bitrix.Loc.getMessage(code, {'#N#': n})短语（来自 BX.message）；Vue 外的 JS：从 main.core 导入 Loc
$Bitrix.eventEmitter应用级 EventEmitter
$Bitrix.Data.get/set应用级共享数据
$Bitrix.RestClient.get() / $Bitrix.PullClient.get()默认 REST / Pull 客户端（bitrix-pull）

BitrixVue.getFilteredPhrases(this, 'VENDOR_')——Vue 3 中第一个参数是组件实例（文档展示的是不带此参数的 Vue 2 用法）。

内核组件

  • 组件：ui.vue3.components.*（button、popup、hint、switcher 等），例如 import { Counter } from 'ui.vue3.components.counter'（components: { Counter } → <Counter :value="5"/>；自 ui 26.200* 起提供；备用方案：自行封装 ui.cnt）。小部件选项：bitrix-ui。
  • 状态管理和路由：ui.vue3.pinia、ui.vue3.vuex、ui.vue3.router。
  • 延迟加载组件：BitrixVue.defineAsyncComponent('vendor.module.heavy', 'HeavyForm') 会在首次渲染时加载该扩展。
  • 可扩展组件：BitrixVue.mutableComponent(name, def)；其他代码可通过 mutateComponent() / cloneComponent() 更改它。

Vue 中的内核小部件

Popup / Menu / Dialog / Popover / ActionPanel 实例应保持非响应式：this.popup = markRaw(new Popup(...))，或将它们保存在 data() 之外。自 ui 26.650 起重建的小部件使用原生 #private 字段；通过响应式 Proxy 访问时会抛出 TypeError: Cannot read private member。

调试

在 /local/php_interface/init.php 中设置 define('VUEJS_DEBUG', true);（仅开发环境）→ 使用开发版构建 + devtools；启用后，VUEJS_LOCALIZATION_DEBUG 会显示短语代码而不是文本。

从 Vue 2（ui.vue）迁移

  • BX.BitrixVue / import … from 'ui.vue' → ui.vue3。
  • BitrixVue.component() / .directive() 不会在 Vue 3 中注册（会在控制台报错）：请使用本地 components: {}、app.component() 或 mutableComponent()。
  • getFilteredPhrases(prefix) → getFilteredPhrases(this, prefix)；destroyed → unmounted；不支持过滤器，也不支持 $on / $off。

检查清单

  • 仅使用 ui.vue3；所有导入均来自 ui.vue3；内联脚本使用 BX.Vue3.BitrixVue。
  • 内核小部件实例使用 markRaw() 包装。
  • 通过 $Bitrix.Loc / Loc 获取短语，绝不硬编码。
  • 服务端调用使用 BX.ajax.runAction（包含 CSRF），不要直接使用 fetch。
  • 在 unmounted 中移除 Pull 订阅。

评论

支持 Markdown