機械翻訳について

C コア・パック・コンポーネントへのOracle JETレガシー・コンポーネントの移行

Oracle JET Core Packマイグレータを使用すると、アプリの機能を中断することなく、Oracle JETレガシー・コンポーネント(oj-*)を同等のコア・パック・コンポーネント(oj-c-*)に移行できます。 また、レガシー・コンポーネント用に書き込まれたSelenium WebDriverテスト・ファイルを移行して、移行されたCore Packコンポーネントと連携させます。

コア・パック・マイグレータは、Oracle JET Audit Framework (Oracle JAF)にパッケージ化されています。 コア・パックの移行ワークフローを開始するには、まずOracle JAFをダウンロードし、アプリで監査を実行します。 次に、監査レポートの情報を使用して、アプリの移行コードを準備します。移行が失敗するか、移行者によって無視される可能性があるため、アプリで手動で対処する必要がある特定の問題があります。

コードを評価し、移行の準備が完了したら、migrator.logファイルを生成する予行演習移行を実行して、マイグレータのコードに対する意図した変更を確認できます。

また、移行構成ファイルを作成して、Core Packマイグレータの動作を調整することもできます。 デフォルト設定を使用してマイグレータを実行できますが、たとえば、テスト・ファイルのみを移行したり、特定のコンポーネントを移行から除外するように、migrationConfig.jsonファイルを使用して操作を変更できます。

移行前コードとドライ・ランの結果に問題がなければ、完全な移行を実行できます。

ノート:

すべての移行を自動化できるわけではなく、一部のコンポーネントでは、機能するために移行後に手動による修正が必要な場合があります。 移行に関する既知の問題のリストと解決方法は、「コア・パックの移行に関する問題のトラブルシューティング」を参照してください。

アプリのレガシー・コンポーネントをコア・パックに正常に移行した後、SeleniumのWebDriverテスト・ファイルでコンポーネントを移行できます。 「WebDriverテスト・ファイルのコア・パックへの移行」を参照してください。

Oracle JAFのインストールおよび使用の詳細は、「Oracle JET Audit Frameworkのインストール」を参照してください。 ターミナル・ウィンドウでコマンドojaf -vおよびojaf -mig -vを実行して、インストールされているOracle JAFおよびCore Packマイグレータのバージョンを確認できます。

コア・パック用のOracle JETアプリの準備

アプリのコードまたはテスト・ファイルでOracle JET Core Packマイグレータを使用する前に、Oracle JAF監査を実行して、移行に影響を及ぼす可能性のある問題を検査します。 たとえば、非推奨のAPIはCore Packコンポーネントで使用できず、コードに存在する場合、移行は失敗します。

Oracle JAFの組込み監査ルールは、無効な機能の識別および修正に役立ちます。

また、Oracle JET APIドキュメントには、移行できるコア・パックに相当する各レガシー・コンポーネントの「移行」というラベルのセクションがあります。 この項では、2つのコンポーネント・バージョンの違いに関する具体的なガイダンスと情報を提供することで、特定のレガシー・コンポーネントをコア・パックに移行することを容易にします。 たとえば、oj-buttonコンポーネントの移行セクションを参照してください。 同等のコア・パック・コンポーネントを持つレガシー・コンポーネントのみが移行の対象となります。

ノート:

破棄されたコンポーネントのAPIドキュメントがAPIページに表示されない場合は、サイドバーの「メンテナンス・モードの表示」チェック・ボックスを選択して表示できます。

アプリの移行を準備するには、最新バージョンのOracle JAFをインストールし、コードに対して監査を実行します:

  1. ターミナル・ウィンドウを開き、次のコマンドを入力してOracle JAFをグローバルにインストールします:

    npm install -g @oracle/oraclejet-audit

  2. Oracle JAFをインストールした後、ターミナル・ウィンドウでアプリのルート・ディレクトリに移動し、デフォルトのJAF構成を初期化します:

    ojaf --init

    Oracle JAFツールは、アプリのルート・ディレクトリにoraclejafconfig.jsonという名前のデフォルトのJAF構成ファイルをスキャフォールドします。

  3. ターミナル・ウィンドウで、アプリケーションの./srcディレクトリに移動し、監査を実行するコマンドを入力します:

    ojaf

監査によって、ターミナル・ウィンドウにレポートが生成されます。 レポートを使用して、コードにフラグが付けられた問題を解決します。 たとえば、「deprecated」という単語を含む、発生した問題を修正する必要があります。 非推奨のAPIはCore Packコンポーネントで使用できず、コンポーネントが非推奨のAPIを使用している場合、移行は失敗します。

ノート:

