1. 仮想DOMアーキテクチャを使用したOracle JETアプリケーションの開発
  2. Oracle JET VComponentベースのWebコンポーネントの使用

4 Oracle JET VComponentベースのWebコンポーネントの使用

Oracle JET VComponentベースのWebコンポーネントは、カスタムHTML要素として埋め込むことができる、再利用可能なユーザー・インタフェース・コードの単位です。Webコンポーネントには、Oracle JETコンポーネント、他のWebコンポーネント、HTML、JavaScriptおよびCSSが含まれます。独自のWebコンポーネントを作成するか、ページに追加できます。

Webコンポーネントの作成

Oracle JETでは、カスタムWebコンポーネントの様々なコンポーネント・タイプがサポートされます。スタンドアロンWebコンポーネントを作成できます。または、一緒に使用するためのWebコンポーネントのセットを作成できます。その後、それらをJETパックすなわちパック・コンポーネント・タイプとしてアセンブルできます。リソース・コンポーネントを作成してJETパックを拡張できるのは、厳密にUIコンポーネントではないアセットの再利用可能なライブラリがあるときです。また、スタンドアロン・コンポーネントでサードパーティ・コードを参照する必要がある場合は、参照コンポーネントを作成して、そのコードへのポインタを定義できます。

スタンドアロンWebコンポーネントの作成

Oracle JETコマンドライン・インタフェース(CLI)を使用して、コンテンツを移入できるOracle JET Webコンポーネント・テンプレートを作成します。CLIを使用しない場合、WebコンポーネントのファイルとフォルダをOracle JETアプリケーションに手動で追加できます。

次の手順では、Webコンポーネントを作成するための大まかなステップを示します。

始める前に:

Webコンポーネントを作成するには:

  1. Webコンポーネントの名前を決定します。
    Webコンポーネントの仕様では、カスタム要素の名前が次のように制限されます。

    • 名前にはハイフンを含める必要があります。

    • 名前は小文字のASCII文字で始める必要があります。

    • 名前には大文字のASCII文字を使用できません。

    • 他のコンポーネントの名前と競合するリスクを減らすため、名前には一意の接頭辞を含めるようにしてください。

      お薦めのパターンとしては、コンポーネント名の最初のセグメントとして組織の名前を使用します。たとえば、org-component-name。名前は、予約済のojおよびnsネームスペースのルートに対応する接頭辞oj-またはns-で始めることはできません。

    • 名前には予約名を使用できません。Oracle JETでは、ojおよびnsのネームスペースと接頭辞も予約されています。

  2. 次のいずれかのオプションを使用して、Webコンポーネントの配置先を決定します。

    • Oracle JET CLIで作成した既存のOracle JETアプリケーションにWebコンポーネントを追加します。

      この方法を使用する場合は、CLIを使用して、Webコンポーネントのコンテンツを格納するために必要なフォルダとファイルを含むWebコンポーネント・テンプレートを作成します。

    • Oracle JET CLIを使用しない既存のOracle JETアプリケーションにWebコンポーネントを手動で追加します。

      この方法を使用する場合は、Webコンポーネントのコンテンツを格納するフォルダとファイルを手動で作成します。

  3. 前のステップでの選択に応じて次のいずれかのタスクを実行し、Webコンポーネントを作成します。

    • Oracle JET CLIを使用してアプリケーションを作成した場合は、アプリケーションの最上位ディレクトリのターミナル・プロンプトで、次のコマンドを入力してWebコンポーネント・テンプレートを生成します:

      ojet create component component-name

      たとえば、doc-hello-worldという名前のWebコンポーネントを作成するには、ojet create component doc-hello-worldと入力します。このコマンドは、Webコンポーネントのスタブ・コンテンツを含むファイルとともに、アプリケーションのsrc\components\フォルダにdoc-hello-worldを追加します。

      VComponentソース・ファイル

      oracleconfig.jsonファイルのcomponentsプロパティの値によって、Oracle CLIでWebコンポーネントを生成するフォルダの場所が決まります。デフォルト値はcomponentsですが、別の値に変更できます。

    • Oracle JET CLIを使用しない場合は、アプリケーションのsrcフォルダ内にフォルダを作成し、作成する各Webコンポーネントの名前を含むフォルダを追加します。

  4. Oracle JET CLIを使用しない場合は、loader.js RequireJSモジュールを作成し、それをWebコンポーネントのルート・フォルダに配置します。

    loader.jsモジュールは、Webコンポーネントの依存性を定義し、コンポーネントのクラス名(この例ではDocHelloWorld)を登録します。 

    export { DocHelloWorld } from "./doc-hello-world";
  5. Webコンポーネントで使用されるカスタム・スタイルを構成します。

    • スタイルが2、3個しかない場合は、それらをWebコンポーネントのルート・フォルダにあるweb—component-name-styles.cssに追加します(必要な場合はこのファイルを作成します)。

      たとえば、DocHelloWorld Webコンポーネントは、コンポーネントの表示、幅および高さのスタイルを定義します。 

      /* This prevents the flash of unstyled content before the Web 
   Component properties have been setup. */
