アプリを Capacitor3.0 にアップデート

Capacitor 3 は、エコシステムに重要なアップデートとエキサイティングな新機能をもたらします。

Capacitor 3.0 RC のアナウンスを読む ›

アプリを Capacitor3 にアップグレードした後、何かフィードバックがあれば このディスカッション で共有していただけませんか？ご意見をお待ちしております 💖

プラグインを Capacitor の新しいバージョンにアップグレードしたいと考えているプラグイン作者の方は、 Upgrade Guide for Capacitor Plugins をご覧ください。

NodeJS 12+

Node 8 は生産終了となりました。Node 10 は 2021 年 4 月 30 日に寿命を迎えます。Capacitor 3 は NodeJS 12 以上が必要です。(最新の LTS バージョンを推奨します。)

Ionic CLI

If you are using the Ionic CLI, official Capacitor 3 support starts at version 6.16.0. We suggest upgrading to the latest version at this time via npm install -g @ionic/cli.

Update Capacitor CLI and Core

npm install @capacitor/cli@latest @capacitor/core@latest

ES2017+

Capacitor 3 は ES5 ではなく、ES2017 の環境でビルドされるようになりました。また、 プラグインテンプレートも ES2017 をターゲットに更新されました ので、サードパーティのプラグインもターゲットを更新することが推奨されます。

この変更は、Capacitor が公式にサポートしていない IE11 をサポートしている場合を除き、アプリに影響を与えることはありません。

TypeScript 3.8+

Capacitor 3 は新しい TypeScript の構文を使用しており、TS 3.8 以降でしか使用できません。

Capacitor Config の変更

TypeScript 3.8+がインストールされている場合、 capacitor.config.json を移行して、 capacitor.config.ts という名前の Type 化された TypeScript 設定ファイルにすることができます。 .json ファイルを使い続けることもできますが、TypeScript の設定ファイルの方が、チームにとってより良い開発環境を提供できるかもしれません。以下は、 Capacitor Test App で使用されている capacitor.config.ts ファイルの例です。c

/// <reference types="@capacitor/local-notifications" />
/// <reference types="@capacitor/push-notifications" />
/// <reference types="@capacitor/splash-screen" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.capacitorjs.app.testapp',
  appName: 'capacitor-testapp',
  webDir: 'build',
  plugins: {
    SplashScreen: {
      launchAutoHide: false,
    },
    LocalNotifications: {
      smallIcon: 'ic_stat_icon_config_sample',
      iconColor: '#CE0B7C',
    },
    PushNotifications: {
      presentationOptions: ['alert', 'sound'],
    },
  },
};

export default config;

公式プラグイン

すべてのプラグインは、Capacitor コアから削除され、独自の npm パッケージになりました。これにはいくつかの理由がありますが（ #3227 参照）、コアチームはこれが正しい方法であると確信しています。コアプラグインのインポートは以下のように行います。

import { Camera } from '@capacitor/camera';

Background Task、Permissions、 Photos の各プラグインは削除されました

• Background Task: このプラグインは、ほとんど使用されていないようで、ほとんどの開発者が期待していたようには動作しませんでした。コアチームは将来的にバックグラウンド機能を再検討する予定です。アップデートのために #3032 に登録してください
• Permissions: コアチームはこの集中型のアプローチに代わるものを実装しました。コミュニティのプラグインもこれを採用することができます（new Permissions APIを参照）
• Photos。この文書化されていない iOS 専用のプラグインは削除されました。 @capacitor-community/media をご利用ください

Accessibility、App、Modals plugins は分割されました

• Accessibility
  • VoiceOver と TalkBack の機能は、 スクリーンリーダー に移動しました。
• App
  • App 関連の情報や機能は App に残ります。
  • App の URL 処理(openUrl()とcanOpenUrl())は App Launcher に移動しました。
• Modal
  • Actions Sheet 機能(showActions())はActionsSheet 機能に移動しました。
  • Dialog Window の機能(alert(), prompt(), confirm())はDialogに移動しました。

新しい公式プラグインパッケージを使用するためにアプリを移行する

