# 連線 UI (DidConnect)

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

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

在使用 `DidConnect` 之前，請確保您已使用 [`SessionProvider`](./core-components-session-provider.md) 將您的應用程式包裹起來，以管理整體的 session 狀態。

## 基本用法

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

```jsx DID Connect 範例 icon=logos:react
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` 元件協調了整個使用者驗證流程，從顯示連線選項到處理最終的成功或錯誤狀態。

<!-- DIAGRAM_IMAGE_START:flowchart:4:3:1765962229 -->
![Connection UI (DidConnect)](assets/diagram/did-connect-diagram-0.zh-TW.jpg)
<!-- DIAGRAM_IMAGE_END -->

## 元件 Props

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

### 核心設定

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

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

### 行為控制

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

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

### UI 客製化

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

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

### 回呼

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

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

## 後續步驟

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