doc-hello-world:not(.oj-complete) {
  visibility: hidden;
}

doc-hello-world {
   min-height: 50px;
   width: 50px;
}
    • Oracle JETツールを使用してアプリケーションを作成し、Sassを使用してCSSを生成する場合は次のようにします。

      1. 必要に応じて、アプリケーションの最上位ディレクトリのターミナル・プロンプトで、次のコマンドを入力し、node-sassをアプリケーションに追加します: ojet add sass。

      2. web—component-name-styles.scssを作成し、Webコンポーネントの最上位レベルのフォルダ内に置きます。

      3. web—component-name-styles.scssを有効なSCSS構文で編集し、ファイルを保存します。

        この例では、変数でデモ・カードのサイズが定義されます。
        $doc-hello-world-size: 200px;

/* This prevents the flash of unstyled content before the 
   Web Component properties have been setup. */
doc-hello-world:not(.oj-complete) {
  visibility: hidden;
}

doc-hello-world {
  width: $doc-hello-world-size;
  min-height: $doc-hello-world-size;
}
  6. Webコンポーネントのドキュメントを追加する場合は、Webコンポーネントのルート・フォルダにあるREADME.mdにコンテンツを追加します(必要な場合はこのファイルを作成します)。

    README.mdファイルには、コンポーネントの概要と適切に書式設定された例を含めるようにしてください。コンポーネントのコンシューマに提供する追加情報があれば、それも含めます。READMEファイル形式の推奨される標準は、Markdownです。

JETパックの作成

コンシューマが選んだコンポーネントが1つ以上のコンポーネントに関連する可能性がある場合、JETパックを作成するとプロジェクト管理が単純化されます。個々のJETパックで、特定のバージョンの参照コンポーネントが必要になることがあります。

基本的に、JETパックは関連するWebコンポーネントのライブラリです。それらのアセットが直接含まれるわけではなく、コンポーネントの特定バージョン・ストライプの索引として存在します。

ノート:

関連するコンポーネントの参照メカニズムとしてのパックには例外が1つあります。パックには、1つ以上のRequireJSバンドル・ファイルを含めることができます。これは、最適化された形式のコンポーネント・セットを、少数の物理的ダウンロードにパッケージ化したものです。ただし、これは常に、Oracle Component Exchangeで独立エンティティとして提供される実際のコンポーネントと合せて使用されます。

JETパックで参照されるコンポーネントは一緒に使用するためのものであり、その使用方法は個別のコンポーネント・バージョンによって制限されます。したがって、作成するJETパックによって、各コンポーネントの特定のバージョンと、同じセット内の他のコンポーネントの特定の固定バージョンとの関係が結ばれます。つまり、JETパックそのものに「バージョン・ストライプ」があり、これによってユーザーがアプリケーションにインポートする特定のコンポーネントが決まります。個々のコンポーネントのバージョン番号は異なる可能性があるため、JETパックによって、コンシューマが自らのアプリケーションとパック全体のバージョン(パックに含まれる個別のコンポーネントではない)を関連付けることが保証されます。

  1. アプリケーションのルート・フォルダからJETツールを使用してJETパックを作成します。
    ojet create pack my-pack

    パック名については慎重に検討してください。この名前がそのパック内のすべてのコンポーネントの接頭辞になるためです。

    ツールによって、ユーザーが変更する必要のあるテンプレート・ファイルを含むフォルダ構造が追加されます:

    /(working folder)
  /src
    /components
      /my-pack
  2. アプリケーションのルート・フォルダからJETツールを使用して、JETパックにバンドルするコンポーネントを作成します。指定するコンポーネント名は、パック内で一意である必要があります。
    ojet create component my-widget-1 --pack=my-pack

    ツールによって、コンポーネント・フォルダ/my-widget-1がmy-packルート・フォルダにネストされます。新しいコンポーネント・ファイルはスタンドアロンWebコンポーネント用に作成されるファイルと似ています。 

    