この変更に伴い、これまで使用していたプラグインを個別にインストールする必要があります。

1. プロジェクトで @capacitor/core の Plugins オブジェクトから抽出したコアプラグインを検索します
2. 対応する プラグインのドキュメント を探します。ただし、 いくつかのプラグインが分割されている ことに注意してください
3. ドキュメントに記載されている各プラグインのインストール手順に従う
4. プラグインのインポートを、プラグインのパッケージからインポートするように変更する（プラグインのインポート参照）
5. 後方互換性のないプラグインの変更 に記載されている指示に従う

Ionic Framework を使っていますか？

Ionic Framework では、以下のプラグインで API を利用しています:

• App
• Haptics
• Keyboard
• StatusBar

Ionic Framework で最高のユーザーエクスペリエンスを得るためには、アプリにプラグインをインポートしていなくても、これらのプラグインがインストールされていることを確認する必要があります:

npm install @capacitor/app @capacitor/haptics @capacitor/keyboard @capacitor/status-bar

Plugin のインポート

Pluginsオブジェクトは非推奨ですが、Capacitor 3 では引き続き使用できます。Capacitor のプラグインは、新しいプラグイン登録 API（Upgrade Guide for pluginsを参照）を使用するように更新する必要があり、これによりプラグインのパッケージから直接インポートすることができるようになります。

今後は、@capacitor/core の Plugins オブジェクトは使用しないでください。

// OLD
import { Plugins } from '@capacitor/core';
const { AnyPlugin } = Plugins;

プラグインのパッケージから直接インポートするのが望ましいのですが、これを可能にするためには、プラグインを Capacitor 3 で動作するようにアップデートする必要があります。

// NEW
import { AnyPlugin } from 'any-plugin';

後方互換性のないプラグインの変更

プラグインの API の多くは Capacitor 3 への移行を容易にするために変更されませんが、一部のプラグインはコードの更新や手動での移行が必要になります。

• Accessibility / Screen Reader
  • isScreenReaderEnabled()メソッドは、isEnabled()に名称変更されました。
  • accessibilityScreenReaderStateChange'イベントは、'stateChange'に名称変更されました。
  • Android および iOS では、スクリーンリーダーが現在アクティブな場合にのみ、speak()が動作します。スクリーンリーダーがアクティブかどうかに関わらず音声合成を行うには、@capacitor-community/text-to-speechを使用してください。
• Browser
  • prefetch()が削除されました。
• Device
  • アプリの情報が getInfo() から削除されました（appVersion, appBuild, appId, appName）。この情報については、App プラグインのgetInfo()を使用してください。
  • uuid は getInfo() から削除されました。新しい getId() 関数を使用してください。
• Haptics
  • HapticsNotificationType 列挙型のキーが、他の列挙型と一致するように、大文字からキャメルケースに変更されました。
• Local Notifications
  • このプラグインは新しい Permissions API を使用するようになりました。 requestPermission() が削除されたので、 requestPermissions() を使用してください。
• Push Notifications
  • このプラグインは新しい Permissions API を使用するようになりました。requestPermission()は削除されました。requestPermissions()を使用してください。
• Share
  • share() メソッドは any ではなく ShareResult を返すようになりました。
  • share() の戻り値には、completedが含まれなくなりました。完了しなかった場合は、代わりに拒否されます。
• Storage
  • データ移行が必要です！ 内部ストレージのメカニズムが変更され、データ移行が必要になりました。便利なメソッドが追加されました: migrate(). エンドユーザーに影響を与えずにアプリを更新するには、他のメソッドの前に migrate() を呼び出してください。
• Filesystem
  • statute()メソッドは、すべてのプラットフォームで ctime および mtime のタイムスタンプをミリ秒単位で返すようになりました。以前は、iOS はタイムスタンプを秒単位で返していました。

Logging の変更

Capacitor 3 では、hideLogs設定オプションが非推奨となりました。これに代わって、新しい設定オプション loggingBehavior が導入されました。詳細はconfig ドキュメントに記載されています

