Capacitor 3 は、エコシステムに重要なアップデートとエキサイティングな新機能をもたらします。
アプリを Capacitor3 にアップグレードした後、何かフィードバックがあれば このディスカッション で共有していただけませんか?ご意見をお待ちしております 💖
プラグインを Capacitor の新しいバージョンにアップグレードしたいと考えているプラグイン作者の方は、 Upgrade Guide for Capacitor Plugins をご覧ください。
Node 8 は生産終了となりました。Node 10 は 2021 年 4 月 30 日に寿命を迎えます。Capacitor 3 は NodeJS 12 以上が必要です。(最新の LTS バージョンを推奨します。)
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
.
npm install @capacitor/cli@latest @capacitor/core@latest
Capacitor 3 は ES5 ではなく、ES2017 の環境でビルドされるようになりました。また、 プラグインテンプレートも ES2017 をターゲットに更新されました ので、サードパーティのプラグインもターゲットを更新することが推奨されます。
この変更は、Capacitor が公式にサポートしていない IE11 をサポートしている場合を除き、アプリに影響を与えることはありません。
Capacitor 3 は新しい TypeScript の構文を使用しており、TS 3.8 以降でしか使用できません。
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';
@capacitor-community/media
をご利用くださいopenUrl()
とcanOpenUrl()
)は App Launcher に移動しました。showActions()
)はActionsSheet 機能に移動しました。alert()
, prompt()
, confirm()
)はDialogに移動しました。この変更に伴い、これまで使用していたプラグインを個別にインストールする必要があります。
@capacitor/core
の
Plugins
オブジェクトから抽出したコアプラグインを検索しますIonic Framework を使っていますか?
Ionic Framework では、以下のプラグインで API を利用しています:
Ionic Framework で最高のユーザーエクスペリエンスを得るためには、アプリにプラグインをインポートしていなくても、これらのプラグインがインストールされていることを確認する必要があります:
npm install @capacitor/app @capacitor/haptics @capacitor/keyboard @capacitor/status-bar
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 への移行を容易にするために変更されませんが、一部のプラグインはコードの更新や手動での移行が必要になります。
isScreenReaderEnabled()
メソッドは、isEnabled()
に名称変更されました。accessibilityScreenReaderStateChange'
イベントは、'stateChange'
に名称変更されました。speak()
が動作します。スクリーンリーダーがアクティブかどうかに関わらず音声合成を行うには、@capacitor-community/text-to-speech
を使用してください。prefetch()
が削除されました。getInfo()
から削除されました(appVersion
, appBuild
, appId
, appName
)。この情報については、App プラグインのgetInfo()
を使用してください。uuid
は getInfo()
から削除されました。新しい getId()
関数を使用してください。HapticsNotificationType
列挙型のキーが、他の列挙型と一致するように、大文字からキャメルケースに変更されました。requestPermission()
が削除されたので、 requestPermissions()
を使用してください。requestPermission()
は削除されました。requestPermissions()
を使用してください。share()
メソッドは
any
ではなく
ShareResult
を返すようになりました。share()
の戻り値には、completed
が含まれなくなりました。完了しなかった場合は、代わりに拒否されます。migrate()
. エンドユーザーに影響を与えずにアプリを更新するには、他のメソッドの前に
migrate()
を呼び出してください。statute()
メソッドは、すべてのプラットフォームで ctime および mtime のタイムスタンプをミリ秒単位で返すようになりました。以前は、iOS はタイムスタンプを秒単位で返していました。Capacitor 3 では、hideLogs
設定オプションが非推奨となりました。これに代わって、新しい設定オプション
loggingBehavior
が導入されました。詳細はconfig ドキュメントに記載されています
Capacitor 3 は iOS 12+をサポートしています。Xcode 12+が必要です。CocoaPods 1.8+を推奨します。
CocoaPods を最新の安定版にアップグレードすることを推奨します。
CocoaPods 1.8 では CDN を使用するようになったため、pod repo update
を定期的に実行する必要がなくなりました。
CocoaPods のバージョンは
pod --version
で確認し、インストール方法は
cocoapods.org を参照してください。
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 を使用していない場合は、Xcode ターゲットのBuild Settingsタブを開き、Swift Compiler - LanguageセクションのSwift Language VersionをSwift 5に変更します。
public
を移動するCapacitor 3 では、ios/App/public
ディレクトリをios/App/App/public
に移動することが推奨されています。これは Xcode で実現できます:
既存のpublic
フォルダを削除する。
新しい場所でpublic
を再作成する
App
ターゲットに追加することを確認します)。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
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)
}
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 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
CAPNotifications
to NSNotification
extensionsios/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)
}
DerivedData
DerivedData
を ios/.gitignore
ファイルに追加します。これは、Capacitor CLI が iOS のネイティブビルドを配置する場所です。
App/Pods
App/App/public
App/Podfile.lock
+DerivedData
xcuserdata
# Cordova plugins for Capacitor
Capacitor 3 は、Android 5+に対応しています(現在は Android 11 にも対応しています)。Android Studio 4+が必要です。
npm install @capacitor/android@latest
npx cap sync 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);
}
}
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.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
しか含まれていません。以下の手順で、未使用のパーミッションを削除してください:
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>