/(working folder)
  /src
    /components
      /my-pack
          component.json
          /my-widget-1
          |   loader.ts
	   |   my-widget-1-styles.css
	   |   my-widget-1.tsx
	   |   README.md
	   |
	  +---resources
	   |   /---nls
	   |     /---root
	   |           my-widget-1-strings.ts
	   |
	  /---themes

    loader.tsには、次の例のように、新しいコンポーネントのVComponentモジュール・クラスをエクスポートする1行のエントリが含まれています:

    export { MyWidget1 } from "./my-widget-1";

  3. オプションで、「JETパックのリソース・コンポーネントの作成」に従って作成した任意のリソース・コンポーネントについて、コンポーネント用の独自のcomponent.jsonファイルを含む作業フォルダをパック・ファイル構造に追加します。

    ツールによって、コンポーネント・フォルダ/my-widget-1がmy-packルート・フォルダにネストされます。新しいコンポーネント・ファイルはスタンドアロンWebコンポーネント用に作成されるファイルと似ています。 

    /(working folder)
  /src
    /components
        /my-pack
          component.json
          /my-widget-1
            /resources
              /nls
                /root
                  my-widget-1-strings.js
            component.json
            loader.ts
            README.md
            my-widget-1.tsx
            my-widget-1-styles.css
          /my-resource-component-1
            component.json
            /converters
              file1.js
              ...
            /resources
              /nls
               /root 
                string-file1.js
            /validators
              file1.js
              ...
  4. オプションで、パックの対象コンポーネントで必要なバンドルを生成します。詳細は、https://requirejs.org WebサイトのRequireJSのドキュメントを参照してください。

    ヒント:

    RequireJSを使用して、パック・コンポーネントの最適化されたバンドルを作成できます。こうすると、実行時に利用側アプリケーションが各コンポーネントを別々にダウンロードするかわりに、複数のコンポーネントを含む1つのJavaScriptファイルをダウンロードできます。ほとんど常に一緒に使用されるコンポーネント・セットがある場合にはこの機能を使用することをお薦めします。必要に応じて使用可能なコンポーネントをグループ化するために、1つのパックに任意の数のバンドルを含める(またはまったく含めない)ことができます。パック内のすべてのコンポーネントをいずれかのバンドルに含める必要はないこと、および各コンポーネントは1つのバンドルにしか含められないことに注意してください。

  5. テキスト・エディタを使用し、パックのフォルダ・ルートのcomponent.jsonファイルを次のサンプルのように変更して、パックの依存関係とオプションのバンドルを指定します。追加するコンポーネントは、完全名と特定のバージョンによって関連付ける必要があります。
    {
    "name": "my-pack",
    "version": "1.0.0",
    "type": "pack",
    "displayName": "My JET Pack",
    "description": "An example JET Pack",
    "dependencies": {
      "my-pack-my-widget-1":"1.0.0",
      ...
    },
    "bundles":{
        "my-pack/my-bundle":[
          "my-pack/my-bundle-file1/loader",
          ...
        ]
      },
    "extension": {
        "catalog": {
            "coverImage": "coverimage.png"
        }
    }
}
}

    パック・コンポーネントのcomponent.jsonファイルには、次の一意の定義を含める必要があります。

    • nameは、一意にする必要があるJETパックの名前です。グループに関連するネームスペースを使用して定義してください。パック内の個々のコンポーネントの完全名を作成するときに、この名前が前に付加されます。

    • versionには、SemVer範囲ではなく、パックの正確なバージョン番号を定義します。

      ノート:

      パックの所定のリリースにおけるバージョン番号の変更は、パック内容の最も大きな変更を示すものです。たとえば、パックに2つのコンポーネントが含まれているとき、あるリリースで、コンポーネントの1つはPatchレベルが変更され、もう1つはMajorバージョンが変更されると、パックのバージョン番号の変更でもMajorバージョンを変更する必要があります。パックの実際のバージョン番号が、参照しているコンポーネントいずれかのバージョン番号と一致しなくてはならないという要件はありません。

    • typeはpackに設定する必要があります。
    • displayNameは、Oracle Component Exchangeに表示されるパック・コンポーネントの名前です。これには読みやすく長すぎないものを設定します。
    • descriptionはOracle Component Exchangeに表示される説明です。たとえば、これを使用してパックの用途を説明します。

    • dependenciesには、コンポーネントの完全名(パック名とコンポーネント名を連結したもの)を指定して、パックを構成するコンポーネントのセットを定義します。ここでは、SemVer範囲ではなく、正確なバージョン番号を使用することに注意してください。依存関係のバージョン番号のリビジョンを管理して、参照コンポーネントのバージョンの変化を反映し、パック内でコンポーネントにアクセスするためのパスの一部も指定することが重要です。

      JET Packディレクトリにすべてのコンポーネントを含める場合は、パック内のすべてのコンポーネントに対して個別のエントリを定義するのではなく、dependenciesの値としてトークン"@dependencies@"を使用します。次のスニペットは、このトークンをcomponent.jsonファイルで使用する方法を示しています: 

      {
  "name": "my-pack",
  "version": "1.0.0",
  "type": "pack",
  "displayName": "My JET Pack",
  "description": "An example JET Pack",
  "dependencies": "@dependencies@"
}
    • bundlesには、使用可能なバンドル(オプション)と各バンドルの内容を定義します。バンドル名とそのバンドルの内容の両方を定義するときに、パック名接頭辞を使用することに注意してください。これは、それらのアーティファクトにマップするために必要なRequireJSパスであるためです。
    • catalogには、Oracle Component Exchangeの作業メタデータを定義します。このケースではカバー・イメージが含まれます。
  6. オプションで、作業フォルダのルートにreadmeファイルを作成します。これは、README.txt (またはマークダウン形式を使用するときはREADME.md)という名前のプレーン・テキスト・ファイルとして定義する必要があります。
  7. オプションで、Oracle Exchangeでコンポーネントを表示するためのカバー・イメージを作業フォルダのルートに作成します。ファイル名は、component.jsonファイルのname属性と同じにすることができます。
  8. コンポーネントをOracle Component Exchangeにアップロードしようとする場合は、「Webコンポーネントのパッケージ化」の説明に従い、JETツールを使用してJETパックの作業フォルダのzipアーカイブを作成します。
  9. コンポーネントをOracle Component Exchangeにアップロードすることで、Oracle Visual BuilderプロジェクトでのJETパックの使用をサポートします。