Oracle JET Core Packコンポーネントは、Altaテーマをサポートしていません。 アプリでAltaを使用する場合は、これらのコンポーネントをアプリで使用する前に、Redwoodに移行する必要があります。 「Oracle JET現在のリリースへのアプリの移行」を参照してください。

コードを監査し、すべての問題が解決されたことを確認したら、移行を続行できます。

コア・パック・マイグレータを使用したレガシー・コンポーネントの移行

移行のためにアプリを準備した後、ドライ・ラン移行を実行して、移行者がコードに対して意図した変更を理解し、移行前または移行後に対処する必要がある問題を見つけます。 変更するマイグレータの動作の側面がある場合は、その操作をカスタマイズするために使用できる移行構成ファイルを作成できます。

ガイドとして、次の移行手順のステップに従います。

  1. 予行演習の移行を実行します。 予行演習の移行では、コードが更新または移行されることはありませんが、移行されるすべてのコードの詳細なログが生成されます。

    アプリの./srcディレクトリでターミナル・ウィンドウを開き、コマンドojaf -mig -drを入力します。

    予行演習が終了すると、移行に要した時間および更新されたファイルおよびコンポーネントの数に関する情報を示すメッセージが表示されます。 また、アプリの./srcディレクトリに作成され、移行によって影響を受けるファイルおよびコンポーネントの詳細を含むmigrator.logファイルも示します。

  2. migrator.logファイルでドライ・ランの結果を確認し、移行構成ファイルを使用して移行者のデフォルト設定を使用するか動作を変更するかを決定します。

    移行構成ファイルについてさらに学習するには、「Core Pack Migratorの動作のカスタマイズ」を参照してください。

    移行構成ファイルを作成または変更する場合は、ターミナル・ウィンドウで次のコマンドを実行し、パスを独自の構成ファイルのロケーションに置き換えることで、予行演習で移行者への変更をテストできます: ojaf -mig -dr -c ./migrationConfig.json

  3. コードおよび移行の構成に問題がなければ、アプリの./srcディレクトリにあるターミナル・ウィンドウから移行コマンドを実行します。

    • 構成ファイルを変更した場合は、構成ファイルのロケーションを指す構成オプションを指定して次のコマンドを実行します:

      ojaf -mig -c ./migrationConfig.json

    • デフォルト構成でマイグレータを実行するには、次のコマンドを実行します:

      ojaf -mig

Core Pack Migratorの動作のカスタマイズ

移行構成ファイルを使用して、コア・パック・マイグレータの動作を微調整できます。 migrationConfig.jsonファイルでは、コア・パック・マイグレータの動作を構成できるプロパティの範囲がサポートされています。 たとえば、移行がアプリ全体ではなく、特定のコンポーネントまたはコンポーネントのサブセットにのみ影響するように指定できます。

移行構成ファイルには、次の指定に使用できるプロパティが含まれています:
  • 移行がWebDriverテスト・ファイルのみの場合、およびそれらが使用する拡張。
  • 移行中にスキップする必要があるフォルダ、ファイル、コンポーネント、または逆に、移行のターゲットが唯一のものである必要があります。
  • 特定のレガシー・コンポーネントをコア・パックに強制的に移行するかどうか。
  • 式が値である属性を含むタグを持つコンポーネントを移行から除外するかどうか。
  • 移行が実行されるベース・フォルダ。
  • 移行ログ・ファイルの名前とロケーション。

migrationConfig.jsonファイルには任意の名前を指定できます。 したがって、ユーザーは、複数の構成ファイルによって異なる移行ルールのセットを定義できます。

開始するには、選択したディレクトリにmigrationConfig.jsonファイルを作成します。通常は、アプリの./srcディレクトリなど、マイグレータを実行するディレクトリ内に作成します。

次のサンプルmigrationConfig.jsonファイルには、含めることができる構成オプションが表示されます。 

{
  "testFiles": "",
  "testFilesExtension": "",
  "excludeFolders": [],
  "excludeFiles": [],
  "excludeComponents": ["legacyTag1", "legacyTag2"],
  "includeFiles": [],
  "includeFolders": [],
  "includeComponents": ["legacyTag1", "legacyTag2"],
  "forceMigration": ["legacyTag1", "legacyTag2"],
  "excludeAttributeExpressions": {
    "legacyTag1": ["attributes"],
    "legacyTag2": ["attributes"]
  },
  "baseMigrationDir": "",
  "logFileName": "",
  "logFilePath": ""
}

すべての構成設定はオプションであり、移行に必要な設定のみを含めるように選択できます。

次の表に、使用可能な移行構成オプションとその使用方法を示します。

