跳到主要內容

API 參考

本節為整個 @arcblock/did-connect-react 函式庫中使用的所有主要 TypeScript 類型提供了全面的參考。了解這些資料結構對於有效使用 SessionProvider 等元件和 useConnect 等掛鉤至關重要。

連線類型

這些類型主要用於設定 DID Connect 互動視窗並與之互動時使用。

ConnectProps

這是傳遞給 useConnect 掛鉤中的 open 函數或會話上下文中的 openDidConnect 函數的主要設定物件。它允許對連線流程的行為和外觀進行廣泛的自訂。

  • action string (required) — 連線的主要操作，例如 'login'。
  • containerEl Element — 連線互動視窗應附加到的 DOM 元素。
  • prefix string (default: /api/did) — DID Connect 服務的 API 端點前綴。
  • locale 'en' | 'zh' (default: en) — 用於 UI 的語言。
  • popup boolean (default: false) — 若為 true，連線 UI 將顯示在彈出視窗中，而不是互動視窗。
  • checkInterval number (default: 2000) — 檢查會話狀態的間隔（以毫秒為單位）。
  • checkTimeout number (default: 300000) — 整個會話檢查過程的逾時時間（以毫秒為單位）（5 分鐘）。
  • closeTimeout number (default: 2000) — 成功連線後關閉互動視窗前的延遲時間（以毫秒為單位）。
  • extraParams object (default: {}) — 隨連線請求發送的任何額外參數。
  • tokenKey string (default: _t_) — 用於儲存會話權杖的金鑰。
  • encKey string (default: _ek_) — 用於加密的金鑰。
  • baseUrl string (default: '') — API 請求的基礎 URL。
  • messages ConnectMessages — 用於自訂連線 UI 中顯示文字的物件。
  • autoConnect boolean (default: true) — 若為 true，則自動嘗試使用已儲存的會話進行連線。
  • forceConnected boolean | string (default: true) — 強制將連線視為已建立。
  • saveConnect boolean (default: true) — 若為 true，成功的連線會話將被儲存以供 autoConnect 使用。
  • useSocket boolean (default: true) — 若為 true，則使用 WebSockets 進行即時狀態更新。
  • allowWallet boolean (default: true) — 若為 true，允許透過 DID Wallet 連線。
  • passkeyBehavior 'none' | 'both' | 'only-existing' | 'only-new' (default: true) — 定義在驗證過程中如何處理通行密鑰（Passkeys）。
  • provider 'wallet' | 'auth0' | '' (default: wallet) — 指定驗證提供者。
  • qrcodeSize number (default: 160) — QR code 的大小（以像素為單位）。
  • showDownload boolean (default: true) — 若為 true，則顯示 DID Wallet 的下載連結。
  • webWalletUrl string (default: https://web.abtwallet.io) — 網頁版 DID Wallet 的 URL。
  • enabledConnectTypes Array<'web' | 'mobile' | 'auth0' | 'github' | 'apple' | 'google' | 'passkey'> (default: ["web", "mobile", "github", "apple", "google", "auth0", "passkey"]) — 在 UI 中啟用的連線方法陣列。
  • extraContent any — 在連線互動視窗內呈現的自訂內容。
  • loadingEle any — 要顯示的自訂載入元素。
  • disableSwitchApp boolean (default: false) — 若為 true，則禁用行動裝置上的自動應用程式切換。
  • hideCloseButton boolean (default: false) — 若為 true，則隱藏互動視窗中的關閉按鈕。
  • options object (default: {}) — 額外的設定選項。
    • showQuickConnect boolean (default: true) — 若為 true，則顯示已儲存會話的快速連線選項。
  • onRecreateSession Function — 當會話被重新建立時執行的回呼函數。
  • checkFn () => boolean — 用於檢查連線狀態的自訂函數。
  • onSuccess (result: object) => void — 成功連線後執行的回呼函數。
  • onError (error: any) => void — 發生錯誤時執行的回呼函數。
  • onClose Function — 連線互動視窗關閉時執行的回呼函數。

ConnectMessages

用於自訂 DID Connect UI 中顯示文字的物件。

  • title string (required) — 連線互動視窗的主標題。
  • scan string (required) — 掃描 QR code 的說明文字。
  • success ReactNode (required) — 成功連線後顯示的訊息或元件。
  • confirm string — 提示使用者在錢包中確認操作的文字。
  • error string — 要顯示的自訂錯誤訊息。

OpenDidConnect

此函數類型定義了開啟具有進階需求的 DID Connect 流程的簽章，通常用於漸進式授權。

  • params ConnectProps (required) — 標準連線屬性。
  • options object — 用於控制連線模式和指定需求的額外選項。
    • openMode 'redirect' | 'window' | 'popup' (default: popup) — 決定 DID Connect 視窗的開啟方式。
    • requirements object — 指定會話的需求。
      • login boolean (default: true) — 若為 true，要求使用者登入。
      • bindWallet boolean (default: true) — 若為 true，要求使用者已綁定 DID Wallet 帳戶。
      • bindDidSpaces false | 'read' | 'full' (default: false) — 指定是否需要綁定 DID Spaces，以及需要何種等級的存取權限。
    • baseUrl string — API 請求的基礎 URL。
    • locale BaseLocale — UI 的語言（'en' 或 'zh'）。

會話與使用者類型

這些類型定義了由 SessionProvider 管理的使用者和會話資料的結構。

SessionProps

主會話物件，可透過 useSession 掛鉤存取。它包含使用者的狀態、會話資訊以及管理會話的方法。

  • action string — 目前正在執行的操作（例如，'login'）。
  • error string — 在會話管理期間發生的任何錯誤訊息。
  • initialized boolean — 如果會話已初始化，則為 True。
  • loading boolean — 如果會話目前處於載入狀態，則為 True。
  • open boolean — 如果 DID Connect 互動視窗目前是開啟的，則為 True。
  • walletOS WalletOS — 已連線錢包的作業系統（'web'、'android'、'ios'）。
  • user User — 已驗證的使用者物件。如果沒有使用者登入，則為 Undefined。
  • locale UserLocale — 使用者的目前地區設定。
  • provider WalletProvider — 目前會話使用的提供者。
  • baseUrl string — 用於 API 呼叫的基礎 URL。
  • federatedMaster object — 關於統一登入站點群中主站點的資訊。
  • login LoginSessionFn — 用於啟動登入過程的函數。
  • logout LogoutSessionFn — 用於登出使用者的函數。
  • switch Function — 用於在不同使用者帳戶之間切換的函數。
  • switchDid CommonSessionFn — 用於切換使用者活動 DID 的函數。
  • autoSwitchDid Function — 用於自動切換 DID 的函數。
  • switchProfile CommonSessionFn — 用於切換使用者設定檔的函數。
  • switchPassport CommonSessionFn — 用於在不同通行證之間切換的函數。
  • bindWallet CommonSessionFn — 用於啟動錢包綁定過程的函數。
  • refresh Function — 用於手動刷新會話資料的函數。
  • updateConnectedInfo (data: object) => void — 用於更新連線資訊的函數。
  • openDidConnect OpenDidConnect — 用於開啟具有進階需求的 DID Connect 互動視窗的函數。
  • useOAuth Function — 用於 OAuth 整合的掛鉤。
  • OAuthProvider Function — 用於 OAuth 上下文的提供者元件。
  • OAuthConsumer Function — 用於 OAuth 上下文的消費者元件。
  • OAuthContext object — 用於 OAuth 的 React 上下文物件。
  • usePasskey Function — 用於 Passkey 整合的掛鉤。
  • PasskeyProvider Function — 用於 Passkey 上下文的提供者元件。
  • PasskeyConsumer Function — 用於 Passkey 上下文的消費者元件。
  • PasskeyContext object — 用於 Passkey 的 React 上下文物件。
  • useDid (options: { session: Session }) => void — 一個用於處理 DID 資訊的實用掛鉤。
  • WrapDid Function — 一個與 DID 功能相關的包裝元件。
  • getUserSessions () => Promise<UserSession[]> — 用於獲取目前使用者所有活動會話的函數。

User

代表已驗證使用者的詳細設定檔。

  • did string (required) — 使用者的去中心化識別碼（DID）。
  • pk string (required) — 使用者的公鑰。
  • avatar string (required) — 使用者頭像的 URL。
  • fullName string (required) — 使用者的全名。
  • email string (required) — 使用者的電子郵件地址。
  • role UserRole (required) — 使用者在應用程式中的角色（例如，'guest'、'member'、'admin'）。
  • locale UserLocale (required) — 使用者的偏好語言。
  • connectedAccounts ConnectAccount[] (required) — 與使用者 DID 連線的帳戶列表。
  • passports Passport[] (required) — 與使用者關聯的通行證列表。
  • permissions any[] (required) — 授予使用者的權限列表。
  • didSpace object — 關於使用者 DID Space 的資訊。
  • approved boolean (required) — 表示使用者是否已被核准。
  • remark string — 關於使用者的可選備註或註記。
  • createdAt string (required) — 使用者帳戶建立時的時間戳。
  • updatedAt string (required) — 使用者帳戶最後更新的時間戳。
  • firstLoginAt string — 使用者首次登入的時間戳。
  • lastLoginAt string — 使用者最後一次登入的時間戳。
  • lastLoginIp string — 使用者最後一次登入的 IP 位址。

UserSession

代表使用者的單個活動會話，通常從 getUserSessions 中檢索。

  • id string (required) — 會話的唯一識別碼。
  • appName string (required) — 此會話的應用程式名稱。
  • appPid string (required) — 應用程式的通行證 ID。
  • updatedAt string (required) — 上次會話更新的時間戳。
  • userDid string (required) — 此會話使用者的 DID。
  • visitorId string (required) — 與會話關聯的訪客 ID。
  • extra object (required) — 與會話關聯的任何額外資料。
  • user SessionUser (required) — 會話的簡化使用者物件。
  • passportId string — 此會話使用的通行證 ID。

核心資料類型

這些是在各種其他介面中使用的基本字串聯合類型。

TypeDescriptionPossible Values
WalletProvider識別驗證方法或提供者。wallet, auth0, apple, github, google, passkey
WalletOS代表 DID Wallet 的作業系統。web, android, ios, '' (空字串)
UserRole定義使用者在應用程式中的角色。guest, member, admin, owner 或任何 string
BaseLocale支援的基礎語言集。en, zh
UserLocale使用者的地區設定，可以是基礎地區設定或更具體的設定。en, zh 或任何 string（例如 'en-US'）