連線 UI (DidConnect)

DidConnect 元件是一個預先建置的、全面的 UI 解決方案，用於處理各種去中心化身分（DID）連線流程。它為登入、驗證和個人資料請求等操作提供了一個使用者友善的介面，並原生支援多種連線方式。

它是 @arcblock/did-connect-react 函式庫的視覺核心，將 session 管理和即時狀態更新的複雜性抽象化。該元件會為 DID Wallet 使用者顯示一個 QR code，並提供其他登入選項，例如社群登入（OAuth）和無密碼驗證（Passkeys）。

在使用 DidConnect 之前，請確保您已使用 SessionProvider 將您的應用程式包裹起來，以管理整體的 session 狀態。

基本用法

要使用 DidConnect，您需要匯入它並提供一些必要的 props。該元件通常由一個決定其可見性的狀態變數來控制。

DID Connect 範例

import React, { useState } from 'react';
import axios from 'axios';
import DidConnect from '@arcblock/did-connect-react/lib/Connect';

function App() {
  const [isConnectOpen, setConnectOpen] = useState(false);

  const handleClose = () => setConnectOpen(false);
  const handleSuccess = () => {
    // 處理成功登入，例如，重新導向使用者
    window.location.href = '/profile';
  };

  return (
    <div>
      <button onClick={() => setConnectOpen(true)}>使用 DID 登入</button>
      {isConnectOpen && (
        <DidConnect
          action="login"
          checkFn={axios.get}
          onClose={handleClose}
          onSuccess={handleSuccess}
          messages={{
            title: '掃描以登入',
            scan: '使用您的 DID Wallet 掃描 QR code',
            confirm: '在您的 DID Wallet 上確認登入',
            success: '您已成功登入！',
          }}
        />
      )}
    </div>
  );
}

export default App;

在此範例中，點擊「使用 DID 登入」按鈕會將 isConnectOpen 狀態設定為 true，這會將 DidConnect 元件渲染為一個強制回應對話框。checkFn prop 至關重要，因為它是元件用來從您的後端輪詢 session 狀態的函式。

運作方式

DidConnect 元件協調了整個使用者驗證流程，從顯示連線選項到處理最終的成功或錯誤狀態。

Connection UI (DidConnect)

元件 Props

DidConnect 元件可透過其 props 進行高度設定。以下是可用選項的詳細清單。

核心設定

這些 props 對於設定元件的基本功能至關重要。

action string (required) — 定義連線的目的，例如 login、claim、sign 等。此字串會傳遞到您的後端以確定所需的操作。
checkFn function (required) — 用於輪詢後端以獲取 session 狀態更新的函式。它應該是一個發出 API 請求的函式，例如 axios.get。
baseUrl string (default: '') — API 端點的基礎 URL。如果您的 API 在不同的網域上，請在此處指定。
prefix string (default: /api/did) — 您後端 DID Connect API 端點的 URL 前綴。

行為控制

這些 props 控制連線過程的行為方式。

enabledConnectTypes string[] (default: ["web", "mobile", ...]) — 一個字串陣列，指定要顯示哪些連線方式。可能的值包括 web、mobile、github、google、apple、passkey 等。
passkeyBehavior 'none' | 'both' | 'only-existing' | 'only-new' (default: 'none') — 控制 Passkey 驗證的行為。none 會停用它，both 允許建立新的 passkey 和使用現有的，only-existing 限制只能使用現有的 passkey，而 only-new 強制建立新的 passkey。
allowWallet boolean (default: true) — 如果為 false，QR code 和行動錢包連線選項將被隱藏。
autoConnect boolean (default: true) — 如果為 true，元件將自動嘗試使用來自同一裝置先前建立的連線。
forceConnected boolean | string (default: true) — 如果為 true，使用者必須使用他們已經登入的同一個 DID 進行連線。如果提供了一個 DID 字串，使用者必須使用該特定的 DID 進行連線。
saveConnect boolean (default: true) — 如果為 true，成功的連線資訊會儲存在本機，以供未來的 autoConnect 嘗試使用。
useSocket boolean (default: true) — 如果為 true，則嘗試使用 WebSocket 進行即時狀態更新，如果無法建立連線，則退回使用輪詢。

UI 客製化

客製化 DidConnect 元件的外觀和文字。

mode 'dialog' | 'drawer' | 'page' (default: 'dialog') — 決定元件的顯示方式。dialog 將其顯示為置中對話框，drawer 顯示為底部彈出視窗（在行動裝置上），而 page 將其直接嵌入文件流中。
messages object — 一個用於客製化 UI 中顯示文字的物件。
- title string — 頂部的主標題。
- scan string — 標題下方的說明文字。
- confirm string — QR code 掃描後顯示的文字。
- success string | ReactNode — 成功連線時顯示的訊息。
- error string — 發生錯誤時顯示的訊息。
hideCloseButton boolean (default: false) — 如果為 true，右上角的關閉按鈕（X）將被隱藏。
extraContent ReactNode (default: null) — 允許您將自訂的 React 元件或元素注入 UI 中，通常會出現在主標題/描述下方。
customItems ReactNode[] (default: []) — 一個自訂 React 節點的陣列，將被新增到連線方式清單中。
disableSwitchApp boolean (default: false) — 如果您正在使用統一登入站點群，此 prop 可防止使用者在登入過程中在群組中的不同應用程式之間切換。
webWalletUrl string — 用於「使用網頁錢包連線」選項的網頁版 DID Wallet 的 URL。預設為官方 ArcBlock 網頁錢包。

回呼

在連線生命週期的不同階段呼叫的函式。

onClose function (required) — 當使用者關閉 DidConnect 對話框時（例如，點擊關閉按鈕或在對話框外部點擊）執行的回呼函式。
onSuccess function (required) — 成功連線後執行的回呼函式。Session 資料會作為參數傳遞。
onError function — 在過程中發生錯誤時執行的回呼函式。錯誤物件或訊息會作為參數傳遞。
onRecreateSession function — 當 session 需要重置時（例如，逾時後或使用者手動取消並重試時）調用的回呼函式。

後續步驟

在對 DidConnect 元件有了扎實的理解後，您現在可以建構穩健的驗證體驗。若想對連線 UI 進行更多程式化控制，請探索 useConnect hook，它允許您從應用程式的任何地方開啟和關閉 DidConnect 對話框。