すべての堅実な TypeScript API の例 for Capacitor begins the same way: with a typed plugin interface. Spell out your methods, options, and Promise results explicitly, and your web code and the native layer share one contract that TypeScript actually enforces.
目次
強く型付けされたCapacitor プラグインインターフェイスを構築する
The interface describes the API your web code sees. The native implementation behind it has to honor that contract — and TypeScript checks method names, parameters, and return values before your app ever runs.
import { registerPlugin } from ‘@capacitor/core’;
export interface DeviceStatus { オンライン: boolean; バッテリー残量?: number; }
export interface DevicePlugin {
getStatus(): Promise
}
export const Device = registerPlugin
(‘Device’);
- それだけの行に多くのことが起こっています: 明示的な戻り値の型
- 結果を予測できるようにする 型付けされたオプションのオブジェクト
- コンパイル時点で欠落したプロパティやスペルミスをキャッチする Promiseベースのメソッド
- ネイティブの作業を非同期で完了する
registerPlugin汎用的な関数呼び出し ウェブ API とネイティブ ブリッジを接続するものはこれです。 - インターフェイス 契約書を記述するだけで、実行時 code のバイト数を増やさない。
各呼び出し元は同じ処理を受けます:
const status = await Device.getStatus(); console.log(status.online);
await Device.setLabel({ label: '生産' });
入れ替え { label: 'Production' } for { name: 'Production' } インターフェイスは、オプション値とエラーのケースをモデル化する場所でもあります。ネイティブ メソッドが常にバッテリーの読み取りを提供できない場合
呼び出し元に batteryLevel?: number 以下の図は、型付けされたメソッド、オプション、戻り値、ブリッジ定義、コンパイル時チェックが __CAPGO_KEEP_0__ 内の __CAPGO_KEEP_1__ でどのように接続しているかを示しています。 undefined.
Capgoの図では、型付けされたメソッド、オプション、戻り値、ブリッジ定義、コンパイル時チェックは、CapacitorとAPI内でつながっています。
基本概念 Type definitions flow from the web-facing interface toward native platform logicコンパイル時チェックは、すべての呼び出し元で警戒する。
API のデザインのためのクイック検索
| Element | 目的 | Example |
|---|---|---|
| メソッド署名 | 呼び出し可能な動作を定義する | getStatus() |
| オプションの型 | 入力の形状を制御する | { label: string } |
| Promise 結果 | 非同期作業を表す | Promise<DeviceStatus> |
| 結果インターフェイス | 返却データを定義 | online: boolean |
より深い参照のために、TypeScript で API を構築するためのガイドを参照してください。 TypeScript で API を構築するためのガイド。2 つの習慣を維持してください: クライアント code からシークレットと署名認証情報を除外し、各プラットフォーム実装に対してインターフェイスをテストする前に公開する。
モバイルチームは JavaScript、ネイティブ code、デバイスパーミッション、非同期プラットフォームサービスを同時に管理する必要があります。 A 強力な TypeScript コントラクトは、iOS または Android デバイスに到達する前に、各境界で期待を明確にするように、共有チェックリストのように機能します。 iOS または Android デバイスに到達する前に、各境界で期待を明確にするように、共有チェックリストのように機能します。 各境界で共有チェックリストのように機能し、期待を明確にすることで、iOSやAndroidデバイスにcodeが到着する前に。
TypeScript で API を構築するためのガイドを参照してください。 TypeScript API example, __CAPGO_KEEP_1__ と __CAPGO_KEEP_2__ を比較する Promise<DeviceStatus> 型付けされていないデータを返すメソッドと型付けされたデータを返すメソッドの違い
型付けされたバージョンは、エディターとすべてのレビュアーにフィールドが存在することを明示的に伝えます。
型付けされていないバージョンは、ランタイムログ、手動テスト、そして最悪の場合、生産インシデントにその発見を押し付けることになります。 採用信号TypeScriptはフロントエンドのニッチを超えて進んでいます。 採用率は2024年には35%の開発者に達しました one million GitHub contributors 12%にしかなかった そして2025年には100万人以上の__CAPGO_KEEP_0__コントリビューターが主な言語としてリストアップしました。 もし、raw numbersが必要なら。
モバイル組織にとって、Trajectoryは実際的な意味合いを持つ。採用、入社、そしてcodeのレビューは、共有されたタイプに依存するようになっている。Capacitorのプロジェクトに参加した新人は、インターフェイスを読むだけで、期待されるネイティブの動作を理解できる。
Typed APIはリリース作業を簡単に理解できるようにする。特定のオプションオブジェクトを要求するメソッドがある場合、リネームされたプロパティや欠落したフィールドはコンパイル時点でエラーを発生させる。静的チェックにより、ネイティブの要求が半分形成されたものとならない。
強い型付けは、フィードバックを左にシフトさせる。フィードバックが左にシフトされると、修正が数分で済むようになる。緊急のホットフィックスリリースは必要なくなった。
Capacitorチームの利点
クロスプラットフォームアプリは、複数のネイティブ実装の上に座る1つのウェブ向けAPIを公開する。TypeScriptは、ネイティブの詳細がすべて同じ動作をしていることを証明できないが、全体のアプリケーションで呼び出しを一貫して保つことができる。
明示的な型を適用する:
- メソッドの入力、必要なオプションとオプション
- Promiseの結果、成功データは予測可能な形状を持ちます
- イベントとリスナー, したがって、コールバックは既知のペイロードを処理します
- エラーとステータス値, したがって、フォールバックパスは表示され続けます
デバイスプラグインまたはオペレーショナルサービスを統合する際に、その構造は有効になります。 また、更新の自動化をチームがレビューする際にも役立ちます。 ここでは、間違ったチャネル、バンドル識別子、または互換性フィールドが大規模なユーザー ベースに波及する可能性があります。
関連パターンについてのより深い理解を求めている場合は、 OpenAPIを使用した型付きAPIの生成に関する.APIドキュメントと.codeアプリケーション間の通常のマニュアルドリフトを削減する共有定義について説明します。
ビジネス上の論理
Strict typing does ask for some upfront investment, especially when older JavaScript code carries inconsistent data shapes. The return shows up over time: smaller refactors, clearer ownership, and far fewer integration surprises.
「リスクが最も高い境界から始めましょう」
- リスクが最も高い境界から始めましょう:
- TypeScriptオプションオブジェクトとイベントペイロードを入力してください。
- 厳格なコンパイラチェックを段階的に有効にします。
- 公開される更新前に型チェックを必須にします。
企業向けモバイルチームにとって、この基盤はリリース、プラットフォーム、コントリビューター間でメンテナンスを予測可能にします。
CapacitorのScreenOrientationPluginは素晴らしい TypeScript APIの例 __CAPGO_KEEP_0__は、シンプルなWebメソッドをプラットフォーム固有のデバイス動作にマップすることで、ハンドフル数の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
(‘ScreenOrientation’);
—現在のオリエンテーションを非同期に読み取ります
orientation()—のみ有効なオリエンテーション値を受け入れますlock()—通常のデバイスの動作にコントロールを戻しますunlock()—オリエンテーションが変更されたときに型付きのペイロードを発火しますaddListener()すべてのメソッドが Promise を返すため、ネイティブブリッジとブラウザ実装に対して同じコールパターンを使用できます。ブランチング、特殊ケースなし。
ロックオプションを指定してロックします： Promise
const current = await ScreenOrientation.orientation();
if (current.type.startsWith(‘landscape’)) {\nconsole.log("Angle: ${current.angle});
}
await ScreenOrientation.lock({ orientation: 'landscape-primary', });
正しくない値を入力すると landscape-main 即座にビルドが失敗する。 そのようなエラーは数秒で修正できるが、デバイスのログを追跡するプラットフォーム固有のランタイムのバグではありません。
正しくListenerの引数を指定する
リスナは通常のメソッドと同じ厳密さを必要とする。 以下の例のように、リスナの引数を省略してはいけない。 any リスナの引数を省略すると、イベントのペイロードと結果の差がわかりにくくなってしまう。 orientation() returns.
const subscription = await ScreenOrientation.addListener( ‘screenOrientationChange’, handleChange, );
await subscription.remove();
const current = await ScreenOrientation.orientation();
両方のネイティブ実装が同じフィールドを保証する場合にのみ、1つのタイプを共有してください。 OrientationData 1つのプラットフォームがフィールドを省略する場合、省略可能なものとしてマークし、呼び出し元にフィールドをハンドルするように強制してください。 angle設計上の選択肢 undefined.
| 安全なパターン | 入力 |
|---|---|
| Inputs | 結果 |
| 明示的なPromise型 | イベント |
| Literalイベント名 | クリーンアップ |
| protectedTokens | キャンセル可能なサブスクリプションを返します。 |
インターフェイスはブリッジ契約であり、ネイティブ実装ではありません。 小さく、予測可能で、テスト可能なものにしましょう。
プラットフォームの動作、権限、インストール手順については、以下の Capacitor スクリーン オリエンテーション プラグイン ガイドを参照してください。 一度習慣として取り入れておくべき最後の習慣は、厳密なTypeScript設定下で有効な呼び出しと拒否された呼び出しをテストすることです。 その組み合わせは、パッケージ化されたモバイルアプリケーションよりも遥かに早く、間違ったメソッド名、欠落しているフィールド、不相応なリスナー ペイロードをキャッチします。
Capgo は、Capacitor チームに、JavaScript、CSS、構成、資産の修正を、アプリストアのレビューを待たずにプッシュする方法を提供します。 そのトリックは、更新パイプラインを、他の型付き API 境界と同様に扱うことです。 したがって、チャネル、ロールアウトルール、互換性チェック、ロールバック決定は、ユーザーのデバイスに到達する前に明確になります。
更新契約を定義する
まず、自動化が受け入れる値を厳密に定義してください。Literal Unionは間違って、間違ったチャネルに展開しないようにします。 インターフェイスは、バンドルと必要なネイティブ版の関係を自明にします。
type Channel = ‘beta’ | ‘staging’ | ‘production’;
interface UpdateRequest { channel: Channel; bundleVersion: string; minNativeVersion: string; rolloutPercent: number; signed: boolean; }
interface UpdateResult { accepted: boolean; appliedOnNextLaunch: boolean; rollbackEnabled: boolean; }
直感的に理解できる TypeScript API example リクエストを検証し、Capgo クライアントに渡します。
async function publishUpdate(
request: UpdateRequest,
): Promise
return capgo.publish(request);
クライアントのメソッド名は、Capgo SDK のバージョンによって変わります。したがって、独自のインターフェイスを用いてラップすることをお勧めします。アップグレードの度にこの隔離が効果を発揮し、コードベースにバイヤー固有の詳細が漏れ出さないようにします。
Guard チャンネルと互換性
チャンネルの選択は軽率にすべきではない。生産的なリリースには、ベータ実験よりも厳格なチェックが必要であり、ウェブパッケージが以前のアプリバージョンでは存在しなかったネイティブ機能を呼び出す場合に特にそうだ。
function canDeploy( request: UpdateRequest, installedNativeVersion: string, ): boolean { return request.signed && installedNativeVersion >= request.minNativeVersion; }
バージョンを単純な文字列で比較しないでください。正しい意味のあるバージョン管理ライブラリを取り込んでください。 1.10.0 ソートされる 1.9.0チェンネルに何かが到達する前に、チェックリストを実行してください。
- チャンネルに流す前に、以下のチェックリストを実行してください:
- バンドルの署名を確認する。
- ターゲットチャンネルが意図どおりであることを確認する。
- ネイティブとバンドルの互換性範囲を比較する。
- 最初は限られたユーザーに公開する。
アップデートパイプラインは、型付きのもので、リリースポリシーを code に変換し、レビュアーとCIが実際に検査できるものになります。
型付きの更新パイプラインは、リリースポリシーを Capgo に変換し、レビューアとCIが実際に検査できるようにします。 this guide to custom event tracking with Capgo.
このガイドを参照してください: __CAPGO_KEEP_0__ を使用したカスタムイベントトラッキングのガイド
Typed listeners are what make asynchronous APIs easy to trust. Whether a callback tracks screen orientation or a Capgo update event, it should receive the same payload shape on every platform — and the compiler should be the one enforcing that.
interface UpdateEvent { version: string; channel: ‘beta’ | ‘production’; available: boolean; }
リスナー
interface UpdateService {
addListener(
event: 'updateAvailable',
callback: Listener
}
This TypeScript API example は、イベント名をLiteralに固定し、Typed Payloadにコールバックを紐付けます。エディターは自動補完が可能で、コンパイラは関数の引数が不一致の場合にエラーを返します。__CAPGO_KEEP_0__の変更が発生するたびに、少しずつ設定するだけで、毎回の変更で効果を発揮します。 version for free, and the compiler rejects any callback that expects unrelated data. It’s a small amount of setup, and it pays off every time the API changes.
リスナーを安全に登録する
リスナーを安全に登録する
コンポーネント内では、サブスクリプションハンドルを保持して、クリーンアップを明示的に行うようにします。同様のパターンは、Angularライフサイクルハック、Reactエフェクト、Vueマウントハックに適用できます。変更はありません。
let orientationHandle: { remove: () => Promise}
async function start() { orientationHandle = await ScreenOrientation.addListener( ‘screenOrientationChange’, ({ type, angle }) => { console.log(type, angle); }, ); }
async function stop() { await orientationHandle?.remove(); orientationHandle = undefined; }
画面が消えるときに、クリーンアップを実行してください。アプリ全体が終了するときだけではありません。スキップすると、ナビゲーションがネイティブイベントソースにコールバックを残します。結果は、重複した作業と古い状態の更新が、追跡が困難な痛みが生まれます。
各フレームワークは、このようなハックを提供します:
- Angular — クリーンアップをトリガーする
ngOnDestroy - React — アSYNCセーフなクリーンアップ関数を返す
useEffect - Vue — サブスクリプションを削除する
onBeforeUnmount
すべての
addListener呼び出しには、対応する削除パスが必要です。
適切なクリーンアップ方法を選択する
サービスが複数のリスナーを保持し、完全にリセットされている場合に、サービスが所有する場合に返されたハンドルは正しい呼び出しです。 removeAllListeners() async function resetUpdates(service: UpdateService) {
await service.removeAllListeners();
}
共有コンポーネントから、他の画面が依存しているサービスに広範なメソッドを呼び出さないようにしてください。所有権がローカルである場合、個々のハンドルに従います。
状況 remove() 推奨アクション
| コンポーネントのサブスクリプション | 一つのコンポーネントのサブスクリプション |
|---|---|
| 個々のハンドル | Call handle.remove() |
| サービス停止 | Call removeAllListeners() |
| 再登録 | ガード初期化 |
| 不明なペイロード | 使用する前に検証 |
Capgo の通知の場合、更新のペイロードをデバイスイベントから分離し、登録、配信、クリーンアップを個別にテストすることができます。Capgo のカスタムイベントトラッキングガイドには、統合側の詳細が記載されています。 Capgo のカスタムイベントトラッキングガイド API統合の詳細はこちらです。
専門のソフトウェア開発者が Capacitor を2台のモニターとヘッドフォンで作業しています。
A well-built TypeScript API example メソッド名は動詞で、インターフェイス名は名詞で、接尾辞を一貫して使用する。 Options, Result, and Eventクラス名が明確なので、初期設定時間が短縮されます。開発者は実装を開くことなく、契約を理解できます。
パブリックインターフェイスを小さく保つ。特定の機能を提供するための集中したメソッドを使用し、関連性のない操作を単一のオブジェクトにまとえないようにする。
getStatus()ステートを読み取る。updateConfig(options)設定を変更する。addListener(event, callback)更新が発生した場合に自動的に反映されるように、変更をサブスクライブします。
Type Inputs and Outputs Precisely
パラメータが増加する可能性がある場合、名付けられたオプションインターフェイスを使用してください。
interface PublishOptions { channel: ‘beta’ | ‘production’; rolloutPercent: number; }
interface PublishResult { バージョン: string; 受け入れ: boolean; }
async function publish(__CAPGO_KEEP_0__)
型指定が役に立つのは、API が異なるデータをラップしながら、その特定の型を保持する必要がある場合です:
APIレスポンス
async function request
ただし、型指定を単に柔軟性を示すために追加しないでください。型指定は、入力と出力の間の実際の関係を表すものでなければなりません。そうでない場合は、具体的なインターフェイスが読みやすく維持しやすくなります。
無効な状態を表現するのは難しいようにしましょう、特にネイティブ、ネットワーク、更新境界でのこと。
契約とともに動作を記述する。許可、単位、拒否されたPromise、オプションフィールド、メソッドの即時適用か次の起動時かをカバーする。インラインコメントは決定を説明するようにし、メソッド名を繰り返すのではなく。
Codeの変更についての組織
型、クライアントロジック、プラットフォームアダプター、テストを予測可能なファイルに分ける。1つのエントリポイントから公開型をエクスポートし、実装詳細をプライベートに保つ。
| 関心事 | 推奨場所 |
|---|---|
| 公開インターフェイス | types.ts |
| APIメソッド | client.ts |
| ネイティブアダプター | platform/ |
| 互換性テスト | tests/ |
プラグインの変更が破壊的である場合、新しいメジャーインターフェイスまたは互換性レイヤーを導入し、廃止されたメソッドを一時的に残し、移行手順を記述する。 APIバージョニング戦略についてもっと学ぶ 変更される消費者.
CIで厳格な型チェックと契約テストを実行し、Capgoワークフローではチャンネル値、ネイティブ互換性、署名済みバンドル、ロールバック動作を型付きリリースルールとして検証し、チーム、プラットフォーム、統合の成長に伴って高速な更新を制御する。
動的ネイティブ結果をどのように型付けするか?
Don’t let any codeに漏れ込まないようにしてください。代わりに、期待できるフィールドを明示的に記述し、 ?ネイティブメソッドが返した値が不確実な場合にのみ使用します。
NativeResult インターフェイス { success: boolean; value?: string; }
async function readValue(): Promise
このアプローチは、呼び出し元を安全に保ちながら、型自体で不確実性を明示的に表現します。より広い視点でAPIをTypeScriptで構築する方法については TypeScriptでAPIを構築する.
リスナーは、未処理の拒否を避けるにはどうするか?
Asynchronous callbacks need to be defensive by design. Catch failures inside the listener itself rather than trusting the event system to swallow rejected promises silently.
const handleUpdate = (event: UpdateEvent): void => { void applyUpdate(event).catch((error: unknown) => { console.error(‘Update failed’, error); }); };
Componentのアンマウント時にサブスクリプションの参照を保持し、削除することで、重複のコールバックと古いステートの更新を防ぎます。
すべての非同期リスナーには、エラーのパスとクリーンアップのパスが必要です。
How Do I Protect Capgo Updates?
サーバーやCIシステムに署名キーと管理者用クレデンシャルを保持し、クライアントは署名されたバンドルを受信し、型付き結果を使用してステータスを表示するのみで、署名を作成することはない。
CapgoへのPRを提出する前に、別々のチャンネルユニオンを設定し、互換性チェックを実行し、ロールアウトの制限を設定し、ロールバックのパスを計画する。 Capgo handles signed delivery, channel controls, next-launch application, and rollback protection for Capacitor and Electron apps. Their docs show how typed release workflows can tighten up your update pipeline.
