ご覧のページは、お客様の利便性のために一部機械翻訳されています。また、ドキュメントは頻繁に更新が加えられており、翻訳は未完成の部分が含まれることをご了承ください。最新情報は都度公開されておりますため、必ず英語版をご参照ください。翻訳に問題がある場合は、こちらまでご連絡ください。

カスタム要素をデータセットに接続する

Liferay DXP 2026.Q3+

リリース機能

重要

データセットマネージャは、リリース機能フラグ (LPS-164563) の背後にあります。データセットを作成し、このチュートリアルで使用するフィールドにアクセスするには、これを有効にしてください。 FDSConnection API とサンプルクライアント拡張機能はフラグによって制限されません。

カスタム要素クライアント拡張機能は、同じページ上のデータセットの検索クエリを設定できます。例えば、 liferay-sample-custom-element-7 サンプルは検索フィールドをレンダリングし、データセットと同期させます。サンプルは独立したウィジェットであるため、データセットの管理バーを使用する代わりに、ページ上の任意の場所に検索フィールドを配置できます。

前提条件

liferay-sample-custom-element-7 クライアント拡張機能を使用するには、

サポートされているバージョンの Java をインストールしてください。

サンプルワークスペースをダウンロードして解凍してください。

curl -o com.liferay.sample.workspace-latest.zip https://repository.liferay.com/nexus/service/local/artifact/maven/content\?r\=liferay-public-releases\&g\=com.liferay.workspace\&a\=com.liferay.sample.workspace\&\v\=LATEST\&p\=zip

com.liferay.sample.workspace-latest.zip を解凍します。

Liferay DXP の新しいインスタンスを起動するには、以下を実行します。
```
docker run -it -m 8g -p 8080:8080 liferay/dxp:2026.q1.9-lts
```
http://localhost:8080 に、メールアドレス test@liferay.com とパスワード test を使用して Liferay にサインインします。プロンプトが表示されたら、パスワードを learn に変更してください。
LPS-164563 リリース機能フラグを有効にします。
接続先のデータセットを作成します。データセットの作成を参照してください。
データセットをページに追加します。ページにデータセットを追加するを参照してください。

これで、最初のデータセット検索カスタム要素をデプロイするためのツールが揃いました。しかし、まずはそのコードを調べてみよう。

カスタム要素クライアント拡張機能を調べます

カスタム要素の例は、サンプルワークスペースの client-extensions/liferay-sample-custom-element-7/ フォルダーにあります。その client-extension.yaml ファイルには、以下の詳細が定義されています。

assemble:
    - from: build/static
        into: static
liferay-sample-custom-element-7:
    friendlyURLMapping: liferay-sample-custom-element-7
    htmlElementName: liferay-sample-custom-element-7
    instanceable: true
    name: Liferay Sample Custom Element 7
    portletCategoryName: category.client-extensions
    type: customElement
    urls:
        - index.*.js
    useESM: true

