useConnectフックは、DidConnect UIモーダルをプログラムで開閉・管理するための強力な方法を提供します。宣言的なButtonコンポーネントが提供するものよりも接続フローをより詳細に制御する必要がある場合、例えばカスタムUI要素、メニュー項目、またはアプリケーションイベントに応じてモーダルをトリガーする場合に理想的なソリューションです。
このフックはButtonコンポーネントの背後にあるエンジンであり、同じコア機能への直接アクセスを提供します。
仕組み
useConnectフックは、主に2つの要素を返します：
`connectHolder`
コンポーネントツリーにレンダリングする必要があるReact要素です。この要素は、
DidConnectモーダルがアクティブ化されたときにそれをレンダリングする責任があります。open関数が呼び出されるまで非表示のままです。`connectApi`
モーダルのライフサイクルを制御するために使用する関数（
open、close、openPopup、loginOAuth）を含むオブジェクトです。
セットアップ
フックを使用するには、それをインポートし、コンポーネント内で呼び出します。次に、アプリケーションのどこか、できればトップレベルのコンポーネントでconnectHolderをレンダリングして、モーダルが他のすべてのコンテンツの上にオーバーレイできるようにします。
Basic Setup
import React from 'react';
import { useConnect } from '@arcblock/did-connect-react';
function MyComponent() {
// 1. フックを初期化する
const { connectHolder, connectApi } = useConnect();
const handleLogin = () => {
// 2. API を使用してモーダルを開く
connectApi.open({
action: 'login',
onSuccess: (result) => {
console.log('ログイン成功！', result);
},
onClose: () => {
console.log('モーダルがユーザーによって閉じられました。');
}
});
};
return (
<div>
<button type="button" onClick={handleLogin}>
DIDでログイン
</button>
{/* 3. ホルダーコンポーネントをレンダリングする */}
{connectHolder}
</div>
);
}
export default MyComponent;APIリファレンス
connectApiオブジェクトは、接続プロセスを制御するための以下のメソッドを提供します。
connectApi.open(options)
これはDidConnectモーダルをトリガーして表示するための主要な関数です。接続セッションの動作、外観、およびコールバックを設定するための単一のoptionsオブジェクトを受け入れます。
パラメータ (options)
- action
string(required) — 接続リクエストの目的、例：login、claim、signなど。これはウォレット内のワークフローを決定します。 - onSuccess
(result: object) => void— ユーザーがウォレットでアクションを正常に完了したときに実行されるコールバック関数。resultオブジェクトにはウォレットからのレスポンスが含まれます。 - onClose
() => void— ユーザーがアクションを完了せずに手動でモーダルを閉じたときに実行されるコールバック関数。 - onError
(error: any) => void— タイムアウトやネットワークの問題など、プロセス中にエラーが発生した場合に実行されるコールバック関数。 - messages
ConnectMessages— モーダルに表示されるテキストをカスタマイズするためのオブジェクト。詳細はConnectMessages型を参照してください。- title
string— モーダルのタイトル。 - scan
string— QRコードに付随するテキスト。 - confirm
string— 確認ステップのテキスト。 - success
ReactNode— 成功画面のコンテンツ。
- title
- popup
boolean(default:true) — trueの場合、UIはモーダルダイアログとして表示されます。falseの場合、インラインでレンダリングされ、containerElの設定が必要です。 - containerEl
Element— popupがfalseに設定されている場合にDidConnectコンポーネントがレンダリングされるDOM要素。 - closeTimeout
number(default:2000) — 接続成功後、モーダルが自動的に閉じるまでの遅延時間（ミリ秒）。 - checkInterval
number(default:2000) — セッションステータスを確認するためにサーバーをポーリングする間隔（ミリ秒）。 - checkTimeout
number(default:300000) — 接続試行がタイムアウトするまでの合計時間（ミリ秒）。 - extraParams
object(default:{}) — セッション作成リクエストに含める追加のパラメータで、サーバー側で取得できます。
connectApi.close()
DidConnectモーダルを手動で閉じます。モーダルは成功時またはユーザーによるキャンセル時に自動的に閉じますが、他の理由でプログラムから閉じる必要がある場合はこの関数を呼び出すことができます。
// 例：成功コールバックで短い遅延の後にモーダルを閉じる
connectApi.open({
action: 'login',
onSuccess: () => {
showTemporarySuccessMessage();
setTimeout(() => {
connectApi.close();
}, 1500);
},
closeTimeout: 999999 // 自動クローズを防止
});connectApi.openPopup(params, options)
この関数は、現在のページ内のモーダルの代わりに、新しいブラウザのポップアップウィンドウでDID Connectフローを開く代替の接続方法を提供します。これは、特定のOAuthのようなフローや、モーダルを注入できないサイトとの統合に役立ちます。
パラメータ
- params
ConnectProps(required) — openメソッドのオプションに似ています。主な違いは、認証方法（例：「github」、「google」）を識別するためにparams.extraParams.providerが必須であることです。 - options
object— ポップアップウィンドウ自体の設定。- baseUrl
string— ポップアップURLを構築するためのベースURL。 - locale
string(default:en) — ポップアップコンテンツのロケール。 - popupOptions
object— ポップアップのサイズや機能をカスタマイズするためにwindow.open()に直接渡されるオプション。
- baseUrl
使用法
openPopup関数は、成功時に認証データで解決されるか、失敗またはキャンセル時に拒否されるPromiseを返します。
const handleGithubLogin = async () => {
try {
const result = await connectApi.openPopup({
action: 'login',
onSuccess: () => console.log('このコールバックもトリガーされます'),
extraParams: { provider: 'github' } // これは必須です
});
console.log('ポップアップ経由でのログイン成功：', result);
} catch (err) {
if (err.message === 'Popup closed') {
console.log('ユーザーがポップアップウィンドウを閉じました。');
} else {
console.error('エラーが発生しました：', err);
}
}
};connectApi.loginOAuth(options)
これはOAuthログインフローを直接開始するためのヘルパー関数です。ライブラリの他の部分で内部的に使用される低レベルのユーティリティです。
パラメータ (options)
- provider
string(required) — 使用するOAuthプロバイダー、例：「github」、「google」。 - action
string(required) — アクション、通常は「login」。 - extraParams
object— OAuthフローの追加パラメータ。 - onLogin
function(required) — ログイン成功時に実行されるコールバック関数。