iOS

Capacitor 3 は iOS 12+をサポートしています。Xcode 12+が必要です。CocoaPods 1.8+を推奨します。

CocoaPods のアップデート

CocoaPods を最新の安定版にアップグレードすることを推奨します。 CocoaPods 1.8 では CDN を使用するようになったため、pod repo updateを定期的に実行する必要がなくなりました。

CocoaPods のバージョンは pod --version で確認し、インストール方法は cocoapods.org を参照してください。

iOS のデプロイメントターゲットを 12.0 に設定します。

Xcode のプロジェクトとアプリのターゲットに対して、以下の作業を行います： Build Settings タブを開きます。Deploymentセクションで、iOS Deployment TargetをiOS 12.0**に変更します。

次に、ios/App/Podfileを開き、iOS のバージョンを 12.0 にアップデートします:

-platform :ios, '11.0'
+platform :ios, '12.0'
 use_frameworks!

Swift のバージョンを 5 にする

まだ Swift 5 を使用していない場合は、Xcode ターゲットのBuild Settingsタブを開き、Swift Compiler - LanguageセクションのSwift Language VersionをSwift 5に変更します。

iOS のターゲットディレクトリに public を移動する

Capacitor 3 では、ios/App/publicディレクトリをios/App/App/publicに移動することが推奨されています。これは Xcode で実現できます:

既存のpublicフォルダを削除する。

1. プロジェクト（App）のファイルツリーを展開し、App グループを選択して、public フォルダを選択します。
2. 右クリックして、Deleteを選択します。フォルダを削除するか、参照だけを削除するかを尋ねられたら、Move to Trashを選択します。

新しい場所でpublicを再作成する

1. App “プロジェクト内の “App “グループを右クリックし、”Add Files to “App”… “をクリックします。
2. デフォルトのオプションのままにしておきます（グループではなくフォルダ参照を作成することと、Appターゲットに追加することを確認します）。
3. 新しいフォルダ**をクリックして、名前を “public “にします。
4. 作成」をクリックして、「追加」をクリックします。

Xcode では同じように見えるかもしれませんが、新しいpublicフォルダは、プロジェクトのルートではなく、Appグループに相対するようにしてください。

新しいpublicフォルダを gitignore します

ios/.gitignoreで、無視するパスをApp/publicからApp/App/publicに変更します。このフォルダには Web アセットのコピーが入っているので、コミットしてはいけません。

 App/build
 App/Pods
-App/public
+App/App/public
 App/Podfile.lock
 xcuserdata

Capacitor iOS プラットフォームのアップデート

npm install @capacitor/ios@latest
npx cap sync ios

アプリケーションイベントで、CAPBridgeからApplicationDelegateProxyに切り替える

ios/App/AppDelegate.swiftで、以下を更新します。

     func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
         // Called when the app was launched with a url. Feel free to add additional processing here,
         // but if you want the App API to support tracking app url opens, make sure to keep this call
-        return CAPBridge.handleOpenUrl(url, options)
+        return ApplicationDelegateProxy.shared.application(app, open: url, options: options)
     }

     func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
         // Called when the app was launched with an activity, including Universal Links.
         // Feel free to add additional processing here, but if you want the App API to support
         // tracking app url opens, make sure to keep this call
-        return CAPBridge.handleContinueActivity(userActivity, restorationHandler)
+        return ApplicationDelegateProxy.shared.application(application, continue: userActivity, restorationHandler: restorationHandler)
     }

Remove USE_PUSH compilation condition

If using the push notifications feature, in ios/App/App/AppDelegate.swift, update the following:

-    #if USE_PUSH

     func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        NotificationCenter.default.post(name: Notification.Name(CAPNotifications.DidRegisterForRemoteNotificationsWithDeviceToken.name()), object: deviceToken)
     }

     func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
        NotificationCenter.default.post(name: Notification.Name(CAPNotifications.DidFailToRegisterForRemoteNotificationsWithError.name()), object: error)
     }

-#endif

If not using push notifications you can remove the whole block

