コンポーネント
4D のコンポーネントとは、プロジェクトに追加可能な、1つ以上の機能を持つ 4Dコードや 4Dフォームの一式です。 たとえば、4D SVGコンポーネント は、SVGファイルの表示するための高度なコマンドと統合されたレンダリングエンジンを追加します。
独自の 4Dコンポーネントを 開発 し、ビルド することもできますし、4Dコミュニティによって共有されているパブリックコンポーネントを GitHubで見つけて ダウンロードすることもできます。
4D で開発する際、コンポーネントファイルはコンピューター上または Githubリポジトリ上に、透過的に保存することができます。
インタープリターとコンパイル済みコンポーネント
コンポーネントは、インタープリターまたは コンパイル済み のものが使えます。 コンポー ネントのパッケージフォルダーには以下のいずれかが含まれます:
- プロジェクトフォルダー (インタープリターのコンポーネント)
- または .4DZ ファイル (コンパイル済みコンポーネント)
インタープリターモードで動作する 4Dプロジェクトは、インタープリターまたはコンパイル済みどちらのコンポーネントも使用できます。 コンパイルモードで実行される 4Dプロジェクトでは、インタープリターのコンポーネントを使用できません。 この場合、コンパイル済みコンポーネントのみが利用可能です。
コンポーネントの読み込み
このページでは、4D と 4D Server 環境でのコンポーネントの使用方法について説明します。 他の環境では、コンポーネントの管理は異なります:
- リモートモードの 4D では、サーバーがコンポーネントを読み込み、リモートアプリケーションに送信します。
- 統合されたアプリケーションでは、コンポーネントは ビルドする際に組み込まれます。
概要
4Dプロジェクトにコンポーネントを読み込むには、以下の方法があります:
- プロジェクトの Components フォルダー にコンポーネントファイルをコピーします。
- または、プロジェクトの dependencies.json ファイルでコンポーネントを宣言します。これは、依存関係インターフェースを使用して依存関係を追加 するときに、ローカルファイルに対して自動的におこなわれます。
dependencies.json ファイルで宣言されているコンポーネントは、異なる場所に保存できます:
- 4Dプロジェクトのパッケージフォルダーと同じ階層 (デフォルトの場所です)
- マシン上の任意の場所 (コンポーネントパスは environment4d.json ファイル内で宣言する必要があります)
- GitHubリポジトリ (コンポーネントパスは、dependencies.json ファイルまたは environment4d.json ファイル、あるいはその両方で宣言できます)
同じコンポーネントが異なる場所にインストールされている場合、優先順位 が適用されます。
dependencies.json と environment4d.json
dependencies.json
dependencies.json ファイルは、4Dプロジェクトに必要なすべてのコンポーネントを宣言します。 このファイルは、4Dプロジェクトフォルダーの Sources フォルダーに置く必要があります。例:
/MyProjectRoot/Project/Sources/dependencies.json
このファイルには次の内容を含めることができます:
- デフォルトパス、または environment4d.json ファイルで定義されたパスに ローカル保存されている コンポーネントの名前
- GitHubリポジトリ に保存されているコンポーネントの名前 (パスはこのファイルまたは environment4d.json ファイルで定義できます)。
environment4d.json
environment4d.json ファイルは必須ではありません。 このファイルは、dependencies.json ファイル内で宣言された一部またはすべてのコンポーネントのついて、カスタムパス を定義するのに使用します。 このファイルは、プロジェクトパッケージフォルダーまたはその親フォルダーのいずれかに保存することができます (ルートまでの任意のレベル)。
このアーキテクチャーの主な利点は次のとおりです:
- environment4d.json ファイルをプロジェクトの親フォルダーに保存することで、コミットしないように選択できることです。これにより、ローカルでのコンポーネントの管理が可能になります。
- 複数のプロジェクトで同じ GitHubリポジトリを使用したい場合は、dependencies.json ファイルでそれを宣言し、environment4d.json ファイルで参照することができます。
優先順位
コンポーネントはさまざまな方法でインストールできるため、同じコンポーネントが複数の場所で参照される場合、優先順位が適用されます:
優先度高
- プロジェクトの Components フォルダー に置かれているコンポーネント
- dependencies.json**ファイルで宣言されたコンポーネント (ローカル環境を構成するために environment4d.json で指定されたパスは dependencies.json のパスをオーバーライドします)。
- 内部のユーザー4Dコンポーネント (4D NetKit、4D SVG など)
優先度低
同じコンポーネントの別のインスタンス (A) がより高い優先度レベルにあるためにコンポーネント (B) を読み込めない場合、AとBのコンポーネントにはそれぞれ専用の ステータス が付与されます: 読み込まれなかったコンポーネント (B) には Overloaded ステータス、読み込まれたコンポーネント (A) には Overloading ステータスが与えられます。
ローカルコンポーネント
ローカルコンポーネントは dependencies.jsonファイル にて次のように宣言します:
{
"dependencies": {
"myComponent1" : {},
"myComponent2" : {}
}
}
... 上記の "myComponent1" と "myComponent2" は読み込むコンポーネントの名前です。
デフォルトの (つまり、"myComponent1" と "myComponent2" が environment4d.json ファイルで宣言されていない) 場合、4D はコンポーネントのパッケージフォルダー (コンポーネントのプロジェクトルートフォルダーのこと) を 4Dプロジェクトのパッケージフォルダーと同じ階層に探します。例:
/MyProjectRoot/
/MyProjectComponentRoot/
このアーキテクチャーにより、プロジェクトと同じレベルにすべてのコンポーネントにコピーし、dependencies.json ファイルで参照することができます。
dependencies.json のアーキテクチャーを利用したくない場合は、プロジェクトの Components フォルダー にコンポーネントをコピーすることで、ローカルコンポーネントをインストールすることもできます。
コンポーネントパスのカスタマイズ
ローカルコンポーネントの場所をカスタマイズしたい場合は、プロジェクトフォルダーと同じ階層に保存されていない依存関係のパスを、environment4d.json ファイルに定義します。
相対パス または 絶対パス を使用できます (下記参照)。
例:
{
"dependencies": {
"myComponent1" : "MyComponent1",
"myComponent2" : "../MyComponent2",
"myComponent3" : "file:///Users/jean/MyComponent3"
}
}
environment4d.json ファイルで定義されたコンポーネントのパスが、プロジェクトの開始時に見つからない場合、コンポーネントは読み込まれず、Not found ステータス が表示されます。
相対パス vs 絶対パス
パスは、POSIXシンタックスで表します (POSIXシンタックス 参照)。
相対パスは、environment4d.json
ファイルを基準とした相対パスです。 絶対パスは、ユーザーのマシンにリンクされています。
コンポーネントアーキテクチャーの柔軟性と移植性のため、ほとんどの場合、相対パスを使用することが 推奨 されます (特に、プロジェクトがソース管理ツールにホストされている場合)。
絶対パスは、1台のマシンと 1人のユーザーに特化したコンポーネントの場合にのみ使用すべきです。
GitHub に保存されたコンポーネント
GitHubリリースとして利用可能な 4Dコンポーネントを参照して、4Dプロジェクトに自動で読み込むことができます。
GitHub に保存されているコンポーネントに関しては、dependencies.json ファイルと environment4d.json ファイルの両方で同じ内容をサポートしています。
GitHubリポジトリの設定
GitHub に保存された 4Dコンポーネントを直接参照して使用するには、GitHubコンポーネントのリポジトリを設定する必要があります。
- ZIP形式でコンポーネントファイルを圧縮します。
- GitHubリポジトリと同じ名前をこのアーカイブに付けます。
- このリポジトリの GitHubリリース にアーカイブを統合します。
これらのステップは、4Dコードや GitHubアクションを使用することで簡単に自動化できます。
パスの宣言
GitHub に保存されているコンポーネントは dependencies.jsonファイル にて次のように宣言します:
{
"dependencies": {
"myGitHubComponent1": {
"github" : "JohnSmith/myGitHubComponent1"
},
"myGitHubComponent2": {}
}
}
... 上記の場合、"myGitHubComponent1" は宣言とパス定義の両方がされていますが、"myComponent2" は宣言されているだけです。 そのため、environment4d.json ファイルにパスを定義する必要があります:
{
"dependencies": {
"myGitHubComponent2": {
"github" : "JohnSmith/myGitHubComponent2"
}
}
}
"myGitHubComponent2" は複数のプロジェクトで使用できます。
タグとバージョン
GitHub ではリリースを作成するときに、タグ と バージョン を指定します。
- タグ はリリースを一意に参照するテキストです。 dependencies.json ファイル および environment4d.json ファイルでは、プロジェクトで使用するリリースタグを指定することができます。 たとえば:
{
"dependencies": {
"myFirstGitHubComponent": {
"github": "JohnSmith/myFirstGitHubComponent",
"tag": "beta2"
}
}
}
- リリースは バージョン によっても識別されます。 使用されるバージョニング方法は、最も一般的に使用される セマンティックバージョニング のコンセプトに基づいています。 各バージョン番号は次のように識別されます:
majorNumber.minorNumber.pathNumber
。 タグと同様に、プロジェクトで使用したいコンポーネントのバージョンを指定することができます。例:
{
"dependencies": {
"myFirstGitHubComponent": {
"github": "JohnSmith/myFirstGitHubComponent",
"version": "2.1.3"
}
}
}
バージョンは、使用できるバージョンを定義するために使用します。 標準的なセマンティックバージョン を使用します。 範囲は、最小値と最大値を示す 2つのセマンティックバージョンと演算子 ('< | > | >= | <= | =
') で定義します。 *
はすべてのバージョンのプレースホルダーとして使用できます。 ~ および ^ の接頭辞は、数字で始まるバージョンを定義し、それぞれ次のメジャーバージョンおよびマイナーバージョンまでの範囲を示します。
以下にいくつかの例を示します:
- "
latest
": GitHubリリースで "latest" バッジを持つバージョン。 - "
*
": リリースされている最新バージョン。 - "
1.*
": メジャーバージョン 1 の全バージョン。 - "
1.2.*
": マイナーバージョン 1.2 のすべてのパッチ。 - "
>=1.2.3
": 1.2.3 を含む、以降の最新バージョン。 - "
>1.2.3
": 1.2.3 を含まない、以降の最新バージョン。 - "
^1.2.3
": バージョン 1.2.3 を含む、以降の最新のバージョン1 (バージョン2未満であること)。 - "
~1.2.3
": バージョン 1.2.3 を含む、以降の最新のバージョン 1.2 (バージョン1.3未満であること)。 - "
<=1.2.3
": 1.2.3 までの最新バージョン。 - "
1.0.0 – 1.2.3
" または ">=1.0.0 <=1.2.3": 1.0.0 から 1.2.3 までのバージョン。 - "
<1.2.3 ||>=2
": 1.2.3 から 2.0.0 未満までを除いたバージョン。
タグやバージョンを指定しない場合、4D は自動的に "latest" バージ ョンを取得します。
プライベートリポジトリ
プライベートリポジトリにあるコンポーネントを統合したい場合は、アクセストークンを使用して接続するよう 4D に指示する必要があります。
これには、GitHubアカウントで リポジトリ へのアクセス権を持つ classic トークンを作成します。
詳細については GitHubトークンのインターフェース を参照ください。
次に、environment4d.json ファイルに "github" キーを挿入します:
{
"github": {
"token": "ghpXXXXXXXXXXXXUvW8x9yZ"
},
"dependencies": {
"mySecondGitHubComponent": {
"github": "JohnSmith/mySecondGitHubComponent"
}
}
}
依存関係のローカルキャッシュ
参照された GitHubコンポーネントはローカルのキャッシュフォルダーにダウンロードされ、その後環境に読み込まれます。 ローカルキャッシュフォルダーは以下の場所に保存されます:
- macOs:
$HOME/Library/Caches/<app name>/Dependencies
- Windows:
C:\Users\<username>\AppData\Local\<app name>\Dependencies
... 上記で <app name>
は "4D"、"4D Server"、または "tool4D" となります。
dependency-lock.json
プロジェクトの userPreferences
フォルダー に dependency-lock.json
ファイルが作成されます。
このファイルは、依存関係・パス・url・読み込みエラー・その他の情報などをログに記録します。 これは、コンポーネントの読み込み管理やトラブルシューティングに役立ちます。
プロジェクトの依存関係の監視
開かれているプロジェクトでは、依存関係 パネルで依存関係の追加・削除ができるほか、現在の読み込み状態に関する情報を取得することができます。
依存関係パネルを表示するには:
-
4D では、デザイン/プロジェクト依存関係 メニューア イテムを選択します (開発環境)。
-
4D Server では、ウインドウ/プロジェクト依存関係 メニューアイテムを選択します。
依存関係パネルが表示されます。 依存関係は ABC順にソートされます。
依存関係インターフェースでは、依存関係を管理することができます (4Dシングルユーザーと4D Server)。 ローカル と GitHub の依存関係を追加または削除できます。
ローカルな依存関係の追加
ローカルな依存関係を追加するには、パネルのフッターエリアにある + ボタンをクリックします。 次のようなダイアログボックスが表示されます:
ローカル タブが選択されていることを確認し、... ボタンをクリックします。 標準の "ファイルを開く" ダイアログボックスが表示され、追加するコンポーネントを選択できます。 .4DZ または .4DProject ファイルを選択できます。
選択した項目が有効であれば、その名前と場所がダイアログボックスに表示されます。
選択された項目が有効でない場合は、エラーメッセージが表示されます。
プロジェクトに依存関係を追加するには、追加 をクリックします。
- プロジェクトパッケージフォルダーの隣 (デフォルトの場所) にあるコンポーネントを選択すると、dependencies.jsonファイル内で宣言されます。
- プロジェクトのパッケージフォルダーの隣にないコンポーネントを選択した場合、そのコンポーネントは dependencies.json ファイルで宣言され、そのパスも environment4d.json ファイルで宣言されます (注記参照)。 依存関係パネルでは、相対パスまたは絶対パス のどちらを保存するか尋ねられます。