すべての堅固な TypeScript API example for Capacitor は、型付きプラグインインターフェイスで始まります。 メソッド、オプション、Promise の結果を明示的に記述し、Web code とネイティブレイヤーは、TypeScript が実際に適用する共通契約を共有します。
目次
Capacitor プラグイン インターフェイスの型付け
インターフェイスは、APIが見るウェブcodeを説明します。
import { registerPlugin } from ‘@capacitor/core’;
export interface DeviceStatus { オンライン: boolean; バッテリー残量?: number; }
export interface DevicePlugin {
getStatus(): Promise}
export const Device = registerPlugin
ここでは、数行で何が起こっているのかが多くあります:
- 明示的な戻り値の型 結果を予測できるようにします。
- 型付きオプションオブジェクト コンパイル時点で、欠落しているプロパティやミススペルをキャッチします。
- 非同期メソッド モデルは、非同期で完了するnativeワークを実行します。
- 汎用的な
registerPlugin呼び出し APIのWebとnativeブリッジを接続するのは、どの呼び出しも - インターフェイス document the contract without adding a byte of runtime code.
各呼び出しサイトは同じ処理を受けます:
const status = await Device.getStatus(); console.log(status.online);
await Device.setLabel({ label: ‘生産用’ });
置換 { label: 'Production' } 代わりに { name: 'Production' } とコンパイラのフラグが即座にマッチングを検出します。 これは、モバイルリリース後にマッチングミスを発見することよりも優れています。
インターフェイスは、オプション値とエラーのケースをモデル化する場所でもあります。 例えば、ネイティブメソッドが常にバッテリーの読み取りを生成できない場合 batteryLevel?: number は、呼び出し元にエラーを伝えるように指示します。 undefined.
以下の図は、CapacitorとAPI内で型付けされたメソッド、オプション、戻り値、ブリッジ定義、コンパイル時チェックがどのように接続しているかを示しています。
核心の考え方は次のとおりです。 型定義は、Web向けインターフェイスからネイティブプラットフォームのロジックに向かって流れます。コンパイル時チェックは、各呼び出し元のところで警備をしています。
APIの__CAPGO_KEEP_1__のクイック検索
| 要素 | 目的 | Example |
|---|---|---|
| メソッド署名 | 呼び出しが可能な動作を定義します | getStatus() |
| オプションの型 | 入力の形状を制御します | { label: string } |
| Promiseの結果 | 非同期作業を表します | Promise<DeviceStatus> |
| 結果のインターフェイス | 返却されるデータを定義します | online: boolean |
APIの作成方法についての詳細な説明はこちらのガイドを参照してください TypeScriptでAPIを作成する方法についてのガイド. Two habits worth keeping: leave secrets and signing credentials out of client code, and test the interface against each platform implementation before you publish.
モバイルチームはJavaScript、ネイティブ code、デバイスのパーミッション、非同期のプラットフォームサービスを同時に扱う必要があります。 強力なTypeScript契約 各境界で共有チェックリストのように機能し、期待を明確にし、iOSやAndroidデバイスにcodeが到着する前に。
具体的な TypeScriptのAPIの例, 未型付けデータを返すメソッドと比較して、型付けされたバージョンは、エディターとすべてのレビュアーに存在するフィールドを明確に伝えます。未型付けバージョンは、実行時ログ、手動テスト、そして、最悪の場合、生産インシデントにその発見を押し付ける Promise<DeviceStatus> 採用信号
TypeScriptはフロントエンドのニッチを超えました。採用は2024年に35%に達し、2017年の12%から上昇しました
TypeScriptの採用は2024年に35%に達し、2017年の12%から上昇しました TypeScriptの採用は2024年に35%に達し、2017年の12%から上昇しましたTypeScriptの採用は2024年に35%に達し、2017年の12%から上昇しました 12%（２０１７年）、そして 1,000万人以上のGitHubコントリビューター 2025年までに、__CAPGO_KEEP_0__を主な言語としてリストした 詳細なTypeScript採用結果を確認するには ここにリンクがあります。
That trajectory matters for mobile organizations in practical ways. Hiring, onboarding, and code review increasingly revolve around shared types. Someone joining a Capacitor project can read an interface and understand the expected native behavior without tracing through every implementation.
型付きAPIは、リリース作業を簡素化します。メソッドが特定のオプションオブジェクトを要求すると、プロパティ名の変更や欠落したフィールドはコンパイル時点でエラーとなり、静かに半分の形のネイティブリクエストを生成するのではなく
強い型付けは、フィードバックを左にシフトします、修正が数分で、緊急のホットフィックスリリースが必要なくなります
Capacitorチームの利点
クロスプラットフォームアプリは、複数のネイティブ実装の上に置かれた1つのウェブ向けAPIを公開します。TypeScriptは、ネイティブの詳細がすべて同じように動作することを証明できないかもしれませんが、全体のアプリケーションで呼び出しを一貫して維持できます
明示的な型を適用してください
- メソッドの入力、必要なものとオプションを含む
- Promiseの結果、成功データは常に予測可能な形状を持ちます
- イベントとリスナー、コールバックは知られているペイロードを処理します
- エラーとステータス値、フォールバックパスは常に表示されます
その構造は、デバイスプラグインまたはオペレーショナルサービスを統合する際に有効になります。また、更新の自動化をレビューするチームにとっても役立ちます。間違ったチャネル、バンドル識別子、または互換性フィールドが大規模なユーザーベースに波及する可能性があります。
関連パターンについてのより深い理解を得るには、 OpenAPIを使用した型付きAPIの生成に関する. It covers how shared definitions reduce the manual drift that normally creeps in between API documentation and application code.
ビジネス上の論理
厳密な型付けは、古いJavaScript code が不一致のデータ形状を持つ場合に、前向きの投資が必要です。結果は時間の経過とともに現れます: 小さなリファクタリング、明確な所有権、遠く離れた統合の驚きが少なくなります。
リスクが最も高い境界から始めましょう:
- ネイティブとリモートの呼び出し用のレスポンスインターフェイスを定義します。
- オプションオブジェクトとイベントペイロードを型付けします。
- 厳格なコンパイラチェックを段階的に有効にします。
- 公開する更新前に型チェックを必須にします。
エンタープライズモバイルチームにとって、この基盤はプラットフォーム、リリース、コントリビューターを横断して、メンテナンスを予測可能にします。
Capacitor の ScreenOrientationPlugin は、 TypeScript API の例 が素晴らしい例です。少数のシンプルなWebメソッドを、プラットフォーム固有のデバイス動作にマップします。パブリック契約はプラットフォームを横断して同じままですが、iOSとAndroidはそれぞれネイティブの詳細を処理します。
import { registerPlugin } from ‘@capacitor/core’;
export type OrientationType = | ‘portrait-primary’ | ‘portrait-secondary’ | ‘landscape-primary’ | ‘landscape-secondary’;
export interface OrientationData { type: OrientationType; angle: number; }
export interface LockOptions { orientation: OrientationType; }
export interface ScreenOrientationPlugin {
orientation(): Promise}
export const ScreenOrientation =
registerPlugin}
各APIのサインチャーについてのクイックリファレンスです。
orientation()— 画面の現在の向きを非同期で読み取ります。lock()---unlock()---addListener()---
---
const current = await ScreenOrientation.orientation();
if (current.type.startsWith('landscape')) {
console.logAngle: ${current.angle});
}
await ScreenOrientation.lock({ orientation: 'landscape-primary', });
と誤った値を入力すると landscape-main 正しく型付けされたリスナーの引数を入力する
リスナーの引数は正しく型付けする
ここでは、イベントのペイロードと結果の差を隠すため any --- orientation() 戻り値。
const handleChange = (data: OrientationData) => {\ndocument.body.dataset.orientation = data.type;\n};
const subscription = await ScreenOrientation.addListener('screenOrientationChange', handleChange,);
await subscription.remove();
両方のネイティブ実装が同じフィールドを保証する場合にのみ、1 つの型を共有してください。 1 つのプラットフォームがフィールドを省略した場合、省略可能なフィールドとしてマークし、呼び出し元にフィールドを処理するよう強制します。 OrientationData デザイン上の選択 angle安全なパターン undefined.
| 入力 | 名前付きオプションインターフェイス |
|---|---|
| 結果 | Only share a single |
| Results | 明示のPromise型 |
| イベント | Literalイベント名 |
| クリーンアップ | 削除可能なサブスクリプションを返す |
インターフェイスはブリッジコントラクトであり、ネイティブ実装ではありません。 小さく、予測可能で、テスト可能なものに留めましょう。
プラットフォームの動作、権限、インストール手順については、 Capacitor スクリーン オリエンテーション プラグイン ガイド。最後に、厳格なTypeScript設定下で有効な呼び出しと拒否呼び出しをテストする習慣を身につけることをお勧めします。 その組み合わせは、パッケージされたモバイルアプリケーションよりも遥かに早く、間違ったメソッド名、欠落したフィールド、非互換のリスナーペイロードを検出します。
Capgo は、Capacitor チームに JavaScript、CSS、構成、資産の修正をプッシュする方法を提供します。 そのトリックは、更新パイプラインを他の型付き API 境界と同様に扱うことです。 したがって、チャンネル、ロールアウトルール、互換性チェック、ロールバック決定は、ユーザーのデバイスに到達する前に明示的に実行されます。
アップデート契約を定義する
アップデートの自動化を実行するには、まず自動化が受け入れる値を厳密に定義する必要があります。Literal unionsは間違って間違ったチャンネルにデプロイしないようにしてくれます。インターフェイスは、バンドルと必要なネイティブバージョンの関係を自明に説明してくれます。
型 Channel = ‘ベータ’ | ‘ステージング’ | ‘プロダクション’;
interface UpdateRequest { チャンネル: Channel; バンドルバージョン: string; 最小ネイティブバージョン: string; ロールアウトパーセント: number; 署名: boolean; }
interface UpdateResult { 受け入れ: boolean; 次の起動時に適用: boolean; ロールバック可能: boolean; }
簡単な TypeScript API の例 リクエストを検証する前に、Capgo クライアントにリクエストを渡します:
async function publishUpdate(
request: UpdateRequest,
): Promise
return capgo.publish(request);
クライアントのメソッド名は Capgo SDK のバージョンによって変わります。したがって、インターフェイスを介してメソッドをラップすることで、バージョンアップ時にvendor固有の詳細がコードベースに漏れ出さないようにすることができます。
保護されたチャネルと互換性
チャンネルの選択は軽率にすべきではない。生産的なリリースには、ベータ実験ほど厳格なチェックが必要であり、特にWebバンドルが古いアプリバージョンでないネイティブ機能を呼び出す場合
function canDeploy( request: UpdateRequest, installedNativeVersion: string, ): boolean { return request.signed && installedNativeVersion >= request.minNativeVersion; }
比較は文字列で行うのではなく、適切なシーケンスバージョンライブラリを取り込んでください 1.10.0 ソート後 1.9.0.
- リリース前にチェックリストを実行する
- バンドルが署名されていることを確認する
- ターゲットチャンネルが意図に合っていることを確認する
- ネイティブとバンドルの互換性範囲を比較する
- 限られたユーザーに公開する
タイプ付きの更新パイプラインは、リリースポリシーを code に変換し、レビューアーとCIが実際に検査できるようにします。
Capgoの差分配布とチャンネル制御は、そのパターンにうまくフィットしており、デバイスレベルの観察性は、事後的に採用または失敗の信号を追跡するのにチームをサポートしています。 Capgoのカスタムイベント追跡のガイド.
署名キーと管理者資格情報はサーバーやCIシステムに置くべきであり、実行中のアプリケーションには置かない。次の起動時にアップデートを適用し、意図的に拒否されたバンドルでロールバックテストを行い、型付きの結果で毎回の決定を記録する。そうすることで、迅速な配布は、厳格なモバイルリリース制御と互換性がある。
型付きリスナーが非同期APIを信頼できるものとして扱えるようにしている。スクリーンオリエンテーションを追跡するコールバックやCapgoのアップデートイベントのどちらも、同じプラットフォーム上で同じペイロードの形を取得するはずであり、コンパイラがその形を強制するべきである。
interface UpdateEvent { version: string; channel: ‘beta’ | ‘production’; available: boolean; }
Listener
interface UpdateService {
addListener(
event: 'updateAvailable',
callback: Listener
}
この TypeScript APIの例 イベント名をLiteralに固定し、型付きのペイロードにコールバックを紐付けます。エディターは自動補完を行います。 version 無料でエディターが自動補完を行い、コンパイラは関数が不適切なデータを期待している場合にのみエラーを投げます。API の変更ごとに、少しずつ設定するだけで、毎回効果を発揮します。
実際に動作を確認したい場合は、ウォークスルーをご覧ください。
リスナを安全に登録する
コンポーネント内では、サブスクリプションハンドルを保持して、クリーンアップを明示的に行うようにしてください。Angularライフサイクルハック、Reactエフェクト、Vueマウントハックに同じパターンを適用することもできます。
let orientationHandle: { remove: () => Promise} | undefined;
async function stop() { await orientationHandle?.remove(); orientationHandle = undefined; }
async function stop() { await orientationHandle?.remove(); orientationHandle = undefined; }
各フレームワークは、このようなハックを提供します:
Angular
- アングラーワーク 〜トリガーからクリーンアップを実行します。
ngOnDestroy - React 〜非同期安全なクリーンアップ関数を返します。
useEffect - Vue 〜サブスクリプションを削除します。
onBeforeUnmount
すべて
addListener各呼び出しには、削除パスを一致させる必要があります。
正しいクリーンアップ方法を選ぶ
1つのコンポーネントが1つのサブスクリプションを所有する場合、返されたハンドルは正しい呼び出しです。 removeAllListeners() サービスが複数のリスナーを保持し、完全にリセットされている場合に、明るく輝きます。
async function resetUpdates(service: UpdateService) { await service.removeAllListeners(); }
共有コンポーネントから広範なメソッドを呼び出さないようにしてください。サービスが依存する他の画面がまだ存在する場合です。所有権がローカルにある場合、個別の remove() ハンドルします。
| シチュエーション | 推奨アクション |
|---|---|
| 1つのコンポーネントサブスクリプション | 呼び出し handle.remove() |
| context | 呼び出し removeAllListeners() |
| HTMLテキストフラグメント | サービスシャットダウン |
| 繰り返し登録 | ガード初期化 |
通知の場合、Capgo の更新データはデバイスイベントとは別に保管する必要があります。次に、登録、配信、クリーンアップをそれぞれテストしてください。 Capgoのカスタムイベントトラッキングガイド は統合側についてさらに詳しく説明しています。
配信する前に、次の3点を確認してください:ハンドラが実際に削除されるかどうか、拒否されたPromiseがキャッチされるかどうか、そして破棄されたコンポーネントを更新することはできないかどうか。そうした disciplineは、Angular、React、Vueを含むリアクティブCapacitorアプリをレスポンシブに保つことができます。
よく作られた TypeScriptAPIの例 は、意図を表す名前で始まります。メソッドには動詞を、インターフェイスには名詞を使用し、一定の接尾辞を使用してください、例えば、 Options, Result、 Event。明確な名前は、開発者が実装を開くことなく契約を理解できるため、オンボーディング時間を短縮します。
公開インターフェイスを小さく保ちましょう。関連する操作を単一のオブジェクトにダンプするのではなく、焦点を絞ったメソッドを通じて機能を公開してください。
getStatus()状態を読み取る。updateConfig(options)構成を変更する。addListener(event, callback)変更を監視します。
入出力の型を正確に指定します。
パラメータが増加する可能性がある場合、名前付きオプションインターフェイスを使用します:
interface PublishOptions { channel: ‘beta’ | ‘production’; rolloutPercent: number; }
interface PublishResult { バージョン: string; 受け入れ: boolean; }
async function publish(__CAPGO_KEEP_0__)
ジェネリックは、API が異なるペイロードをラップするが、その特定の型を保持する必要がある場合に役立ちます:
APIレスポンス
async function request
無効な状態を表現するのは難しいものです
特にネイティブ、ネットワーク、更新境界で, すでにあるネットワーク、更新の境界点に特にあります。
__CAPGO_KEEP_0__の変更を整理する
変更のために Code を整理する
関心事
| 推奨される場所 | パブリックインターフェイス |
|---|---|
| __CAPGO_KEEP_0__メソッド | types.ts |
| API メソッド | client.ts |
| Native アダプタ | platform/ |
| 互換性テスト | tests/ |
プラグインの変更が大きい場合、主なインターフェイスまたは互換性レイヤーを新しく作成し、非推奨のメソッドを一時的に残し、移行手順を書き留めましょう。 API バージョニング戦略についてもっと学びましょう 変更する前に消費者に伝えましょう。
CI で厳密な型チェックと契約テストを実行し、出荷する前に実行してください。 Capgo ワークフローでは、チャンネル値、ネイティブ互換性、署名されたバンドル、ロールバック動作を型付きのリリースルールとして検証してください。これにより、チーム、プラットフォーム、統合が増えるときに、高速な更新を制御できます。
動的ネイティブ結果の型付けはどうすればいいですか?
Don’t let any code に漏れさせないでください。代わりに、期待できるフィールドを明示的に記述し、 ?で、実際にオプションの値をマークし、不確実な入力を境界で消毒することで、下流のシステムが触れる前にデータを整理しましょう。
interface NativeResult { success: boolean; value?: string; }
async function readValue(): Promise
このアプローチは、呼び出し元を安全に保ちながら、型自体に不確実性を明示的に表現します。このインターフェイスパターンについてより広い視点で見るには、再び TypeScriptでAPIを構築する.
リスナがUnhandled Rejectionを避ける方法
非同期コールバックは、設計上防御的でなければなりません。リスナー内で失敗をキャッチし、イベントシステムに依存して静かに拒否されたプロミスを飲まないようにします。
const handleUpdate = (event: UpdateEvent): void => { void applyUpdate(event).catch((error: unknown) => { console.error(‘Update failed’, error); }); };
サブスクリプションの参照を保持し、コンポーネントがアンマウントされる際にそれを削除することで、重複コールバックと古い状態の更新を防ぎます。この詳細は、リスナー ライフサイクルセクションで説明されています。
すべての非同期リスナーには、エラー パスとクリーンアップ パスが必要です。
Capgoの保護方法はどれですか?
署名キーと管理者用クレデンシャルはサーバーまたはCIシステムに残ります。クライアントは署名されたバンドルを受け取り、型付き結果をステータス表示に使用するのみで、署名を作成することはありません。
公開する前に、別々のチャネル unionを設定し、互換性チェックを実行し、ロールアウト制限を構成し、ロールバックパスを計画してください。 Capgo 署名配信、チャンネル制御、次のリリースアプリケーション、ロールバック保護を Capacitor と Electron アプリケーションに提供します。ドキュメントでは、型付きリリースワークフローがアップデートパイプラインを強化する方法を示しています。
