--- url: 'https://dxpr.com/ja/hc/documentation/learn-dxpr-builder/development/custom-elements' title: 'カスタムエレメントの作成 | DXPR' author: name: Jurriaan url: 'https://dxpr.com/users/jurriaan' date: '2026-10-24T11:28:05+00:00' copyright: 'Copyright DXPR. All rights reserved.' type: article summary: |- すべてのDXPR Builderエレメントはwindow.dxprBuilder.dxpr_elementsにプッシュされるJavaScriptオブジェクトです。エディターは各オブジェクトをStyle・Animationタブ付きのエレメントクラスに変換します。このページでは出荷エレメントがdxpr_builder/dxpr_elements.jsで定義される方法、モジュールが独自定義をエディターに追加する方法、結果のHTMLを示します。エレメントごとのサーバー側Twigテンプレートはありません。エレメントはブラウザーでレンダーされます。 エディターのエレメント登録方法 この順序で読み込まれ、dxpr_builder_library_info_build()(dxpr_builder.module内)でdxpr_builder/editor.builderライブラリーとして定義される6つのスクリプトです。 tags: - 'Bouw erop voort' image: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg' published: true og: site_name: DXPR updated_time: '2026-10-24T11:28:05+0000' 'image:alt': 'DXPR, powered by Drupal: AI-powered Drupal for marketers.' schema: '@context': 'https://schema.org' '@graph': - mainEntity: { } - '@type': TechArticle headline: カスタムエレメントの作成 description: |- すべてのDXPR Builderエレメントはwindow.dxprBuilder.dxpr_elementsにプッシュされるJavaScriptオブジェクトです。エディターは各オブジェクトをStyle・Animationタブ付きのエレメントクラスに変換します。このページでは出荷エレメントがdxpr_builder/dxpr_elements.jsで定義される方法、モジュールが独自定義をエディターに追加する方法、結果のHTMLを示します。エレメントごとのサーバー側Twigテンプレートはありません。エレメントはブラウザーでレンダーされます。 エディターのエレメント登録方法 この順序で読み込まれ、dxpr_builder_library_info_build()(dxpr_builder.module内)でdxpr_builder/editor.builderライブラリーとして定義される6つのスクリプトです。 image: '@type': ImageObject url: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg' width: '1200' height: '630' datePublished: '2026-10-24T11:28:05+0000' dateModified: '2026-10-24T11:28:05+0000' author: '@type': Organization '@id': 'https://dxpr.com/#organization' name: DXPR url: 'https://dxpr.com/' logo: '@type': ImageObject url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg' width: '1348' height: '501' publisher: '@type': Organization '@id': 'https://dxpr.com/#organization' name: DXPR url: 'https://dxpr.com/' logo: '@type': ImageObject url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg' width: '1348' height: '501' mainEntityOfPage: 'https://dxpr.com/ja/hc/documentation/learn-dxpr-builder/development/custom-elements' articleSection: 'Bouw erop voort' - '@type': WebPage '@id': 'https://dxpr.com/ja/hc/documentation/learn-dxpr-builder/development/custom-elements' description: |- すべてのDXPR Builderエレメントはwindow.dxprBuilder.dxpr_elementsにプッシュされるJavaScriptオブジェクトです。エディターは各オブジェクトをStyle・Animationタブ付きのエレメントクラスに変換します。このページでは出荷エレメントがdxpr_builder/dxpr_elements.jsで定義される方法、モジュールが独自定義をエディターに追加する方法、結果のHTMLを示します。エレメントごとのサーバー側Twigテンプレートはありません。エレメントはブラウザーでレンダーされます。 エディターのエレメント登録方法 この順序で読み込まれ、dxpr_builder_library_info_build()(dxpr_builder.module内)でdxpr_builder/editor.builderライブラリーとして定義される6つのスクリプトです。 breadcrumb: '@type': BreadcrumbList itemListElement: - '@type': ListItem position: 1 name: ホーム item: 'https://dxpr.com/ja' publisher: '@type': Organization '@id': 'https://dxpr.com/#organization' name: DXPR inLanguage: ja --- [Help Center](/ja/node/75)/[Documentation](/ja/hc/documentation) /[Learn DXPR Builder](/hc/documentation/learn-dxpr-builder) /[Extend](/hc/documentation/learn-dxpr-builder/extend) /[Bouw erop voort](/hc/documentation/learn-dxpr-builder/extend/build-on-it) # カスタムエレメントの作成. Learn DXPR BuilderExtendBouw erop voort ## In this guide Related guides - [Hooks APIリファレンス](/ja/hc/documentation/learn-dxpr-builder/development/hooks-api) - [アーキテクチャ](/ja/hc/documentation/learn-dxpr-builder/development/architecture) すべてのDXPR Builderエレメントは`window.dxprBuilder.dxpr_elements`にプッシュされるJavaScriptオブジェクトです。エディターは各オブジェクトをStyle・Animationタブ付きのエレメントクラスに変換します。このページでは出荷エレメントが`dxpr_builder/dxpr_elements.js`で定義される方法、モジュールが独自定義をエディターに追加する方法、結果のHTMLを示します。エレメントごとのサーバー側Twigテンプレートはありません。エレメントはブラウザーでレンダーされます。 ## エディターのエレメント登録方法 この順序で読み込まれ、`dxpr_builder_library_info_build()`(`dxpr_builder.module`内)で`dxpr_builder/editor.builder`ライブラリーとして定義される6つのスクリプトです。 1. `dxpr_templates.js`：`dxpr_builder/templates/`からコンパイルされたクライアント側twig.jsテンプレート。 2. `dxpr_global.js`：共有ヘルパーとCKEditor 5統合。 3. `dxpr_events.js` 4. `dxpr_param_types.js`：入力タイプごとに1オブジェクトを`window.dxprBuilder.dxpr_param_types`にプッシュ。 5. `dxpr_elements.js`：`window.dxprBuilder.dxpr_elements`配列を作り、エレメントごとに1定義をプッシュ。 6. `dxpr_builder.js`：エディター。このファイルの実行時に`create_dxpr_elements()`を呼び出し、`window.dxprBuilder.dxpr_elements`をループして各定義で以下を実行します。 - 呼び出すのは`register_animated_element(base, is_container, Class)`で、クラスが`AnimatedElement`を拡張します(Styleタブ、Animationタブ、HTML ID、HTMLクラス、配置パラメーター)。 - 継承パラメーターを定義の`params`に追加します。 - 全パラメーターを`make_param_type()`で変換します。`param.type`を登録済みパラメータータイプと照合します。 - 定義のプロパティをクラスのプロトタイプに混ぜ込みます。 定義は`dxpr_elements.js`の実行後、`dxpr_builder.js`の実行前に配列にある必要があります。6ファイルはすべて`defer`属性で読み込まれるため、scriptタグの文書順序が実行順序です。 ## エレメント定義 例は`dxpr_builder/dxpr_elements.js`のAlertエレメントです(ソース：`dxpr_builder/build/dxpr-elements/elements/az_alert.js`)。全エレメントに必要なプロパティに絞っています。オリジナルは`el_class`、`onCancel`ハンドラー、`focusout`リスナーも設定します。 ```javascript window.dxprBuilder.dxpr_elements.push({ base: "az_alert", name: Drupal.t("Alert"), nameEn: "Alert", icon: "az-custom-icon az-alert-icon", largeSettingsWindow: true, hidden: false, params: [ { type: "textarea", heading: Drupal.t("Message"), param_name: "content", value: Drupal.t( "This is a placeholder text. Your actual content will go here. Edit this to include your own information.", ), }, { type: "dropdown", heading: Drupal.t("Type"), param_name: "type", description: Drupal.t("Select message type."), getText: (opt) => opt.text, getValue: (opt) => opt.value, getDefault: (param) => param.value["alert-success"].value, value: { "alert-success": { text: Drupal.t("Success"), value: "alert-success" }, "alert-info": { text: Drupal.t("Info"), value: "alert-info" }, "alert-warning": { text: Drupal.t("Warning"), value: "alert-warning" }, "alert-danger": { text: Drupal.t("Danger"), value: "alert-danger" }, }, passthrough: true, }, ], show_settings_on_create: true, has_content: true, render(...args) { const state = { class: `az-element az-alert alert ${this.attrs.type} ${this.get_el_classes()} ${this.get_content_classes()}`, style: this.attrs.style, message: this.attrs.content, }; this.dom_element = this.baseclass.prototype.render_template( "elements/alert/alert", state, ); this.baseclass.prototype.render.apply(this, args); }, save_history() { const container = this.get_my_container(); container.save_container_history(Drupal.t("Edit alert")); }, }); ``` | プロパティ | 目的 | |---|---| | `base` | マシン名。保存HTMLには`data-azb="az_alert"`として書き込まれ、ページの再解析時にクラス検索に使われます。`az_`プレフィックスを保ちます。 | | `name`、`nameEn` | エレメントピッカーのラベルとその未翻訳形。 | | `icon` | ピッカーアイコン用のCSSクラス。出荷アイコンは`dxpr_builder/sass/dxpr-builder-backend/components/_custom-icons.scss`で定義されます。カスタムエレメントはアイコンクラス用の独自CSSが必要です。 | | `category` | ピッカータブ。レイアウトエレメントは`Drupal.t("Layout")`を使い、ブロックとビューは`"CMS"`を使います。既定のコンテンツタブでは省略します。 | | `is_container` | `true`はエレメントが他のエレメントを保持する場合。 | | `largeSettingsWindow` | 設定ダイアログを大きいサイズで開きます。 | | `hidden` | レンダー可能に保ったままピッカーからエレメントを隠します。 | | `params` | ダイアログに表示される設定。以下を参照。 | | `show_settings_on_create` | エレメントのドロップ直後に設定ダイアログを開きます。 | | `has_content` | エレメントは編集可能なコンテンツ領域を持ちます(`dom_content_element`)。 | | `render(...args)` | 構築するのは`this.dom_element`で、`this.attrs`から。ベースの`render`を呼び出します。 | | `save_history()` | ラベル付きで元に戻すエントリーをプッシュします。 | | `parse_attrs_from_dom(element)` | 任意。保存マークアップからパラメーター値を読み戻します。`skip_data_azb`と`skip_params`と一緒に使い、値を``属性に保存するもので、`data-azat-*`を使わないImageなどのエレメント向けです。 | ### パラメーター 各項目は`params`に以下を持ちます。 | キー | 意味 | |---|---| | `type` | 登録済みパラメータータイプのいずれか(次の節)。 | | `heading` | フィールドラベル。 | | `param_name` | キーは`this.attrs`内で、保存HTMLでは`data-azat-`属性です。`content`は特別で、属性ではなくエレメント本体です。 | | `value` | 初期値。`dropdown`では`getText`、`getValue`、`getDefault`コールバック付きのオプションオブジェクトです。 | | `description` | フィールド下のヘルプテキスト。 | | `tab` | 名前付きアコーディオンにフィールドをまとめます。例：`Drupal.t("SEO")`。 | | `can_be_empty` | 属性を削除せず空文字を保存します。 | | `safe` | 保存値のURLエンコードを飛ばします。 | パラメータータイプは`type`の値で、`window.dxprBuilder.dxpr_param_types`(`dxpr_builder/dxpr_param_types.js`内)にプッシュされます。`boxmodel`、`checkbox`、`checkboxes`、`colorpicker`、`datetime`、`dropdown`、`dxb_slider`、`html`、`icon`、`image`、`images`、`link`、`links`、`numericfield`、`row_layout`、`saved_datetime`、`social_links`、`textarea`、`textfield`、`video`です。登録しないタイプは通常のテキスト入力(`BaseParamType`)にフォールバックします。 全エレメントが継承する`param_name`を再利用しません。例：`color`、`background`、`el_class`、`hash`、`an_*`アニメーション名。Styleタブが`color`を所有済みのため、その名の2つ目のパラメーターが`data-azat-color`に書き込まれることはありません。 ### 保存内容 `update_data()`(`dxpr_builder.js`内)はエレメントをHTMLに書き込みます。 - `data-azb=""`はルートエレメントに。 - `data-azat-=""`は初期値と異なる値の全パラメーターに。パラメーターが`safe: true`を設定しない限りURLエンコードされます。 - Styleタブのパラメーターはインライン`style`とクラスとして。`data-azat-*`属性にはなりません。 - `data-azcnt="true"`は`has_content`設定時にコンテンツエレメントに。 エディターを受け取らない閲覧者はこのHTMLを`data-az*`属性なしで受け取ります。`DxprBuilderService::parseDocumentForCleanup()`が除去します。アニメーション付きエレメントとCarouselなどの組み込み動的エレメントに保持する固定リストを除きます。エレメントが訪問者向けJavaScriptやCSSを要する場合、ルートに`data-dxpr-builder-libraries=""`属性を付けます。`parseDocumentForTemplateLibrary()`はスラッシュなしの全キーに`dxpr_builder/elements.`を添付します。キーは`dxpr_builder.libraries.yml`の`elements.*`ライブラリーです。スラッシュ付きキーは登録済みアイコンセットの`library`である場合のみ有効です。 ## 最小動作例 例では選択色で段落をレンダーする「Notice」エレメントを追加します。`dxpr_templates.js`のコンパイル済みtwig.jsテンプレートはエディターバンドルの一部で他モジュールから拡張できないため、DOMを直接構築します。 1. 作るのは`mymodule/js/notice-element.js`です。 ```javascript window.dxprBuilder.dxpr_elements.push({ base: "az_notice", name: Drupal.t("Notice"), nameEn: "Notice", icon: "az-custom-icon az-alert-icon", params: [ { type: "textfield", heading: Drupal.t("Text"), param_name: "text", value: Drupal.t("Notice text"), }, { type: "colorpicker", heading: Drupal.t("Colour"), param_name: "notice_color", value: "#0d6efd", }, ], show_settings_on_create: true, render(...args) { const el = document.createElement("div"); el.className = `az-element az-notice ${this.get_el_classes()}`; if (this.attrs.style) { el.setAttribute("style", this.attrs.style); } const p = document.createElement("p"); p.style.color = this.attrs.notice_color; p.textContent = this.attrs.text; el.appendChild(p); this.dom_element = el; this.baseclass.prototype.render.apply(this, args); }, save_history() { this.get_my_container().save_container_history(Drupal.t("Edit notice")); }, }); ``` 2. ファイルをエディターライブラリーに挿入します。`dxpr_elements.js`(重み`-4`)と`dxpr_builder.js`(重み`-3`)の間で、`mymodule.module`内に。 ```php /** * Implements hook_library_info_alter(). */ function mymodule_library_info_alter(array &$libraries, string $extension): void { if ($extension === 'dxpr_builder' && isset($libraries['editor.builder'])) { $path = '/' . \Drupal::service('extension.list.module')->getPath('mymodule'); $libraries['editor.builder']['js'][$path . '/js/notice-element.js'] = [ 'weight' => -3.5, 'preprocess' => FALSE, 'attributes' => ['defer' => TRUE], ]; } } ``` `preprocess: FALSE`と`defer`はモジュールが独自ファイル用に定義するエントリーと一致するため、エディターアセットがCDN由来でもローカルビルド由来でもファイルの順序位置を保ちます。 3. キャッシュをクリアしてBuilderページを開きます。 ```bash drush cr ``` 4. ピッカーからエレメントを追加し、テキストと色を設定して保存します。フィールドの保存内容です。 ```html