-    #if USE_PUSH
-
-    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
-        NotificationCenter.default.post(name: Notification.Name(CAPNotifications.DidRegisterForRemoteNotificationsWithDeviceToken.name()), object: deviceToken)
-    }
-
-    func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
-        NotificationCenter.default.post(name: Notification.Name(CAPNotifications.DidFailToRegisterForRemoteNotificationsWithError.name()), object: error)
-    }
-
-#endif

Switch from hard-coded CAPNotifications to NSNotification extensions

ios/App/AppDelegate.swiftで、以下を更新します:

     override func touchesBegan(_ touches: Set<UITouch>, with event: UIEvent?) {
         super.touchesBegan(touches, with: event)

         let statusBarRect = UIApplication.shared.statusBarFrame
         guard let touchPoint = event?.allTouches?.first?.location(in: self.window) else { return }

         if statusBarRect.contains(touchPoint) {
-            NotificationCenter.default.post(CAPBridge.statusBarTappedNotification)
+            NotificationCenter.default.post(name: .capacitorStatusBarTapped, object: nil)
         }
     }

     func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
-        NotificationCenter.default.post(name: Notification.Name(CAPNotifications.DidRegisterForRemoteNotificationsWithDeviceToken.name()), object: deviceToken)
+        NotificationCenter.default.post(name: .capacitorDidRegisterForRemoteNotifications, object: deviceToken)
     }

     func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
-        NotificationCenter.default.post(name: Notification.Name(CAPNotifications.DidFailToRegisterForRemoteNotificationsWithError.name()), object: error)
+        NotificationCenter.default.post(name: .capacitorDidFailToRegisterForRemoteNotifications, object: error)
     }

Ignore DerivedData

DerivedData を ios/.gitignore ファイルに追加します。これは、Capacitor CLI が iOS のネイティブビルドを配置する場所です。

 App/Pods
 App/App/public
 App/Podfile.lock
+DerivedData
 xcuserdata

 # Cordova plugins for Capacitor

Android

Capacitor 3 は、Android 5+に対応しています（現在は Android 11 にも対応しています）。Android Studio 4+が必要です。

Capacitor の Android プラットフォームの更新

npm install @capacitor/android@latest
npx cap sync android

Android プラグインの自動ロードに切り替える

Capacitor 3 では、Android のプラグインを自動的にロードすることが好ましいとされています。 MainActivity.javaでは、onCreateメソッドを削除することができます。これにより、npm でインストールしたプラグインを追加・削除する際に、このファイルを編集する必要がなくなります。

 public class MainActivity extends BridgeActivity {
-    @Override
-    public void onCreate(Bundle savedInstanceState) {
-        super.onCreate(savedInstanceState);
-
-        // Initializes the Bridge
-        this.init(savedInstanceState, new ArrayList<Class<? extends Plugin>>() {{
-            // Additional plugins you've installed go here
-            add(Plugin1.class);
-            add(Plugin2.class);
-        }});
-    }
 }

アプリケーションに専用のカスタムプラグインが含まれている場合は、onCreateでプラグインを登録する必要があります:

 public class MainActivity extends BridgeActivity {
     @Override
     public void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);

+        registerPlugin(PluginInMyApp.class);
     }
 }

Gradle の 7.0 へのアップデート

Capacitor のプロジェクトでは、Gradle 7.0 の使用を推奨しています。Android Studio で、Fileメニューを開き、Project Structureをクリックします。プロジェクトのセクションで、Gradle Versionを7.0に、Android Gradle Plugin Versionを4.2.0に変更します。そして、OK**をクリックします。

Project StructureダイアログのSuggestionsセクションで、Android パッケージのアップデート案を評価するとよいでしょう。

Android variables の更新

