# 總覽

`@arcblock/did-connect-react` 程式庫提供了一套全面的 React 元件和掛鉤 (hooks)，旨在將去中心化身分 (DID) 功能無縫整合到您的 Web 應用程式中。它使用 ArcBlock 的 DID Wallet 簡化了使用者驗證和會話管理的流程，為傳統登入系統提供了一個安全且使用者友善的替代方案。

無論您需要一個完整的開箱即用解決方案，還是對驗證流程進行精細控制，該程式庫的設計都兼具靈活性和易用性。

### 主要功能

<x-cards data-columns="2">
  <x-card data-title="完整的連線 UI" data-icon="lucide:qr-code-icon">
    包含 `DidConnect` 元件，這是一個預先建置、可自訂的對話方塊，用於處理整個 QR Code 掃描和連線過程。
  </x-card>
  <x-card data-title="無縫的會話管理" data-icon="lucide:key-round">
    利用 `SessionProvider` 和 `useSession` 掛鉤，輕鬆管理整個應用程式中的使用者登入狀態、會話和個人資料。
  </x-card>
  <x-card data-title="靈活的程式化控制" data-icon="lucide:webhook">
    使用像 `useConnect` 這樣的掛鉤，以程式化方式開啟、關閉和管理連線對話方塊，讓您完全掌控使用者體驗。
  </x-card>
  <x-card data-title="豐富的 UI 工具組" data-icon="lucide:gem">
    一系列輔助 UI 元件，如 `Avatar`、`Address` 和 `Button`，用於一致地顯示使用者身分資訊。
  </x-card>
</x-cards>

### 核心架構

該程式庫圍繞一個核心的 `SessionProvider` 運作，它負責管理使用者的會話狀態。像 `Button` 這樣的 UI 元件可以觸發 `DidConnect` 對話方塊，該對話方塊處理與使用者 DID Wallet 之間基於 QR Code 的安全互動。連線完成後，會話將被更新，您的應用程式 UI 也會做出相應的反應。

需要注意的是，`@arcblock/did-connect-react` 是一個用戶端程式庫，需要一個對應的後端服務來處理驗證邏輯。該服務應使用適用於 Node.js 的 [`@arcblock/did-connect-js`](https://www.arcblock.io/docs/did-connect-sdk) 程式庫來建構。

<!-- DIAGRAM_IMAGE_START:architecture:16:9:1765962229 -->
![Overview](assets/diagram/overview-01.zh-TW.jpg)
<!-- DIAGRAM_IMAGE_END -->

### 安裝

若要開始使用，請使用 `yarn` 或 `npm` 將該程式庫新增至您的專案中。

```shell 安裝 icon=lucide:download
# 使用 yarn
yarn add @arcblock/did-connect-react

# 使用 npm
npm install @arcblock/did-connect-react
```

### 運作方式：快速概覽

以下是一個如何設定登入流程的最小範例。應用程式被包裹在一個 `SessionProvider` 中，並使用一個 `Button` 來切換 `DidConnect` 對話方塊的顯示。

```jsx App.js icon=logos:react
import React from 'react';
import axios from 'axios';
import { SessionProvider, SessionConsumer } from '@arcblock/did-connect-react/lib/Session';
import DidConnect from '@arcblock/did-connect-react/lib/Connect';
import Button from '@arcblock/did-connect-react/lib/Button';

const webWalletUrl = 'https://web.abtwallet.io/';

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

  const handleClose = () => setConnectOpen(false);
  const handleSuccess = () => {
    // 成功登入後重新導向或更新 UI
    window.location.reload();
  };

  return (
    <SessionProvider serviceHost="/">
      <div className="main-content">
        <SessionConsumer>
          {({ session }) => {
            if (session.loading) {
              return <div>Loading session...</div>;
            }

            return session.user ? (
              <div>
                <h2>Welcome, {session.user.did}!</h2>
                <button onClick={() => session.logout()}>Logout</button>
              </div>
            ) : (
              <Button onClick={() => setConnectOpen(true)}>Connect Wallet</Button>
            );
          }}
        </SessionConsumer>
      </div>

      <DidConnect
        popup
        open={isConnectOpen}
        action="login"
        checkFn={axios.get}
        onClose={handleClose}
        onSuccess={handleSuccess}
        messages={{
          title: 'Login to My App',
          scan: 'Scan QR code with your DID Wallet',
          confirm: 'Confirm login on your wallet',
          success: 'You have successfully signed in!',
        }}
        webWalletUrl={webWalletUrl}
      />
    </SessionProvider>
  );
}

export default App;
```

此範例展示了如何僅用幾個元件來管理使用者會話並觸發登入過程。

### 後續步驟

現在您已對該程式庫有了基本了解，可以準備進行更深入的探索。

<x-card data-title="開始使用" data-href="/getting-started" data-icon="lucide:rocket" data-cta="開始建構">
  跟隨我們的逐步指南，從頭開始將 DID Connect 整合到您自己的應用程式中。
</x-card>