JETパックのリソース・コンポーネントの作成

JETパックにアセンブルするWebコンポーネント全体でアセットを再利用する場合は、リソース・コンポーネントを作成します。リソース・コンポーネントは、複数のJETパックで再利用できます。

複雑なコンポーネントのセットを扱うときは、複数のコンポーネント間で特定のアセットを共有できると役立つことがあります。そのような場合、コンポーネントすべてを1つのJETパックに含めて、共有アセットを保持するためにリソース・コンポーネントをパックに追加できます。パックに格納できる内容に制限はありません。通常、共有されるJavaScript、CSS、JSONのファイルとイメージが公開されます。通常、サードパーティ・ライブラリは参照コンポーネントから参照する必要があることに注意してください。リソース・コンポーネントには組み込まないでください。

リソース・コンポーネントを作成するためにツールは必要ありません。便利な場所にフォルダを作成する必要があります。最終的にはこのフォルダを圧縮して、配布可能なリソース・コンポーネントを作成します。このフォルダの内部には、望みの構造で任意のコンテンツを含めることができます。

リソース・コンポーネントを作成するには:

  1. まだ作成していない場合は、アプリケーションのルート・フォルダから次のコマンドを使用して、リソース・コンポーネントを含めるJETパックを作成します:

    ojet create pack my-resource-pack

  2. 引き続きアプリケーションのルート・フォルダから、JETパックにリソース・コンポーネントを作成します:

    ojet create component my-resource-comp --type=resource --pack=my-resource-pack

    ツールによって、1つのテンプレートcomponent.jsonファイルおよび索引ファイルを含むフォルダ構造が追加されます。 

    /root folder
  /src
    /components
     /my-resource-pack
       /my-resource-comp
         component.json
  3. 作成したフォルダ(この例ではmy-resource-comp)に必要なコンテンツを移入します。変換バンドルのNLSコンテンツを除き、望みの構造でコンテンツを追加できます。NLSコンテンツのケースでは、通常のJETフォルダ構造を維持します。リソース・コンポーネントにそのようなバンドルを含まれる場合に重要です。
    /(my-resource-folder)
  /converters
    phoneConverter.js
    phoneConverterFactory.js
  /resources
    /nls
      /root
       oj-ext-strings.js
    /phone
      countryCodes.json
  /validators
    emailValidator.js
    emailValidatorFactory.js
    phoneValidator.js
    phoneValidatorFactory.js
    urlValidator.js
    urlValidatorFactory.js

    このサンプルでは、翻訳バンドルの/resources/nlsフォルダ構造は、JETツールによって生成されるアプリケーションのフォルダ構想に基づいて保たれることに注意してください。

  4. テキスト・エディタを使用して、次のサンプルのようなフォルダ・ルートにある、JETパックmy-resource-packのリソースmy-resource-compを定義するcomponent.jsonファイルを更新します。
    {
  "name": "my-resource-comp",
  "pack": "my-resource-pack",
  "displayName": "Oracle Jet Extended Utilities",
  "description": "A set of reusable utility classes used by the Oracle JET extended component set and available for general use.  Includes various reusable validators",
  "license": "https://opensource.org/licenses/UPL",
  "type": "resource",
  "version": "2.0.2",
  "jetVersion": ">=8.0.0 <10.1.0",
  "publicModules": [
    "validators/emailValidatorFactory",
    "validators/urlValidatorFactory"
  ],
  "extension":{
    "catalog": {
      "category": "Resources",
        "coverImage": "cca-resource-folder.svg"
    }
  }
}

    リソース・コンポーネントのcomponent.jsonファイルには、次の一意の定義を含める必要があります。

    • nameは、一意にする必要があるリソース・コンポーネントの名前です。グループに関連するネームスペースを使用して定義してください。
    • packは、リソース・コンポーネントが含まれるJETパックの名前です。
    • displayNameは、Oracle Component Exchangeに表示されるリソース・コンポーネントの名前です。これには読みやすく長すぎないものを設定します。
    • descriptionはOracle Component Exchangeに表示される説明です。たとえば、これを使用して、コンポーネントによって提供される使用可能なアセットを説明します。
    • typeはresourceに設定する必要があります。

    • versionには、リソース・コンポーネントのセマンティック・バージョン(SemVer)全体を定義します。このバージョン番号のリビジョンを管理して、所定の変更の互換性をコンシューマに通知することが重要です。

      ノート:

      リソース・コンポーネント・バージョンの変更は、リソース・コンポーネント内のすべての変更をロールアップする必要があり、.jsファイルのみの変更に限定されないことがあります。共有の.cssファイルに定義されたCSSセレクタに対する変更によって、ダウンストリームでのセレクタの使用方法をユーザーが変更せざるを得ない場合は、メジャー・バージョンの変更がトリガーされることがあります。

    • jetVersionには、サポートされるOracle JETバージョン範囲をSemVer表記を使用して定義します。これはオプションです。リソース・コンポーネントに含めるものの性質によって異なります。コンポーネントにJavaScriptコードが含まれ、そのコードでOracle JET APIが参照される場合、そのケースのJETバージョンの範囲を実際に組み込む必要があります。
    • publicModulesには、リソース・コンポーネント内のエントリ・ポイントのリストを指定します。これらのエントリ・ポイントはパブリックと見なされ、このコンポーネントに依存するすべてのコンポーネントによって使用されると想定されます。配列に指定されないすべてのAPIは、パック内のプライベートと見なされ、外部では使用できず、同じパック・ネームスペース内のコンポーネントによってしか使用できません。
    • catalogには、Oracle Component Exchangeの作業メタデータを定義します。このケースではカバー・イメージが含まれます。
  5. オプションで、作業フォルダのルートにreadmeファイルを作成します。readmeはリソースのアセットを記述するために使用できます。これは、README.txt (またはマークダウン形式を使用するときはREADME.md)という名前のプレーン・テキスト・ファイルとして定義する必要があります。

    ヒント:

    アセットの状態を説明するときは注意してください。たとえば、パブリックとみなし、外部コンシューマ(コンポーネントが所属するJETパック外部のコードなど)が安全に使用できるユーティリティ・クラスは、リソース・コンポーネントに組み込むことを選択できます。ただし、他のアセットはパック内でプライベートであると記述することをお薦めします。

  6. オプションで、作業フォルダのルートに変更ログ・ファイルを作成します。変更ログには、パックの重要な変更の詳細が経時的に記録されます。作成することを強くお薦めします。これは、CHANGELOG.txt (またはマークダウン形式を使用するときはCHANGELOG.md)という名前のテキスト・ファイルとして定義する必要があります。
  7. オプションで、作業フォルダのルートにライセンス・ファイルを作成します。
  8. オプションで、Oracle Exchangeでコンポーネントを表示するためのカバー・イメージを作業フォルダのルートに作成します。サードパーティのロゴを使用すると、ここで使用方法を示すのに役立ちます。ファイル名は、component.jsonファイルのname属性と同じにすることができます。
  9. コンポーネントをOracle Component Exchangeにアップロードするときは、作業フォルダのzipアーカイブを作成します。アーカイブ・ファイル名では<fullName>-<version>.zipという形式を使用することをお薦めします。たとえば、my-resource-pack-my-resource-comp-2.0.2.zipです。