android/variables.gradleでは、以下の変数を更新することができます:

 ext {
     minSdkVersion = 21
-    compileSdkVersion = 29
-    targetSdkVersion = 29
+    compileSdkVersion = 30
+    targetSdkVersion = 30
+    androidxActivityVersion = '1.2.0'
-    androidxAppCompatVersion = '1.1.0'
+    androidxAppCompatVersion = '1.2.0'
+    androidxCoordinatorLayoutVersion = '1.1.0'
-    androidxCoreVersion =  '1.2.0'
-    androidxMaterialVersion =  '1.1.0-rc02'
-    androidxBrowserVersion =  '1.2.0'
-    androidxLocalbroadcastmanagerVersion =  '1.0.0'
-    androidxExifInterfaceVersion = '1.2.0'
-    firebaseMessagingVersion =  '20.1.2'
-    playServicesLocationVersion =  '17.0.0'
+    androidxCoreVersion = '1.3.2'
+    androidxFragmentVersion = '1.3.0'
-    junitVersion =  '4.12'
-    androidxJunitVersion =  '1.1.1'
-    androidxEspressoCoreVersion =  '3.2.0'
+    junitVersion = '4.13.1'
+    androidxJunitVersion = '1.1.2'
+    androidxEspressoCoreVersion = '3.3.0'
     cordovaAndroidVersion = '7.0.0'
 }

Capacitor 3 は Android 11(API 30)に対応していますので、SDK ターゲットを 30 にアップデートしてください。 compileSdkVersion と targetSdkVersion を 30 に変更してください。

新しい変数 androidxActivityVersion が用意されていますので、値を 1.2.0 として追加してください。

変数 androidxAppCompatVersion は 1.2.0 にアップデートできます。

新しい androidxCoordinatorLayoutVersion 変数が作成され、値が 1.1.0 になるように追加してください。

変数 androidxCoreVersion は 1.3.2 にアップデートできます。

変数androidxMaterialVersionは、Action Sheet や Camera プラグインで使用されていたもので、使用していない場合は削除できます。使用していない場合は削除できます。使用している場合は、Camera docs と Action Sheet docs を確認してください。

変数androidxBrowserVersion は、Browser プラグインが使用していました。このプラグインを使用していない場合は、削除することができます。プラグインを使っている場合は、docs を確認してください。

変数 androidxLocalbroadcastmanagerVersion は削除できます。

変数androidxExifInterfaceVersionは、Camera プラグインが使用していたもので、プラグインを使用していない場合は削除できます。プラグインを使用している場合は、docs を確認してください。

FirebaseMessagingVersion` 変数は Push Notifications プラグインで使用されていました。このプラグインを使用していない場合は、削除できます。プラグインを使用している場合は、docs を確認してください。

playServicesLocationVersion` 変数は、Geolocation プラグインで使用されていました。プラグインを使用している場合は、docs を確認してください。

新しい androidxFragmentVersion 変数が用意されていますので、値を 1.3.0 として追加してください。

junitVersionは4.13.1 にアップデートできます。

androidxJunitVersionは1.1.2 にアップデートできます。

The androidxEspressoCoreVersion は 3.3.0 にアップデートすることができます。

未使用および冗長なパーミッションの削除

使用しているプラグインに応じて、オプションでアプリの AndroidManifest.xml ファイルから未使用のパーミッションを削除することができます。パーミッションはプラグインのインストール時に追加されることになっているため、Capacitor の新アプリのマニフェスト には INTERNET しか含まれていません。以下の手順で、未使用のパーミッションを削除してください:

1. アプリが使用しているプラグインを特定する
2. 各プラグインのインストール手順を読み、各プラグインが必要とするパーミッションを探します。
3. アプリの AndroidManifest.xml ファイルで、プラグインが必要とするパーミッションを維持し、使用しないパーミッションを削除します。

Haptics プラグインと Network プラグインは、インストール時のパーミッションを独自の AndroidManifest.xml ファイルに含めるようになったプラグインの例で、最終的にはアプリのものに マージ されます。これらのプラグインのパーミッションは、アプリの AndroidManifest.xml ファイルから削除しても安全です。

     <!-- Permissions -->

     <uses-permission android:name="android.permission.INTERNET" />

-    <!-- Network API -->
-    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

-    <!-- Vibration API -->
-    <uses-permission android:name="android.permission.VIBRATE" />

 </manifest>