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. 03Bitrix のローカライズとイベントサービス
  4. 04Pinia、Vuex、ルーティングの利用
  5. 05非同期・拡張可能なコンポーネント
  6. 06Vue 2 からの移行とデバッグ

活用シーン

  1. 01Bitrix 拡張機能での Vue UI 構築
  2. 02PHP ページへの 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）を使用し、ページ全体で 1 つの 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');
  • BitrixVue と、すべての Vue API（ref、computed、markRaw、defineComponent …）は ui.vue3 からインポートします（カーネルの標準であり、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); を設定します（開発時のみ）。開発ビルドと開発者ツールが有効になります。この設定を有効にすると、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 対応