表C-1 migrationConfig.jsonファイルのプロパティ

プロパティ名 値タイプ 説明
testFiles ブール値

WebDriverテスト・ファイルのみを移行する予定で、移行するディレクトリにテスト・ファイルのみが含まれる場合は、この値をtrueに設定します。

testFilesExtension 文字列

テスト・ファイルの検索に使用できる特定の拡張子を移行元に伝えます。
excludeFolders 配列

移行者がスキップするフォルダ名が含まれます。 各フォルダ名のフルパスを指定します。

excludeFiles 配列

移行者がスキップするファイル名が含まれます。 ファイル名ごとにフルパスを指定します。

excludeComponents 配列

移行者がスキップするレガシー・コンポーネント・タグが含まれます。
includeFiles 配列

移行のために移行者が処理する唯一のファイルの名前が含まれます。 ファイル名ごとにフルパスを指定します。

includeFolders 配列

移行のために移行者が処理する唯一のフォルダの名前が含まれます。 各フォルダ名のフルパスを指定します。

includeComponents 配列

移行のために移行者が処理する唯一のレガシー・コンポーネント・タグが含まれます。
forceMigration 配列

IgnoreRuleSetが無視され、タグがコア・パックに移行されるレガシー・コンポーネント・タグが含まれます。

excludeAttributeExpressions オブジェクト

値として式が含まれている場合は移行しないコンポーネント固有の属性が含まれます。
baseMigrationDir 文字列

移行元のルート・ディレクトリを決定します。 デフォルトでは、マイグレータはコール元ディレクトリから実行されます(指定されていない場合)。 相対パスまたは絶対パスを使用できます。

logFileName 文字列

移行中に生成されるログ・ファイルの名前を決定します。 指定しない場合、migrator.logという名前がデフォルトで使用されます。

logFilePath 文字列

移行ログ・ファイルの出力ロケーションを決定します。 指定しない場合、コール元ディレクトリがデフォルトで使用されます。

WebDriverテスト・ファイルのコア・パックへの移行

Oracle JET Core Packマイグレータは、従来のコンポーネントを含むアプリ用に記述されたWebDriverテスト・ファイルを移行して、Core Packコンポーネントと連携させるのに役立ちます。

テスト・ファイルを移行するには、まず、「コア・パック用のOracle JETアプリの準備」にある移行前のステップに従います。これには、アプリでのOracle JAF構成の初期化、テスト・ファイルでの監査の実行、および見つかった問題の解決が含まれます。

ノート:

監査を実行する前に、Oracle JAFがテスト・ファイルを検索できるように、oraclejafconfig.jsonファイルが構成されていることを確認してください。 filesプロパティ内に、"./src/**/*.spec.ts"などの文字列値としてテスト・ファイルへのパスを含めます。 
"files": [
  "./src/**/*.html",
  "./src/**/*.js",
  "./src/**/*.ts",
  "./src/**/component.json",
  "./src/css/**/*.css",
  "./src/**/*.spec.ts"
],

テスト・ファイルを監査して移行の準備が完了したら、選択したディレクトリ(通常はアプリの./srcディレクトリ)でmigrationConfig.jsonを開くか作成し、次のように構成します。

  1. migrationConfig.jsonファイルのtestFilesプロパティをtrueに設定します。

  2. テスト・ファイルの拡張子が.spec.tsや.test.tsなどの一意の場合は、testFilesExtensionプロパティに文字列値として移行構成ファイルに追加します。

    testFilesExtensionプロパティにテスト・ファイルの拡張子を追加しない場合は、移行されるディレクトリ内のすべてのファイルがテスト・ファイルである必要があります。

  3. 残りの構成を確認して、移行の要件を満たしていることを確認します。 たとえば、マイグレータの実行元のディレクトリに影響するbaseMigrationDirプロパティが正しいことを確認します。

    少なくとも、migrationConfig.jsonファイルは、次の例のようになります。 

    {
  "testFiles": "true",
  "testFilesExtension": ".spec.ts"
}

  4. 移行構成ファイルと同じディレクトリでターミナル・ウィンドウを開きます。 構成ファイルを指しながら、予行演習の移行コマンドを実行します:

    ojaf -mig -dr -c ./migrationConfig.json

  5. migrator.logファイルでドライ・ランの結果を確認します。 必要な変更を行い、コードと構成に問題がなければ、実際の移行を実行します:

    ojaf -mig -c ./migrationConfig.json

移行が完了したら、テスト対象のコア・パック・コンポーネントを使用するアプリに対してテスト・ファイルを実行してみてください。 テストに合格するには、手動で修正する必要がある場合があります。