クライアント拡張機能は、その ID (liferay-sample-custom-element-7)、そのタイプ (customElement)、ブラウザがレンダリングする HTML タグ (htmlElementName)、および urls がビルドによって生成される JavaScript リソース (index.*.js を指すことを宣言します。 assemble ブロックは、 build/static フォルダーを、ビルドされた index.*.js ファイルを含む静的リソースとして、クライアント拡張機能の .zip ファイルにパッケージ化します。詳細については、カスタム要素YAML構成リファレンスを参照してください。

name プロパティはページエディターに表示されるウィジェット名であり、 portletCategoryName はそのウィジェットをクライアント拡張機能カテゴリに配置します。 instanceable: trueを使用すると、ウィジェットをページに複数回追加できます。 friendlyURLMapping プロパティはウィジェットに独自の URL を与えますが、このシナリオでは使用されません。 useESM: true を使用すると、Liferay はクライアント拡張機能の JavaScript を ES モジュールとしてロードします。 ESモジュールのみが、ページのインポートマップを介してベアモジュール指定子を解決できます。このサンプルでは、この方法によって実行時にデータセット接続APIに到達します。

コードを理解する

サンプル数は少ないものの、データセットに接続するカスタム要素が必ず処理しなければならない4つの重要な要素を網羅しています。以下の各セクションでは、それらのうちの1つを取り上げています。

ターゲット選択: 要素がどのデータセットを駆動するかをどのように学習するか。
接続設定: 接続を開き、データセットの検索クエリを追跡する方法。
接続ライフサイクル: ナビゲーション中も購読状態を維持し、削除時にクリーンアップする方法。
モジュール解決: ビルド時と実行時に接続 API がどのように解決されるか。

HTML属性からターゲットデータセットを読み取る

src/index.tsx ファイルはカスタム要素を登録し、 fds-name HTML 属性からターゲットデータセットを読み取ります。属性が存在しない場合は定数にフォールバックします。

import React from 'react';
import {Root, createRoot} from 'react-dom/client';

import App from './App';

const DEFAULT_FDS_NAME =
	'com_liferay_frontend_data_set_sample_web_internal_portlet_FDSSamplePortlet-classic';

const ELEMENT_NAME = 'liferay-sample-custom-element-7';

class LiferaySampleCustomElement extends HTMLElement {
	private _root?: Root;

	connectedCallback() {
		const fdsName = this.getAttribute('fds-name') || DEFAULT_FDS_NAME;

		this._root = createRoot(this);
		this._root.render(<App fdsName={fdsName} />);
	}

	disconnectedCallback() {
		this._root?.unmount();
	}
}

if (!customElements.get(ELEMENT_NAME)) {
	customElements.define(ELEMENT_NAME, LiferaySampleCustomElement);
}

データセットマネージャで作成するデータセットの場合、 fds-name の値は、その外部参照コードです。データセットの詳細タブにある「データセット外部参照コード」フィールドからそのコードをコピーしてください。データセットの管理を参照してください。

注記

DEFAULT_FDS_NAME フォールバックは、Liferay のフロントエンドデータセットサンプルウィジェットがレンダリングするデータセットを対象とするため、異なるパターンを使用します。

つながりを築く

src/App.tsx ファイルは、 @liferay/frontend-data-set-web/api モジュールから接続 API をインポートします。

import {
	FDSConnection,
	FDSConnectionInfo,
	FDSConnectionStatus,
} from '@liferay/frontend-data-set-web/api';

new FDSConnection(fdsName, fdsStateChangeCallback, onFDSConnectionInfoChange, options?) を使用して接続を構築します。 fdsStateChangeCallback 引数は、 検索 コールバックを保持するオブジェクトです。 Liferayは接続が準備できたときにそのコールバックを一度だけ呼び出すため、コンポーネントはデータセットの現在のクエリから開始し、その後変更があるたびに再度呼び出されます。 onFDSConnectionInfoChange 引数は、 {fdsName、instanceId、status} の形状のオブジェクトを受け取ります。 options.timeout を渡して、デフォルトの接続タイムアウト 10000 ms を上書きします。

接続には3つの方法があります。

getSearch() はデータセットの現在のクエリを返します。
setSearch(query) はデータセットに新しいクエリを書き込みます。
disconnect() は接続を終了します。

接続の状態は、 接続中、 準備完了、 タイムアウト、または 切断済み です。 getSearch() と setSearch(query) は、ステータスが readyでない限りショートサーキットします。これは、接続が完了する前のウィンドウと disconnect() 以降のすべてをカバーします。ステータスが 準備完了 になるまで、コントロールを無効にしたままにしてください。

タイムアウト ステータスは、接続がページ上で fdsName に一致するデータセットを見つけられなかったことを意味します。外部参照コードの入力ミスが一般的な原因です。

このサンプルでは、各ステータスを入力プレースホルダーにマッピングします。

const PLACEHOLDERS: Record<FDSConnectionStatus, string> = {
	connecting: 'waiting',
	disconnected: 'Search is not available',
	ready: '検索クエリを入力してください...',
	timeout: 'Search is not available',
};

このサンプルでは、言語キーを使用する代わりに、これらの文字列と検索ボタンのラベルを英語でハードコーディングしています。

このサンプルでは、 useEffect で fdsNameをキーとして接続を作成し、ステータス変更ごとにプレースホルダーと無効状態を更新し、クリーンアップ関数で切断します。

useEffect(() => {
	fdsConnectionRef.current = new FDSConnection(
		fdsName,
		{
			search: (query: string) => {
				setQuery(query);
			},
		},
		(fdsConnectionInfo: FDSConnectionInfo) => {
			setPlaceholder(PLACEHOLDERS[fdsConnectionInfo.status]);
			setDisabled(fdsConnectionInfo.status !== 'ready');
		}
	);

	return () => {
		if (fdsConnectionRef?.current) {
			fdsConnectionRef?.current.disconnect();
			fdsConnectionRef.current = null;
		}
	};
}, [fdsName]);

レンダリングされたインターフェースはテキスト入力と検索ボタンで、どちらもステータスが 準備完了 になるまで無効になっています。 handleSearch 関数は fdsConnectionRef.current?.setSearch(query)を呼び出し、入力は Enter キーでもトリガーします。

接続ライフサイクルに従う

disconnect() メソッドは、検索サブスクリプションを破棄し、ナビゲーションハンドルをデタッチし、 切断 ステータスを報告します。 FDSConnection は、Liferay の beforeNavigate イベントにも接続し、 disconnect() を呼び出します。これにより、シングルページアプリケーション（SPA）のナビゲーション全体にわたるサブスクリプションの管理から解放されます。ページから移動して戻ってくると、カスタム要素は単一のサブスクリプションを使用してデータセットに再接続します。サンプルでは、アンマウント時に disconnect() も呼び出します。

データセットは検索クエリをページURLに保存するため、フィルタリングされたビューをブックマークしたり共有したりすることができ、ブラウザの戻るボタンと進むボタンで検索結果間を移動できます。

ビルド時と実行時にAPIモジュールを解決する

@liferay/frontend-data-set-web/api 指定子は、ビルド時と実行時で異なる解決をします。

Liferayは、すべてのページにインポートマップを書き込みます。インポートマップとは、ブラウザの機能の一つで、ベアモジュール指定子を、それを提供するURLにマッピングするものです。これにより、実行時にブラウザはLiferayが提供する実装をロードします。

ビルド時に、サンプルの tsconfig.json は、同じ指定子を @liferay/js-api パッケージで公開されている型定義にマッピングします。

"compilerOptions": {
    "paths": {
        "@liferay/frontend-data-set-web/api": [
            "./node_modules/@liferay/js-api/data-set"
        ]
    }
}

サンプル内の `package.json`にあるビルドスクリプトでは、その指定子を `external` としてマークしているため、ブラウザはインポートマップからモジュールを解決し、バンドルにはそのコピーが含まれません：

"ビルド": "esbuild src/index.tsx --bundle --entry-names=[name].[hash] --external:@liferay/frontend-data-set-web/api --external:react --external:react-dom --format=esm --outdir=build/static"

ReactとReact DOMが外部ライブラリである理由は同じで、Liferayはどちらも実行時に提供するからです。

あなたのコードはどちらの場合でもインポート文を1つ書き込んでいます。サンプルの package.json pins "@liferay/js-api": "^0.7.1" は型定義用です。

カスタム要素クライアント拡張機能をLiferayにデプロイする

Liferayインスタンスが起動している状態で、サンプルワークスペース内の client-extensions/liferay-sample-custom-element-7/ フォルダから次のコマンドを実行します。

../../gradlew clean deploy -Ddeploy.docker.container.id=$(docker ps -lq)

これによりクライアント拡張機能がビルドされ、zipファイルがLiferayの deploy/ フォルダにデプロイされます。 Liferay SaaSへのデプロイを含む完全なデプロイワークフローについては、 Liferayへのクライアント拡張機能のデプロイを参照してください。

Liferayインスタンスのコンソールで、デプロイが成功したことを確認してください。

liferaysamplecustomelement7_ を開始しました...

カスタム要素をデータセットに接続する

まず、カスタム要素に必要な識別子をコピーします。

グローバルメニュー (を開き、 コントロールパネルを選択し、 データセット をクリックします。
データセットをクリックし、「詳細」タブを選択してください。
読み取り専用のデータセット外部参照コードフィールドの値をコピーします。
データセットが表示されているサイトページに移動し、編集を開始してください。
Liferay Sample Custom Element 7ウィジェットをページに追加します。
ウィジェットの オプション () をクリックし、設定を選択します。
コピーしたコードを使用して、プロパティフィールドに fds-name=<data set external reference code> と入力します。

プロパティフィールドは、1 行につき 属性=値 のペアを 1 つ取ります。 fds-name の値は、カスタム要素が駆動するデータセットを決定します。
をクリックして保存します。
をクリックして公開 します。

データセットの読み込みが完了すると、カスタム要素の入力欄と検索ボタンが有効になります。接続が確立されている間、入力には 待機 プレースホルダーが表示されます。接続準備が整うと、プレースホルダーは になります。検索クエリを入力してください....

カスタム要素を確認する

カスタム要素とデータセットの検索が同期していることを確認してください。

カスタム要素の検索フィールドにクエリを入力し、検索をクリックします。同じ値がデータセットの検索フィールドに表示され、データセットの検索結果を絞り込みます。
データセットの検索バーにクエリを入力してください。同じ値がカスタム要素の入力フィールドに表示されます。

ヒント

入力が無効のままで、 検索は利用できませんと表示される場合、接続でデータセットが見つかりませんでした。外部参照コードが正しいこと、データセットがページ上にあること、および LPS-164563 機能フラグが有効になっていることを確認してください。 FDSConnection も、接続タイムアウトの警告をブラウザのコンソールにログ出力し、試行した値を明示します。

最後に、データセットに組み込まれている検索バーを削除できます。
データセット アプリケーションに移動し、データセットの編集を開始して、設定タブに移動します。
検索を表示 をオフにして、保存をクリックします。
データセットが掲載されているサイトページに戻ります。データセットの上にある検索バーは消えているはずです。
カスタム要素を使用してデータセットをフィルタリングします。