Hello

``` 訪問者は`data-az*`属性なしで同じマークアップを受け取ります。段落はインライン色を保つため、このエレメントに訪問者用ライブラリーは不要です。 ## 把握すべき制限 - **プロフィールはカスタムエレメントを列挙しません。**Builderプロフィールのエレメントチェックリストは`src/Form/DxprBuilderProfileForm.php`と`src/Service/Handler/ProfileHandler.php`の固定リストから来ます。その外のエレメントはプロフィールで隠れません。 - **ピッカーのアイコン**はモジュールからのCSSが必要です。Builder出荷の`az-custom-icon`クラスは出荷エレメントのみを対象とします。 - **`DxprBuilderService::getDxprElementsFolders()`**と`hook_dxpr_builder_elements_folders_alter()`はテーマ内の`elements`フォルダーの一覧を返しますが、エディターは何も読み取りません。登録ルートではありません。 - **StyleとAnimationタブ**は`register_animated_element()`が追加します。そのパラメーターを再定義しません。 ## 次のステップ - [フックAPI](/hc/documentation/learn-dxpr-builder/development/hooks-api)：ユーティリティークラスとアイコンセットを追加するPHPフックに。 - [アーキテクチャー](/hc/documentation/learn-dxpr-builder/development/architecture)：エディターとフィールドフォーマッターの連携に。