Ionic Launch Event. September 28th 2021.

Web アプリの Cordova から Capacitor へのマイグレーション

Cordova を使用して Web アプリケーションを完全に Capacitor に移行するには、いくつかの手順が必要です。

これらの変更を適用する際には、別のコードブランチで作業することをお勧めします。

Capacitor を追加する

ターミナルでプロジェクトを開き、ウェブアプリへの Capacitor の追加、または Ionic アプリへの Capacitor の追加のガイドに従います。

アプリを Capacitor で初期化します。アプリの初期化に必要な情報は、Cordova の config.xml ファイルに記載されています:

アプリ名は <name> 要素の中にあります
バンドル ID は、ルートの <widget> 要素の id 属性で確認できます

npx cap init

ウェブアプリの構築

ネイティブプラットフォームを追加する前に、少なくとも一度はウェブ・プロジェクトを構築する必要があります。

npm run build

これにより、Capacitor の設定ファイルでは、Capacitor がwebDirとして使用するwwwフォルダが自動的に設定されていることが確認できます。

Platforms の追加

Capacitor の Native プラットフォームは、その最上位フォルダにあります。Cordova の場合は、platforms/ios もしくは platforms/android でした。

npx cap add ios
npx cap add android

プロジェクトのルートに android と ios の両フォルダが作成されます。これらは全く別のネイティブプロジェクトの成果物であり、アプリの一部と考えるべきものです（つまり、ソースコントロールにチェックを入れたり、独自の IDE で編集したりするなど）。さらに、package.json の dependencies にある Cordova プラグインは、Capacitor によって自動的に新しいネイティブプロジェクトにインストールされます（ただし、incompatible onesは除きます）。

"dependencies": {
    "@ionic-native/camera": "^5.3.0",
    "@ionic-native/core": "^5.3.0",
    "@ionic-native/file": "^5.3.0",
    "cordova-android": "8.0.0",
    "cordova-ios": "5.0.0",
    "cordova-plugin-camera": "4.0.3",
    "cordova-plugin-file": "6.0.1",
}

スプラッシュスクリーンとアイコン

アイコンとスプラッシュスクリーンのイメージは、プロジェクトのトップレベルの resources フォルダに保存されています。これらの画像があれば、cordova-resツールを使って、Capacitor ベースの iOS や Android プロジェクトのアイコンやスプラッシュスクリーンを生成することができます。

まず、cordova-resをインストールします:

npm install -g cordova-res

次に、以下を実行してイメージを再生成し、ネイティブプロジェクトにコピーします:

cordova-res ios --skip-config --copy
cordova-res android --skip-config --copy

詳細はこちら.

プラグインの移行

まず、既存の Cordova プラグインを確認します。不要なプラグインを削除できる可能性があります。

次に、Capacitor の official plugins と community plugins のすべてを確認します。その結果、Capacitor と同等の Cordova プラグインに変更できる可能性があります。

プラグインによっては機能が完全に一致しないものもありますが、必要な機能を考えれば問題ないでしょう。

なお、 incompatible or cause build issues となっているプラグインは自動的にスキップされます。

Cordova プラグインの削除

Cordova プラグインを Capacitor プラグインに置き換えた(あるいは完全に削除した)後、プラグインをアンインストールし、syncコマンドを実行してネイティブプロジェクトからプラグインコードを削除します:

npm uninstall cordova-plugin-name
npx cap sync

パーミッションの設定

デフォルトでは、Capacitor の最新バージョンに要求されるすべての初期パーミッションが、iOS と Android の両方のデフォルトのネイティブプロジェクトに設定されています。しかし、追加のパーミッションを手動で適用する必要がある場合は、plugin.xmlと iOS や Android の必要な設定をマッピングする必要があります。 iOS と Android の設定ガイドを参照してください。

Cordova プラグインの環境設定

コンデンサは、npx cap init の実行時に、 config.xml に記述されている全てのプリファレンスを読み込んで、 Caoacutir 設定ファイルに移植します。また、cordova.preferencesオブジェクトに手動でプリファレンスを追加することもできます。

{
  "cordova": {
    "preferences": {
      "DisableDeploy": "true",
      "CameraUsesGeolocation": "true"
    }
  }
}

`config.xml` の Additional Fields

あなたは config.xml の他の要素が Capacitor アプリではどのように動作するか気になるかもしれません。

Author 要素はpackage.json で設定できます。ただし、Capacitor やアプリケーション内では使用されません:

<author email="email@test.com" href="http://ionicframework.com/">Ionic Framework Team</author>

allow-intent値のほとんどは使用されませんが、Capacitor に構成可能な代替手段の設定があります。

<allow-intent href="http://*/*" />
<allow-intent href="https://*/*" />
<allow-intent href="tel:*" />
<allow-intent href="sms:*" />
<allow-intent href="mailto:*" />
<allow-intent href="geo:*" />

iOS のedit-config 要素は configured in Info.plist を必要とします。

<edit-config file="*-Info.plist" mode="merge" target="NSCameraUsageDescription">
    <string>Used to take photos</string>
</edit-config>

すべてのconfig.xmlの要素をカバーするのは不可能です。しかし、”Capacitor で X を設定するにはどうやったらいい？”に関する質問のほとんどは、オンラインで答えを探すときには「[プラットフォーム] (iOS/Android)で X を設定するには?」と考えるべきです。

Scheme の設定

Cordova で Ionic を使用すると、アプリはデフォルトで cordova-plugin-ionic-webview を使用し、iOS ではコンテンツの提供に ionic:// scheme を使用します。Capacitor アプリは iOS のデフォルトスキームとして capacitor:// を使用しています。これは LocalStorage のようなオリジンバインドされた Web API を使用すると、起点が異なるためデータが失われることを意味します。これは、コンテンツの提供に使用するスキームを変更することで修正できます。

{
  "server": {
    "iosScheme": "ionic"
  }
}

Cordova の削除

すべてのマイグレーション変更が適用され、アプリケーションが正常に動作することをテストしたら、Cordova をプロジェクトから削除できます。config.xmlを削除します。platforms フォルダと plugins フォルダも同様です。Cordova は Capacitor と一緒に動作するので、技術的に取り外す必要はないことに注意してください。実際、Cordova プラグインの使用を継続する予定がある場合、または将来的に使用する可能性がある場合は、Cordova アセットをそのまま使用できます。