たとえば、テスト・ファイルの関数を使用して呼び出されたプロパティが適切に移行されていないか、テスト・ファイルが適切に移行され、アプリのコード内のレガシー・コンポーネントにCore Packでサポートされていない属性が含まれている可能性があります。

migrator.logファイルの移行レポートを使用して、問題をトラブルシューティングします。 migrator.logファイルには、コア・パックに相当する各レガシー・コンポーネントのAPIドキュメント内の移行セクションへのリンクがあります。

コア・パックの移行に関する問題のトラブルシューティング

一部のコンポーネントでは、移行後に手動による修正が必要な場合があります。 特定のレガシー・コンポーネントをコア・パックと同等のものに移行するためのガイダンスについては、migrator.logファイルの最後にアクセス可能なOracle JET APIドキュメントの移行セクションを参照してください。 詳細は、JET APIドキュメントの「コア・パック」セクションを参照することもできます。

手動移行が必要なインスタンスのリストを次に示します:

  • 変更の書式設定

    ユーザーは、移行の結果としてファイルのフォーマット変更を確認できます。 ファイルを正しい形式に保つために、フォーマッタを移行後に実行します。

  • 非推奨のAPI

    非推奨のAPIはCore Packコンポーネントで使用できないため、移行前に削除する必要があります。 非推奨のAPIがコードに存在する場合、移行は失敗します。

  • データ・ドリブンなアプローチに切り替えたコンポーネント

    一部のレガシー・コンポーネントでは、コア・パックに相当するデータ・ドリブンな子が使用されています。 これらはマイグレータによって無視され、手動で移行する必要があります。 「コア・パック」 APIドキュメントのデータ・ドリブン・コンポーネントおよびコンポーネント固有の移行の項を参照してください。

  • CSS

    CSSは、一部のコンポーネントで想定どおりに動作しなくなります。 「コア・パック」 APIドキュメントのCSSの項およびコンポーネント固有の移行の項を参照してください。

  • プロパティ・タイプが変更されたコンポーネント

    コンポーネントのプロパティが設定されているが、プロパティ・タイプが変更されている場合は、レガシー・インスタンスを移行できません。

    たとえば、oj-input-textやoj-input-numberなどのフォーム・コントロールでは、コア・パックのconverter型とレガシーのconverter型が一致しません。 したがって、converterプロパティが設定されている場合、インスタンスは移行されません。 この場合、migrator.logファイルには、次のメッセージのバリエーションがあります: Rule to ignore: "oj-input-text" filtered out due to attribute "converter".

  • 式を値として持つクラス属性

    クラスの移行は、値が文字列の場合にのみ行われます。そうしないと、移行によって式内の何も変更されません。

  • 強い型指定プロパティへの参照

    TypeScriptコードでは、使用するJETコンポーネントによって宣言された既存の型に基づいて変数またはプロパティを入力する場合があります。

    この例としては、カスタム・コンポーネントを定義し、そのコンポーネント実装の一部として使用するレガシーoj-buttonコンポーネントに直接渡すことができるクロミング・プロパティを定義する場合などがあります。 レガシー・コンポーネントを同等のCore Packに移行する場合も、このタイプの依存関係を同様に移行する必要があります

    JETレガシー・コンポーネントを使用する場合は、通常、エクスポートされるコンポーネントのIntrinsicPropsを使用します:
    import { ButtonIntrinsicProps} from 'ojs/ojbutton';
...
const localChroming:ButtonIntrinsicProps['chroming']
    コア・パック・コンポーネントでは、Preact ComponentPropsコンビニエンス・タイプを使用して同じ情報にアクセスするより一般的な方法があるため、props型はコア・パック・クラスから再エクスポートされません。 かわりに、コードは次のように移行されます: 
    import { ComponentProps } from 'preact';
import 'oj-c/button';
...
type ButtonProps = ComponentProps<'oj-c-button'>
...
const localChroming:ButtonProps['chroming'] = ...

  • 強く型指定されたイベント・ペイロードへの参照

    TypeScriptでコーディングする場合、コンポーネントのイベント・マップを参照することで、JETレガシー・コンポーネントから生成されるイベントを強く入力できます:

    import 'ojs/ojbutton';
import { ojButtonEventMap } from 'ojs/ojbutton';
...
private async onChatActionClick(event: ojButtonEventMap['ojAction']){...}

    コア・パック・コンポーネントでは、eventMapをインポートするのではなく、コンポーネント・インタフェースからタイプを直接参照できます: 

    import 'oj-c/button';
import { CButtonElement } from 'oj-c/button';
...
private async onChatActionClick(event: CButtonElement.ojAction){...}