JETパックでリソース・コンポーネントを使用する方法の詳細は、「JETパックの作成」を参照してください。

Webコンポーネントの参照コンポーネントの作成

Webコンポーネントで使用するためにサードパーティ・ライブラリへのポインタを取得する必要があるときは、参照コンポーネントを作成します。

場合によっては、JET Webコンポーネントが機能するためにサードパーティ・ライブラリを使用する必要があります。それらのライブラリをコンポーネントそのものまたはリソース・コンポーネントに埋め込むことは可能ですが、通常は参照コンポーネントを定義してライブラリの共有コピーを参照することをお薦めします。

参照コンポーネントの作成

参照コンポーネントを作成するためにツールは必要ありません。便利な場所にフォルダを作成して、そこでcomponent.jsonファイルの参照コンポーネントのメタデータを定義する必要があります。最終的にはこのフォルダを圧縮して、配布可能な参照コンポーネントを作成します。

参照コンポーネントは通常はスタンドアロンであるため、作成するcomponent.jsonファイルをJETパックに含めないでください。

参照コンポーネントを作成するには:

  1. 作業フォルダを作成し、そのフォルダのルートに、次のサンプルに似たcomponent.jsonファイルをテキスト・エディタを使用して作成します。このファイルでmoment.jsライブラリを参照します。
    {
  "name": "oj-ref-moment",
  "displayName": "Moment library",
  "description": "Supplies reference information for moment.js used to parse, validate, manipulate, and display dates and times in JavaScript",
  "license": "https://opensource.org/licenses/MIT",
  "type": "reference",
  "package":"moment",
  "version": "2.24.0",
  "paths": {
    "npm": {
      "debug": "moment",
      "min": "min/moment.min"
    },
    "cdn": {
      "debug": "https://static.oracle.com/cdn/jet/packs/3rdparty/moment/2.24.0/moment.min",
      "min": "https://static.oracle.com/cdn/jet/packs/3rdparty/moment/2.24.0/moment.min"
    }
  },
  "extension": {
    "catalog": {
      "category": "Third Party",
      "tags": [
        "momentjs"
      ],
      "coverImage": "coverImage.png"
    }
  }
}

    参照コンポーネントのcomponent.jsonファイルには、次の一意の定義を含める必要があります。

    • nameは、一意にする必要がある参照コンポーネントの名前です。グループに関連するネームスペースを使用して定義してください。
    • displayNameは、Oracle Component Exchangeに表示されるリソース・コンポーネントの名前です。これには読みやすく長すぎないものを設定します。
    • descriptionはOracle Component Exchangeに表示される説明です。たとえば、これを使用してサードパーティ・ライブラリの機能を説明します。
    • licenseには、サードパーティ・ライブラリのライセンスを指定する必要があります。
    • typeはreferenceに設定する必要があります。
    • packageには、ライブラリのnpmパッケージ名を定義します。これは関連するRequireJSパス(ライブラリを指す)の名前としても使用され、この参照に依存するコンポーネントによっても使用されます。
    • versionには、この参照コンポーネントで定義するサードパーティ・ライブラリのバージョンを指定する必要があります。所定のライブラリの複数のバージョンを参照する必要がある場合、それぞれにマップするために複数のバージョンの参照コンポーネントが必要になります。
    • pathsには、このライブラリのCDN位置を定義します。Oracle CDNへのアクセスの詳細は、次を参照してください。
    • minには、使用するライブラリの最適なバージョンを指定します。デバッグ・パスには、デバッグ・バージョンを指定することも、ここに示す縮小バージョンを指定することもできます。
    • catalogには、Oracle Component Exchangeの作業メタデータを定義します。このケースではカバー・イメージが含まれます。
  2. オプションで、作業フォルダのルートにreadmeファイルを作成します。readmeは、参照用のサードパーティ・コンポーネントWebサイトを示すために使用できます。これは、README.txt (またはマークダウン形式を使用するときはREADME.md)という名前のプレーン・テキスト・ファイルとして定義する必要があります。
  3. オプションで、Oracle Exchangeでコンポーネントを表示するためのカバー・イメージを作業フォルダのルートに作成します。サードパーティのロゴを使用すると、ここで使用方法を示すのに役立ちます。ファイル名は、component.jsonファイルのname属性と同じにすることができます。
  4. コンポーネントをOracle Component Exchangeにアップロードするときは、作業フォルダのzipアーカイブを作成します。アーカイブ・ファイル名では<fullName>-<version>.zipという形式を使用することをお薦めします。たとえば、oj-ref-moment-2.24.0.zipです。
  5. コンポーネントをCDNにアップロードすることで、Oracle Visual Builderプロジェクトでの参照コンポーネントの使用をサポートします。詳細は、後述の説明を参照してください。

