# 概述

`@arcblock/did-connect-react` 库提供了一套全面的 React 组件和钩子，旨在将去中心化身份 (DID) 功能无缝集成到您的 Web 应用程序中。它使用 ArcBlock 的 DID 钱包简化了用户身份验证和会话管理的过程，为传统的登录系统提供了一种安全且用户友好的替代方案。

该库的设计灵活且易于使用，无论您需要一个完整的开箱即用解决方案，还是对身份验证流程进行精细控制，它都能满足您的需求。

### 主要特性

<x-cards data-columns="2">
  <x-card data-title="完整的连接用户界面" data-icon="lucide:qr-code-icon">
    包含 `DidConnect` 组件，这是一个预制的、可定制的模态框，用于处理整个二维码扫描和连接过程。
  </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 钱包之间基于二维码的安全交互。连接完成后，会话将被更新，您的应用程序 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.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>正在加载会话...</div>;
            }

            return session.user ? (
              <div>
                <h2>欢迎, {session.user.did}!</h2>
                <button onClick={() => session.logout()}>登出</button>
              </div>
            ) : (
              <Button onClick={() => setConnectOpen(true)}>连接钱包</Button>
            );
          }}
        </SessionConsumer>
      </div>

      <DidConnect
        popup
        open={isConnectOpen}
        action="login"
        checkFn={axios.get}
        onClose={handleClose}
        onSuccess={handleSuccess}
        messages={{
          title: '登录我的应用',
          scan: '请使用您的 DID 钱包扫描二维码',
          confirm: '在您的钱包上确认登录',
          success: '您已成功登录！',
        }}
        webWalletUrl={webWalletUrl}
      />
    </SessionProvider>
  );
}

export default App;
```

这个例子展示了如何仅用几个组件来管理用户会话和触发登录过程。

### 后续步骤

现在您对该库有了基本的了解，可以开始更深入地学习了。

<x-card data-title="开始使用" data-href="/getting-started" data-icon="lucide:rocket" data-cta="开始构建">
  遵循我们的分步指南，从零开始将 DID Connect 集成到您自己的应用程序中。
</x-card>