On this page
ネイティブブリッジとプラグイン
はじめに
ネイティブブリッジを使用するとウェブスタックから離れることなくios、android、desktop上のデバイスapiにjavascriptコードからアクセスできます。すべてが単一のオブジェクトApp.nativeを通じて公開されすべてのプラットフォームで同じように動作します。
各機能は「プラグイン」です。フレームワークには6つのコアプラグインが同梱されており必要に応じて独自のプラグインを自由に追加できます。すべてのプラグインは同じ4ファイル規約(言語ごとに1ファイル)に従うためjavascriptで一度記述したメソッドにはswift、kotlin、rustの対応する実装が存在し必要に応じて実装またはスキップできます。
このドキュメントではその両面を扱います。アプリケーションコードから呼び出す公開App.native.*インターフェースと機能をプラットフォーム上でネイティブに実行したい場合に使用する4ファイルの構成です。
App.nativeファサード
App.nativeはブラウザとネイティブwebviewの両方でグローバルスコープに自動的に添付されるオブジェクトです。各プラグインはこのオブジェクトのプロパティであり各プロパティはプラグインのメソッドを直接公開します。
1// every call is a promise2const pub = await App.native.crypto.generate();3await App.native.storage.set('theme', 'dark');4const id = await App.native.notifications.show('pairing complete', 'tap to open', 'pairing-1');
メソッド呼び出しの解決方法
App.native.<plugin>.<method>(args)を呼び出すとブリッジはネイティブランタイムが起動時に登録したプラグインごとのメソッドマップを確認します:
- メソッドがネイティブメソッドとして登録されている場合呼び出しはネイティブレイヤー(iosではswift、androidではkotlin、desktopではtauriコマンド)に転送されネイティブの結果がpromiseとして返されます。
- メソッドがネイティブとして登録されていない場合呼び出しはjavascriptリファレンス実装を直接実行します。これはそのプラットフォームにネイティブファイルが存在しないプラグイン(例: desktop audio、desktop notifications、desktop crypto、desktop device)の場合やネイティブレイヤーが応答しない場合のフォールバックとして発生します。
この判定はプラグイン単位ではなくメソッド単位で行われます。同一プラットフォーム上でアプローチを混在させたい場合audio.playをネイティブとして登録し(iosでavplayerを使用)、audio.loadを未登録のままにしておく(html audio要素を使用)ことができます。
Promiseとエラー
App.native.*のすべてのメソッドはpromiseを返します。リジェクト時には明確なエラーメッセージが含まれます。真偽値を返すメソッド(ストレージ書き込みの成功など)は例外をスローせず失敗時にfalseを返します。処理を継続できないメソッド(apiが利用できない場合のnotificationsなど)はエラーをスローします。
最もシンプルな呼び出しにはasync関数内で単一のawaitを使用します:
1const granted = await App.native.notifications.requestPermission();2if (granted !== 'granted') {3 notify('enable notifications to receive pairing events', 'warning');4 return;5}
自動登録されるコアプラグイン
フレームワークは6つのコアプラグインを自動的に登録します。各プラグインの詳細は以下のとおりです:
auth(ローカルセッションidと汎用キーバリューストア)device(プラットフォームおよびモデルのメタデータ)storage(汎用文字列キーバリューストア)crypto(ecdsa p 256 sha 256のキーペア生成、署名、検証、ダイジェスト)audio(メディアセッションメタデータを備えた単一url再生)notifications(ローカル通知の表示とキャンセル)
authプラグイン
authプラグインはすべてのデバイスに安定したセッションidと独自データを永続化するための小さなキーバリューストアを提供します。web実装ではlocalStorageを使用しios実装ではUserDefaults、android実装では専用のSharedPreferencesファイルを使用します。すべてのプラットフォームにおいてセッションキーはdstrn.session.id配下に名前空間が設定されキーバリューストアはdstrn.db.<key>配下に名前空間が設定されるため独自キーがセッションと衝突することはありません。
App.native.auth.setSession(id)
idを現在のデバイスセッションとして保存します。文字列に型変換されます。成功時はtrueを返し基礎となるストレージが例外をスローした場合(localStorageへの書き込みがブロックされるプライベートブラウジングモードなど)はfalseを返します。
1await App.native.auth.setSession(loginResponse.token);App.native.auth.getSession()
保存されているセッションidを文字列として返します。保存されていない場合や読み取りで例外が発生した場合はnullを返します。
1const id = await App.native.auth.getSession();2if (!id) redirect('/login');App.native.auth.clearSession()
保存されているセッションを削除します。成功時はtrue、ストレージエラー時はfalseを返します。
1await App.native.auth.clearSession();2redirect('/');App.native.auth.db_get(key)
以前にdstrn.db.<key>配下に保存された値を読み取ります。呼び出し元が保存した生の文字列を返します。キーが設定されていない場合はnullを返します。
1const lastDeviceId = await App.native.auth.db_get('last_device_id');App.native.auth.db_set(key, value)
dstrn.db.<key>配下にvalueを保存します。valueはそのまま保存されるためjson文字列は展開されたり再エンコードされたりすることなく保持されます。成功時はtrue、ストレージエラー時はfalseを返します。
1await App.native.auth.db_set('last_device_id', deviceId);2await App.native.auth.db_set('user_blob', JSON.stringify(user));authプラグインに関する注意点
db_setは値の検証を行わないためパース済みオブジェクトを保存すると[object Object]になります。必ず文字列を保存してください。- db名前空間はstorageプラグインとは意図的に分離されており必要に応じて2つ目の独立したキーバリューストアとして利用できます。
- webでは両方の名前空間が
localStorageに存在するためサイトデータを消去すると両方とも削除されます。
deviceプラグイン
deviceプラグインは現在のデバイスのプラットフォームとモデルをレポートします。iosではデバイスのUIDevice.current.nameとモデル識別子を返しandroidではBuild.MANUFACTURER + Build.MODELを返しdesktopではホスト名を返します。webでは3つのメソッドがそれぞれnavigator.userAgent、navigator.platform、および文字列'web'を返します。
App.native.device.name()
人間が読めるデバイス名を返します。iosでは設定 > 一般 > 情報 > 名前で設定された名前(例: "jane's iphone")になります。androidでは製造元とモデルを結合した文字列(例: "google pixel 8")になります。desktopではホスト名になります。webではユーザーエージェント文字列になります。常に文字列を返しプラットフォームにアクセスできない場合は'unknown'にフォールバックします。
1const name = await App.native.device.name();2els.deviceBadge.textContent = name;App.native.device.model()
製造元を含まないモデル識別子を返します。iosでは'iPhone'または'iPad'、androidではモデル名、desktopではホスト名になります。webではnavigator.platformになります。常に文字列を返しフォールバック時は'unknown'を返します。
1const model = await App.native.device.model();App.native.device.platform()
'ios'、'android'、'desktop'、'web'のいずれかを返します。これはランタイムごとに処理を分岐する最もシンプルな方法です。
1const platform = await App.native.device.platform();2if (platform === 'ios' || platform === 'android') {3 // enable native only features4}
storageプラグイン
ユーザー設定やui状態のための軽量な汎用キーバリューストアです。webではlocalStorage、iosではUserDefaults、androidではSharedPreferences、desktopではプラットフォームのアプリケーションデータディレクトリ内のjsonファイルをバックエンドとします。値は常に文字列です(プラグインは書き込み時に非文字列の値を文字列に変換し読み取り時にはそのまま返します)。
storageプラグインとauth dbストアは独立した名前空間です。保存する対象の意味に合わせて使い分けてください。
App.native.storage.set(key, value)
key配下にvalueを保存します。成功時はtrue、失敗時はfalseを返します。非文字列の値はString(value)によって変換されるため読み取り時に適切に扱う限り数値、真偽値、json文字列のいずれも動作します。
1await App.native.storage.set('theme', 'dark');2await App.native.storage.set('fontSize', 16);3await App.native.storage.set('lastSeen', String(Date.now()));App.native.storage.get(key)
保存されている文字列を返します。キーが設定されていない場合はnullを返します。存在しないキーと空文字列を区別するには明示的にnullをチェックしてください。
1const theme = await App.native.storage.get('theme');2if (theme === null) {3 // first run4}App.native.storage.remove(key)
保存された値を削除します。値が削除された場合はtrueを返しそれ以外の場合はfalseを返します(キーが既に存在しない場合を含む)。
1await App.native.storage.remove('theme');storageプラグインに関する注意点
keys、clear、listメソッドはありません。これらが必要な場合は固定キー配下のjson配列として独自に永続化してください。- 約5メガバイトを超える値は一部のプラットフォームで失敗する可能性があります(
localStorageにはオリジンごとのクォータがあります)。大きなblobはウェブフレームワークのStorage.disk()を使用して保存してください。 - iosおよびandroidではストレージ書き込みは同期的ですがブリッジが解決前に待機するためpromiseパターンは期待どおりに機能します。
cryptoプラグイン
cryptoプラグインはすべてのデバイスに安定したecdsa p 256 sha 256キーペアを提供し署名、検証、ダイジェストのためのヘルパーを備えています。すべてのプラットフォームでバイト単位で同一のキーと署名が返されるためiosで生成された署名はandroid、web、desktopでも検証できます。
キーペアはすべてのプラットフォームで安定したエイリアスに永続化されます(iosキーチェーンのcom.dstrn.crypto.main_key、androidキーストアのdstrn_crypto_main_key、webのindexeddbの同一エイリアス)。generate()の呼び出しはべき等です(初回の呼び出しでキーペアを作成して永続化しそれ以降の呼び出しでは同じ公開キーを返します)。秘密キーが安全なストアから外部に出ることはありません。
App.native.crypto.generate()
デバイスの公開キーをbase64エンコードされた生の非圧縮ポイント(0x04で始まる65バイト)およびアルゴリズム文字列'ECDSA-P256-SHA256'として返します。べき等であり同一デバイス上でgenerate()を繰り返し呼び出しても常に同じ公開キーが返されます。
1const { publicKey, algorithm } = await App.native.crypto.generate();2console.log(algorithm); // 'ECDSA-P256-SHA256'返されるオブジェクトは{ publicKey: string, algorithm: string }です。
App.native.crypto.sign(data)
デバイスの秘密キーを使用してdata(base64文字列)に署名します。{ signature: string, algorithm: string }を返します。ここでsignatureはbase64エンコードされたder asn.1署名です。キーペアが利用できない場合(正常にgenerate()を実行した後は発生しません)やdataが有効なbase64文字列でない場合はエラーでリジェクトされます。
1const payload = btoa(JSON.stringify({ op: 'pair', device: deviceName }));2const { signature } = await App.native.crypto.sign(payload);同じペイロードと同じpublicKeyはどのプラットフォームでも検証可能です。
App.native.crypto.verify(data, signature, publicKey)
signatureがpublicKeyにおけるdataの有効な署名であることを検証します。3つの引数はすべてbase64文字列です。成功時はtrue、失敗時(不正な形式のbase64、不正な形式の署名、改ざんされた署名など)はfalseを返します。
1const ok = await App.native.crypto.verify(payload, signature, senderPublicKey);2if (!ok) throw new Error('signature mismatch');App.native.crypto.digest(data, algo?)
要求されたアルゴリズムでdata(base64文字列)をハッシュ化します。algoのデフォルトは'SHA-256'です。'SHA-1'および基礎となるプラットフォームがサポートする任意のアルゴリズムも受け付けます(webとiosは'SHA-256'と'SHA-1'を受け付け、androidはハイフン付きまたはハイフンなしの同等形式を受け付けます)。ハッシュをbase64文字列として返します。
1const hash = await App.native.crypto.digest(btoa('abc'), 'SHA-256');2// hash === 'ungWv48Bz+pBQUDeXa4iI7ADYaOWG3Yr0FSxiyEyvg7gq9B3/L1lqg=='App.native.crypto.export()
署名を行わずにデバイスの現在のキーペアの{ publicKey, algorithm }を返します。公開アイデンティティのみをピアと共有する必要がある場合に便利です。generate()と同じように動作しますがより短い呼び出しで済みます。
1const { publicKey } = await App.native.crypto.export();App.native.crypto.import(publicKey)
外部の公開キーをローカルキーストアにインポートし以降のverify呼び出しで再インポートなしで使用できるようにします。成功時はtrueを返します。webではこれはキーの形状を検証してtrueに解決するだけのno opです。
1await App.native.crypto.import(peerPublicKey);2const ok = await App.native.crypto.verify(data, signature, peerPublicKey);cryptoプラグインに関する注意点
- 公開キーはpemやx509 blobではなく65バイトの生のバイト列(0x04プレフィックスとxおよびy座標)です。これはiosの
SecKeyCreateWithDataおよびandroidのECPublicKeySpec再構築パスで使用される形式と一致するためトランスコードなしでクロスプラットフォーム検証が機能します。 - 署名はderエンコードされたasn.1(
SHA256withECDSA)であり各プラットフォームがネイティブに生成する形式です。エントロピーの高いビットに応じてバイト長は約64から72の間で変動します。 - webではキーペアはindexeddbの
dstrn_crypto / keys / dstrn_crypto_main_keyに保存されます。サイトデータを消去するとキーペアが削除され次回のgenerate()でデバイスは新しいキーペアを作成します。デバイス間でキーペアを移行する方法はありません。
audioプラグイン
メディアセッションメタデータを備えた単一urlオーディオ再生によりオペレーティングシステムはロック画面や通知領域にタイトル、アーティスト、アルバム、アートワーク、再生コントロールを表示できます。ページごとに1つの共有プレイヤーが存在するためload()を呼び出すとソースが切り替わります。キューや複数urlモードはありません(一度に1トラックのみ)。
iosではプラグインはAVPlayerを使用しバックグラウンド再生とネイティブの再生中コントロールをサポートします。androidでは同様の効果を得るためにMediaPlayerとMediaSessionCompatを使用します。webおよびdesktopではプラグインはHTMLAudioElementとMediaSessionにフォールバックします。これはアプリ内再生とロック画面コントロールには十分ですがアプリが中断されたときに再生を継続することはできません。
App.native.audio.load(url)
現在のソースとしてurlを読み込みます。サポートされるurlは1つのみです。再度load()を呼び出すと前回のトラックが置き換えられます。成功時はtrueを返しurlが無効な場合やaudio要素が拒否された場合はfalseを返します。
1await App.native.audio.load(episodeUrl);2await App.native.audio.play();App.native.audio.play()
現在ロードされているトラックの再生を開始します。trueを返します。ブラウザが自動再生をブロックした場合(ユーザー操作がまだない場合)基礎となるpromiseのリジェクトは無視されtrueが返されます。play()を呼び出す前にユーザーイベントを監視してユーザー操作を確認することをお勧めします。
1button.addEventListener('click', async () => {2 await App.native.audio.play();3});App.native.audio.pause()
再生位置をリセットせずに再生を一時停止します。trueを返します。
App.native.audio.resume()
play()のエイリアスです。システムメディアコントロールからは再生/一時停止として公開されているが独自のコードでは一時停止/再開としてモデル化されている場合に便利です。
App.native.audio.seek(seconds)
再生ヘッドをトラックの先頭からseconds秒の位置に移動します。数値を受け入れフレーム精度のシークのために小数の値もサポートされます。トラックがロードされている場合はtrueを返し要素がまだ存在しない場合(先にloadを呼び出す必要があります)はfalseを返します。
1await App.native.audio.seek(120); // jump to two minutes inApp.native.audio.stop()
再生を一時停止しトラックの先頭に巻き戻します。trueを返します。
App.native.audio.setRate(rate, preservePitch?)
再生速度を設定します。rateは数値です(等倍の半分なら0.5、2倍速なら2など)。preservePitchのデフォルトはfalseです。falseの場合ピッチは速度に連動しtrueの場合ピッチは一定に保たれ速度のみが変化します。trueを返します。
1await App.native.audio.setRate(1.5, true); // 1.5x speed, normal pitchApp.native.audio.setMetadata(title, artist, album, duration, artwork)
システムメディアセッションにメタデータを公開しロック画面や通知領域に再生内容を表示できるようにします。title以外のすべての引数はオプションです。durationは秒単位で数値である必要があります。artworkはurl文字列です。成功時はtrueを返しプラットフォームがメディアセッションをサポートしていない場合はfalseを返します。
1await App.native.audio.setMetadata(2 'episode 42: pairing flows',3 'dframework weekly',4 'season 2',5 1820,6 'https://cdn.example.com/art/episode-42.jpg'7);audioプラグインに関する注意点
- 呼び出し間で同じaudio要素が再利用されます。呼び出しごとのプレイヤーオブジェクトはありません。
- プラグインは個別のurlにまたがる範囲リクエストシークを実装していません。1つのurlにつき1つのソースです。
setRateは任意の正の数値を受け付けますが約[0.25, 4]の範囲外の値はすべてのプラットフォームで尊重されるとは限りません。
notificationsプラグイン
通知ごとに安定したidを持つローカル通知であり表示後に更新またはキャンセルできます。webおよびdesktopではプラグインはwindow.Notificationを使用しiosではUNUserNotificationCenterを使用しandroidではandroid 13以降でランタイム権限リクエストを伴うNotificationManagerCompatを使用します。
App.native.notifications.requestPermission()
現在の権限状態を文字列('granted'、'denied'、または'prompt')として返します。状態が'prompt'の場合呼び出し時にユーザーへのプロンプトも表示されます(それ自体が'granted'または'denied'に解決される可能性があります)。通知apiのないプラットフォームでは'denied'を返します。
1const status = await App.native.notifications.requestPermission();2if (status !== 'granted') {3 return notify('enable notifications in settings', 'warning');4}App.native.notifications.show(title, body?, id?)
表示タイトルとしてtitle、表示本文としてbodyを持つローカル通知を表示します。idはオプションです。指定した場合は後でcancel(id)を呼び出して通知を閉じることができます。指定しない場合プラグインは'dstrn-0'や'dstrn-1'のようなidを生成しますが後からその特定の通知を確実にキャンセルすることはできません。
実際に使用された通知id(指定したidまたは生成されたid)を返します。apiが利用できない場合や権限が拒否されている場合はエラーをスローします。
1const id = await App.native.notifications.show(2 'pairing complete',3 'tap to open the dashboard',4 'pairing-success-1'5);App.native.notifications.cancel(id)
指定されたidの通知を閉じます。通知が見つかり閉じられた場合はtrueを返しそのidの通知が認識されない場合はfalseを返します。
1await App.native.notifications.cancel('pairing-success-1');notificationsプラグインに関する注意点
show()を成功させるには事前に権限が付与されている必要があります。付与されていない場合はpermission deniedをスローします。- 明示的な
idを付与していない通知は設計上キャンセルの追跡対象外となります。後でキャンセルする必要がある場合は常にidを渡してください。 - プラグインは通知を将来の時刻にスケジュールしません。それが必要な場合はプッシュ通知またはジョブキューを使用してサーバーからスケジュールしてください。
独自プラグインの作成
すべてのプラグインは言語ごとに最大4つのファイルを含むフォルダです。フレームワークはプロジェクト内のnative/plugins/<name>/配下の任意のフォルダを自動検出します。マニフェスト、スキーマ、レジストリ、ビルド配線の編集は不要です。ビルド時にフォルダが存在していればプラグインは出荷されます。
4ファイル構成の規約
barcodeという名前のプラグインはnative/plugins/barcode/に配置されます:
1native/plugins/barcode/2├── index.js # required. javascript reference impl. source of truth for method names.3├── Plugin.swift # optional. ios native impl. must export the same method names.4├── Plugin.kt # optional. android native impl. must export the same method names.5└── Plugin.rs # optional. desktop native impl. must export the same method names.この構成には3つのルールがあります:
`index.js`はすべてのプラグインで必須です。リファレンス実装、メソッド名の信頼できる情報源、およびネイティブ実装が存在しないか失敗した場合の自動フォールバックとして機能します。
Plugin.swift、Plugin.kt、Plugin.rsはいずれもオプションです。チームがサポートできるネイティブ言語のものを出荷してください。ファイルが存在しない場合プラグインはそのプラットフォームでjavascript実装にフォールバックします。- メソッド名は言語間で文字列の一致によって照合されます。
index.jsがbarcode.scanをエクスポートしている場合Plugin.swiftにはcase "scan":ブランチが必要でありPlugin.ktは"scan"にマッチしPlugin.rsは"scan"にディスパッチする必要があります。ブリッジ経由で送信される値がjsonエンコード可能である限りパラメータの形状と戻り値の形状は各言語独自の問題です。
javascriptリファレンス実装
index.jsはキーがメソッド名で値が関数であるオブジェクトを返す通常のモジュールです。関数本体はブラウザまたはwebview内で実行され通常のブラウザグローバル(window、localStorage、navigator、fetch、crypto.subtle、MediaSession、Notification、Audioなど)のすべてにアクセスできます。
メソッドはホスト環境の全機能を使って実行されます。通常のフロントエンドjavascriptと同様に扱ってください。ネイティブ側がプラットフォームごとメソッドごとにオーバーライドできるようにプラグインとしてパッケージ化されているだけです。
1// native/plugins/barcode/index.js2return {3 scan() {4 return { ok: false, error: 'not implemented on this platform' };5 },6};
プラグインのスキャフォールディング
cliは動作するjavascript実装と入力用のスタブネイティブファイルを含む4つのファイルを生成します:
1dstrn make:plugin barcode
これによりindex.js、Plugin.swift、Plugin.kt、Plugin.rsを含むnative/plugins/barcode/が作成されます。必要なメソッドを編集すると次回のdstrn simulateまたはdstrn buildで自動的に検出されます。
信頼できる情報源としてのjavascriptの記述
javascript実装は存在しないネイティブファイルに対するフォールバックとなるためどこでも動作するように設計しネイティブ実装はその上のパフォーマンスや機能のアップグレードとして扱います。機能がweb上でどうしても動作しない場合(カメラキャプチャなど)はjavascript実装から明確なエラーを返します:
1return {2 async scan() {3 if (typeof navigator === 'undefined' || !navigator.mediaDevices) {4 throw new Error('barcode: camera unavailable in this environment');5 }6 const stream = await navigator.mediaDevices.getUserMedia({ video: { facingMode: 'environment' } });7 stream.getTracks().forEach((t) => t.stop());8 return { value: 'scanned-value', format: 'qr_code' };9 },10};その後プラグインはwebの動作を損なうことなくiosおよびandroidでネイティブ実装へとアップグレードされます。
ios実装
フレームワークはビルド中にiosランタイムプロジェクト内にプラグインごとのPlugin.swiftを呼び出すPlugins.swiftファイルを生成します。Plugin.swift内では以下の形式に従います:
1import Foundation2 3class BarcodePlugin {4 weak var bridge: Bridge?5 6 init(bridge: Bridge? = nil) {7 self.bridge = bridge8 }9 10 func handle(method: String, params: [String: Any], callId: String) {11 switch method {12 case "scan":13 scan(callId: callId)14 default:15 bridge?.reject(callId: callId, error: "barcode: unknown method \(method)")16 }17 }18 19 private func scan(callId: String) {20 // AVCaptureSession setup, delegate callbacks, etc.21 // call bridge?.resolve(callId: callId, result: [...]) on success22 // or bridge?.reject(callId: callId, error: "failed") on failure23 }24}ブリッジは起動時にbarcode.scanをネイティブメソッドとして登録します。呼び出しはresolveに渡したものを返します。
android実装
フレームワークは各メソッドをPlugin.ktにルーティングするPlugins.ktディスパッチャーを生成します。Plugin.kt内:
1package com.dframework.native2 3import android.content.Context4import org.json.JSONObject5 6class BarcodePlugin(private val context: Context, private val bridge: Bridge) {7 fun handle(method: String, args: JSONObject, callId: String) {8 when (method) {9 "scan" -> scan(callId)10 else -> bridge.reject(callId, "barcode: unknown method $method")11 }12 }13 14 private fun scan(callId: String) {15 // CameraX or ML Kit setup16 // call bridge.resolve(callId, JSONObject().put("value", "payload")) on success17 // or bridge.reject(callId, "data") on failure18 }19}
desktop実装
フレームワークはplugins.rsディスパッチャーを生成します。Plugin.rs内:
1use serde_json::{json, Value};2 3pub fn handle(method: &str, params: &Value) -> (bool, Value, Value) {4 match method {5 "scan" => (true, json!({ "ok": false, "error": "no camera in desktop build" }), json!(null)),6 _ => (false, json!(null), json!(format!("barcode: unknown method {}", method))),7 }8}desktop webviewはほとんどのブラウザapi(fetch、crypto.subtle、localStorageなど)を使用できるためdesktopプラグインは通常ブラウザにはない通知やファイルシステムアクセスなどtauri固有のapiが必要な場合にのみ作成します。desktopファイルを出荷しない場合ブリッジは自動的にjavascript実装にフォールバックします。
フォールバックルール
どの実装を実行するかの決定はプラットフォームごとメソッドごとに行われます:
Plugin.swiftがiosでcase "scan":ブランチを宣言している場合ブリッジはbarcode.scanをネイティブとして登録しjavascriptからのすべての呼び出しはブリッジ経由で転送されます。- そのブランチ(またはファイル全体)を削除した場合ブリッジはios上で
barcode.scanをネイティブとして登録しないためwebview内でjavascript実装が実行されます。これが実際の「フォールバック」の意味です(ネイティブファイルが見つからないために失敗するプラットフォームコードパスはありません)。 - ブリッジがメソッドをネイティブとして登録しているにもかかわらずネイティブ呼び出しがリジェクトされた場合ブリッジはそのリジェクトをpromiseに伝播させます。サイレントにjavascriptにフォールバックすることはありません。ネイティブ実装は成功するか明確なメッセージとともにリジェクトするように設計してください。
- desktop audio、desktop notifications、desktop crypto、desktop deviceは現在すべてjavascriptにフォールバックします(コアフレームワークにはこれらに対応する
Plugin.rsはありません)。desktopでプラットフォーム固有の動作が必要な場合にのみ記述してください。
エンドツーエンドの例(バーコードスキャナー)
バーコードをスキャンしてその値を返す完全な最小プラグインです。動作するwebフォールバックとios / androidネイティブスタブを含みます。
1// native/plugins/barcode/index.js2return {3 async scan() {4 if (typeof navigator === 'undefined' || !navigator.mediaDevices) {5 throw new Error('barcode: camera unavailable');6 }7 const stream = await navigator.mediaDevices.getUserMedia({ video: { facingMode: 'environment' } });8 try {9 return { value: 'placeholder-decoded-value', format: 'qr_code' };10 } finally {11 stream.getTracks().forEach((t) => t.stop());12 }13 },14};1// native/plugins/barcode/Plugin.swift2import AVFoundation3 4class BarcodePlugin {5 weak var bridge: Bridge?6 7 init(bridge: Bridge? = nil) {8 self.bridge = bridge9 }10 11 func handle(method: String, params: [String: Any], callId: String) {12 switch method {13 case "scan": scan(callId: callId)14 default: bridge?.reject(callId: callId, error: "barcode: unknown method \(method)")15 }16 }17 18 private func scan(callId: String) {19 // AVCaptureMetadataOutput with .qr type, callback writes20 // bridge?.resolve(callId: callId, result: ["value": "data", "format": "qr_code"])21 }22}1// native/plugins/barcode/Plugin.kt2package com.dframework.native3 4import android.content.Context5import org.json.JSONObject6 7class BarcodePlugin(private val context: Context, private val bridge: Bridge) {8 fun handle(method: String, args: JSONObject, callId: String) {9 when (method) {10 "scan" -> scan(callId)11 else -> bridge.reject(callId, "barcode: unknown method $method")12 }13 }14 15 private fun scan(callId: String) {16 // CameraX + ML Kit, callback writes17 // bridge.resolve(callId, JSONObject().put("value", "payload").put("format", "qr_code"))18 }19}1// native/plugins/barcode/Plugin.rs2use serde_json::{json, Value};3 4pub fn handle(method: &str, params: &Value) -> (bool, Value, Value) {5 match method {6 "scan" => (false, json!(null), json!("barcode: camera not available on desktop")),7 _ => (false, json!(null), json!(format!("barcode: unknown method {}", method))),8 }9}アプリケーションからこのプラグインを呼び出します:
1try {2 const result = await App.native.barcode.scan();3 console.log(result.value, result.format);4} catch (e) {5 notify('could not scan: ' + e.message, 'error');6}iosおよびandroidではネイティブ実装が実行されます。webではjavascript実装が実行されます。desktopではrustディスパッチが明確なエラーでリジェクトします。1つの呼び出し元に対して4つの実装が存在します。
トラブルシューティング
ブリッジが呼び出しを解決しない。 テスト対象のプラットフォームでそのメソッドがネイティブとして登録されているか確認してください。フレームワークには各プラットフォームで登録されているメソッドを報告するdstrn native:statusおよびdstrn native:doctorコマンドが用意されています。
メソッドがプラットフォーム間で異なる値を返す。 返すjsonの形状がすべてのプラットフォームで同じであることを確認してください。ブリッジはiosのJSONSerialization、androidのJSONObject、desktopのserde_jsonを介して値を渡すためワイヤー形式は同じです。相違点は元の言語側にあります。デバッガーで解決された値を比較してください。
プラグインフォルダが認識されない。 フォルダ名が<name>/と一致しindex.jsが存在することを確認してください。dstrn native:doctorは検出されたプラグインを報告しindex.jsがないものにフラグを立てます。
ネイティブ呼び出しがタイムアウトする。 デフォルトのタイムアウトは30秒でconfig/native.jsのnative.timeoutで設定可能です。実装にそれ以上の時間が必要な場合(大容量ファイルのアップロード、ネットワーク処理など)はタイムアウトを延ばすか処理をより小さな呼び出しに分割してください。