参照コンポーネントの使用

Webコンポーネントが、これらの参照コンポーネントのいずれかに定義されたサードパーティ・ライブラリにアクセスする必要があるときは、component.jsonのdependency属性のメタデータを使用して、参照コンポーネントの明示的なバージョンを示すか、セマンティック範囲を指定します。ここで示すのは、特定のバージョンの2つの参照コンポーネントを使用するコンポーネントの単純な例です。 

{
    "name":"calendar",
    "pack":"oj-sample",
    "displayName": "JET Calendar",
    "description": "FullCalendar wrapper with Accessibility added.",
    "version": "1.0.2",
    "jetVersion": "^9.0.0",
    "dependencies": {
        "oj-ref-moment":"2.24.0",
        "oj-ref-fullcalendar":"3.9.0"
    },
 
    ...

前述のコンポーネントがOracle JETまたはOracle Visual Builderプロジェクトに追加されるとき、この依存関係情報が使用されて、参照コンポーネントとしてポイントされるサードパーティ・ライブラリの正しいRequireJSパスが作成されます。

または、参照コンポーネントに依存するWebコンポーネントをインストールし、Oracle JET CLIを使用すると、ツールによって自動的にnpmインストールが実行され、ライブラリがローカルになります。ただし、同じコンポーネントがOracle Visual Builderで使用されるときは、CDN位置を使用する必要があります。つまり、参照コンポーネントはVisual Builderで使用できるようにCDNに存在する必要があります。

ページへのWebコンポーネントの追加

VComponentベースのWebコンポーネントを使用するには、Webコンポーネントを使用するTSXページのWebコンポーネントにエントリ・ポイントを提供するローダー・モジュールをインポートします。

以前にコンポジット・コンポーネント・アーキテクチャを使用してWebコンポーネントを構築したユーザーは、ローダー・モジュールを使用したWebコンポーネントのインポートに精通しています。VComponentベースのWebコンポーネントでは、Webコンポーネントのメイン・エントリ・ポイントとして機能するloaderモジュールのこの規則も使用します。これにより、Oracle JET CLI、Visual BuilderおよびComponent ExchangeがVComponentベースのWebコンポーネントと連携できます。

WebコンポーネントをVDOMアプリケーションにインポートする場合は、Webコンポーネントのインポートにコンポーネント・クラス名とWebコンポーネントのカスタム要素名のどちらを使用するかを選択できます。VComponentベースのWebコンポーネントをMVVM JETアプリケーションにインポートする場合は、カスタム要素構文を使用する必要があります。JETパックからコンポーネントをインポートする場合は、import文でJETパックを識別する必要もあります。次のコメント付きの例に、各オプションに使用する構文を示します。

import { h } from "preact";
// Import standalone components.
//   Import as a custom element.
import "doc-hello-world/loader";
//   Import as a component class.
import { DocBonjourWorld } from "doc-bonjour-world/loader";

// Import components from a JET Pack
//   Import as a custom element.
import "my-component-pack/my-widget-1/loader";
//   Import as a component class.
import { MyWidget2 } from "my-component-pack/my-widget-2/loader";

export function Content() {
  return (
    <div class="oj-web-applayout-max-width oj-web-applayout-content">
      {/* Standalone component's custom element */}
      <doc-hello-world></doc-hello-world>
      {/* Standalone component's component class */}
      <DocBonjourWorld />

      {/* JET Pack component's custom element */}
      <my-component-pack-my-widget-1></my-component-pack-my-widget-1>
      {/* JET Pack component's component class */}
      <MyWidget2 />
    </div>
  );
}

次の図は、スタータ・テンプレートのコンテンツ・コンポーネントでの各レンダリングの例を示しています。

Webコンポーネントおよびカスタム要素

VComponentベースのWebコンポーネントのAPIドキュメントの生成

Oracle JET CLIには、開発するVComponentベースのWebコンポーネント(VComponent)のAPIドキュメントの生成を支援するためのコマンド(ojet add docgen)が含まれています。

プロジェクトのルートからコマンドを実行すると、JSDoc NPMパッケージがインストールされ、apidoc_templateディレクトリがプロジェクトのsrcディレクトリに追加されます。apidoc_templateディレクトリには、後でVComponent用に生成するAPIリファレンス・ドキュメントの適切なタイトル、サブタイトルおよびフッター情報(コピーライト情報など)でカスタマイズできる次のファイルが含まれています。 

footer.html
header.html
main.html

次の例のように、VComponentのソース・ファイルにコメントを記述します:

import { ExtendGlobalProps, registerCustomElement } from "ojs/ojvcomponent";
. . .

type Props = Readonly<{
  message?: string;
  address?: string;
}>;

/**
 *
 * @ojmetadata version "1.0.0"
 * @ojmetadata displayName "A user friendly, translatable name of the component"
 * @ojmetadata description "<p>Write a description here.</p>
                            <p>Use HTML tags to put in new paragraphs</p>
                            <ul>
                                <li>Bullet list item 1</li>
                                <li>Bullet list item 2</li></ul>
         * <p>Everything before the closing quote is rendered</p>
 * "
 *
 */


function StandaloneVcompFuncImpl({ address = "Redwood shores", 
                         message = "Hello from  standalone-vcomp-func" }: Props) {
  return (
    <div>
    . . .
    </div>
  );
}

ソース・ファイルでのVComponentのAPIの文書化が完了したら、コンポーネントがJETパック(ojet build component component-nameまたはojet build component jet-pack-name)の一部である場合、コンポーネントまたはJETパックに対してbuildコマンドを実行し、appRootDir/web/components/component-or-pack-name/vcomponent-version/docsディレクトリにAPIリファレンス・ドキュメントを生成します。

次の/docsディレクトリ・リストは、スタンドアロンVComponentに対してOracle JET CLIによって生成されるファイルを示しています。コンポーネントを含むOracle JETアプリケーションをビルドして、APIドキュメントを生成することはできません。個々のVComponentまたはVComponentを含むJETパックをビルドする必要があります。Oracle JET CLI ojet add docgenコマンドを使用して、CCAベースのWebコンポーネントのAPIドキュメントを生成することもできません。 

appRootDir/web/components/standalone-vcomp-func/1.0.0/docs

|   index.html
|   jsDocMd.json
|   standalone-vcomp-func.html
|   standalone.StandaloneVcompFunc.html
|
+---scripts
|   |   deprecated.js
|   |
|   \---prettify
|           Apache-License-2.0.txt
|           lang-css.js
|           prettify.js
|
\---styles
    |   jsdoc-default.css
    |   prettify-jsdoc.css
    |   prettify-tomorrow.css
    |
    \---images
            bookmark.png
            linesarrowup.png
            linesarrowup_blue.png
            linesarrowup_hov.png
            linesarrowup_white.png
            oracle_logo_sm.png

なお、生成されたAPIドキュメントの外観を変更するために代替ロゴまたはCSSスタイル(あるいはその両方)を含める場合は、ディレクトリappRootDir/node_modules/@oracle/oraclejet/dist/jsdoc/static/styles/のコンテンツを更新してください。

Webコンポーネントのビルド

Oracle JET Webコンポーネントを作成することで、ファイルを最適化し、コンシューマと共有可能なコンポーネントの縮小フォルダを生成できます。

Webコンポーネントを構成し、様々なアプリケーションで使用する準備ができたら、スタンドアロンWebコンポーネント、JETパックおよびリソース・コンポーネントといったタイプのWebコンポーネントをビルドできます。JETツールを使用してこれらのコンポーネントをビルドすると、最適化されたコンポーネント・ファイルを含む縮小コンテンツが生成されます。この縮小バージョンのコンポーネントは、コンシューマと簡単に共有して使用できます。たとえば、Oracle Component Exchangeに公開する前にコンポーネントをビルドします。Webコンポーネントをビルドするには、コンポーネントを含むJETアプリケーションのルート・フォルダから次のコマンドを使用します:

ojet build component my-web-component-name

たとえば、Webコンポーネント名がhello-worldの場合は、次のコマンドを使用します: 

ojet build component hello-world

JET Packの場合は、パック名を指定します。

ojet build component my-pack-name

パック内の個別のコンポーネントのビルドはサポートされていないことに注意してください。パック全体を一度にビルドする必要があります。

このコマンドによって、Oracle JET Webアプリケーションのweb/components/hello-world/x.x.x/ディレクトリに/minフォルダが作成されます。ここで、x.x.xはコンポーネントのバージョン番号です。/minフォルダにはWebコンポーネント・ファイルの縮小(リリース)バージョンが含まれます。

参照コンポーネントでは縮小やバンドルは必要ないため、ビルドする必要はありません。

Webコンポーネントをビルドする場合:

  • JETアプリケーションに複数のコンポーネントが含まれる場合、コンポーネントを含むJETアプリケーションをビルドし、すべてのコンポーネントをまとめてビルドして最適化できます。コンポーネント名を指定してbuild componentコマンドを実行すると、単一コンポーネントをビルドできます。

  • オプションで、buildコマンドとともに--releaseフラグを使用することはできますが、buildコマンドではコンポーネントのデバッグと縮小バージョンの両方が生成されるため、必須ではありません。

  • デバッグに適した可読性の高いコンパイル出力を生成する場合は、オプションでbuildコマンドとともに--optimize=noneフラグを使用できます。コンポーネントのloader.jsファイルには縮小アプリケーション・ソースが含まれますが、元のソースの改行および空白が保持されるため、内容の可読性は向上します。

Webコンポーネントのパッケージ化

コマンドライン・インタフェースで、縮小Oracle JET Webコンポーネントの共有可能なzipファイル・アーカイブを作成できます。

他の開発者とWebコンポーネントを共有する場合、アプリケーションの/webのcomponentsサブフォルダに含まれる生成済出力のアーカイブ・ファイルを作成できます。スタンドアロンWebコンポーネントまたはリソース・コンポーネントをビルドしたら、JETツールを使用してpackageコマンドを実行し、Webコンポーネントのコンパイル済の縮小ソースを含むzipファイルを作成します。
ojet package component my-web-component-name
JETパックの場合も同様にファイル・システムから直接zipファイルを作成することはできません。JETツールを使用してJETパックをパッケージ化する必要があります。/jet-composites/<packName>サブフォルダ内の出力にはネストされたコンポーネント・フォルダが含まれ、ツールによって各コンポーネントに独自のzipファイルが確保されるためです。
ojet package pack my-JET-Pack-name

packageコマンドは、/web/componentsディレクトリからコンポーネントの縮小ソースをパッケージ化し、それを含むアプリケーションのルートにある/distフォルダ内のzipファイルとして使用できるようにします。このzipファイルの/minサブフォルダには、指定されたコンポーネントとそのコンポーネントの縮小バージョンの両方が含まれます。

参照コンポーネントでは縮小やバンドルは必要ないため、ビルドする必要はありません。コンポーネントのフォルダの単純なzipアーカイブを作成することで、参照コンポーネントをアーカイブできます。

パッケージ化されたコンポーネントのzipアーカイブは、たとえば、「Oracle Component ExchangeへのWebコンポーネントの公開」に示されているように、Oracle Component Exchangeでの共有に適しています。公開するコンポーネントを編成するために、JETツールにより、JETパックのcomponent.jsonファイルのversionプロパティの値が追加され、個々のコンポーネントがdistフォルダ内の生成されたzipに追加されます。たとえば、version値が1.0.0で、パック内の個々のコンポーネント(my-widget-1など)のバージョン値も1.0.0であるコンポーネント・パックmy-component-packがある場合、生成されたファイルのzipファイル名は、次のようになります: 

appRootDir/dist/
my-web-component-name_1-0-0.zip
my-component-pack_1-0-0.zip
my-component-pack-my-widget-1_1-0-0.zip
my-component-pack-my-widget-2_1-0-0.zip
my-component-pack-my-widget-3_1-0-0.zip

コンポーネントをCDNにアップロードするときに、アーカイブ・ファイルも生成できます。CDNの場合は、「CDNでのWebコンポーネントのアップロードおよび消費」で説明しているように、コンポーネントを共有するために追加のステップが必要です。