# 快速入门

本指南将引导你完成使用 `@arcblock/did-connect-react` 将去中心化身份（DID）验证集成到你的 React 应用中的基本步骤。只需几分钟，你就能拥有一个功能齐全的登录和登出流程。

### 前提条件

在开始之前，请确保你的开发环境满足以下条件：

- 你已建立一个 React 项目。
- 你有一个正在运行的 Blocklet Server 实例，用于处理验证请求。该库旨在与由 Blocklet Server 提供支持的后端无缝协作。

## 第 1 步：安装库

首先，将 `@arcblock/did-connect-react` 包添加到你的项目中。你可以使用 npm 或 yarn。

```bash Install with npm icon=logos:npm
npm install @arcblock/did-connect-react
```

```bash Install with yarn icon=logos:yarn
yarn add @arcblock/did-connect-react
```

## 第 2 步：设置 SessionProvider

`SessionProvider` 是该库的核心。它是一个上下文提供程序，用于管理用户的会话状态（如登录状态和用户信息），并使其对所有包裹在其中的组件可用。你应该将其放置在应用的根部，例如，在你的 `App.js` 文件中。

对于基于 Blocklet 构建的应用，推荐的初始化提供程序的方法是使用 `createAuthServiceSessionContext` 工厂函数。

```javascript App.js icon=logos:react
import React from 'react';
import { createAuthServiceSessionContext } from '@arcblock/did-connect-react/lib/Session';
import Home from './Home'; // 我们将在下一步创建此组件

// createAuthServiceSessionContext 针对 Blocklet 环境进行了优化
const { SessionProvider } = createAuthServiceSessionContext();

function App() {
  return (
    // serviceHost prop 指向后端验证服务的基础路径。
    // 对于标准 Blocklet，这通常是 blocklet 的前缀或“/”。
    <SessionProvider serviceHost="/">
      <Home />
    </SessionProvider>
  );
}

export default App;
```

## 第 3 步：实现登录和登出

现在，让我们创建一个允许用户登录和登出的组件。我们可以使用 React 的 `useContext` 钩子和 `SessionContext` 来访问会话数据和函数。

`session` 对象为你提供了所需的一切：当前的 `user`、`loading` 状态，以及像 `login()` 和 `logout()` 这样的函数。

```javascript Home.js icon=logos:react
import React, { useContext } from 'react';
import { SessionContext } from '@arcblock/did-connect-react/lib/Session';
import ConnectButton from '@arcblock/did-connect-react/lib/Button';
import Button from '@arcblock/ux/lib/Button'; // 一个通用按钮
import CircularProgress from '@mui/material/CircularProgress';

function Home() {
  // 访问会话上下文
  const { session } = useContext(SessionContext);

  // 解构以便更轻松地访问
  const { user, loading, login, logout } = session;

  // 在会话初始化期间显示加载指示器
  if (loading) {
    return <CircularProgress />;
  }

  return (
    <div style={{ padding: '20px', textAlign: 'center' }}>
      {user ? (
        // 如果用户已登录，则显示其 DID 和登出按钮
        <div>
          <h1>Welcome!</h1>
          <p>Your DID: {user.did}</p>
          <Button variant="contained" color="secondary" onClick={logout}>
            Logout
          </Button>
        </div>
      ) : (
        // 如果未登录，则显示登录按钮
        <div>
          <h1>Please Sign In</h1>
          <ConnectButton onClick={() => login()}>
            Connect Wallet
          </ConnectButton>
        </div>
      )}
    </div>
  );
}

export default Home;
```

当用户点击 `ConnectButton` 时，`login()` 函数被调用。该函数负责打开 DID Connect 弹窗，显示一个二维码供用户使用其 DID 钱包扫描，并管理整个验证过程。

## 第 4 步：访问用户数据

用户成功登录后，`session.user` 对象将被填充。该对象包含从用户 DID 钱包中检索到的用户个人资料信息。

由上下文提供的 `session` 对象是你与用户验证状态交互的主要接口。以下是其关键属性：

<x-field-group>
  <x-field data-name="user" data-type="object | null" data-desc="已验证的用户对象。如果没有用户登录，则为 `null`。">
    <x-field data-name="did" data-type="string" data-desc="用户的去中心化身份标识（DID）。"></x-field>
    <x-field data-name="fullName" data-type="string" data-desc="来自用户钱包个人资料的全名。"></x-field>
    <x-field data-name="email" data-type="string" data-desc="来自用户钱包个人资料的电子邮件。"></x-field>
  </x-field>
  <x-field data-name="loading" data-type="boolean" data-desc="在会话初始化或刷新期间为 `true`，否则为 `false`。"></x-field>
  <x-field data-name="login" data-type="function" data-desc="一个启动登录过程的函数，它会打开 DID Connect UI。"></x-field>
  <x-field data-name="logout" data-type="function" data-desc="一个用于登出用户并清除会话的函数。"></x-field>
  <x-field data-name="initialized" data-type="boolean" data-desc="初始会话检查完成后为 `true`。"></x-field>
</x-field-group>

## 你已准备就绪！

恭喜！你已成功在你的 React 应用中实现了一个完整的基于 DID 的验证流程。用户现在可以使用他们的 DID 钱包登录，并且你的应用可以安全地访问他们的会话信息。

### 后续步骤

要深入了解并探索更多高级功能，请查看以下部分：

<x-cards>
  <x-card data-title="会话管理 (SessionProvider)" data-icon="lucide:key-round" data-href="/core-components/session-provider">
    了解 `SessionProvider` 的所有配置选项，以自定义会话行为、超时等。
  </x-card>
  <x-card data-title="连接 UI (DidConnect)" data-icon="lucide:qr-code" data-href="/core-components/did-connect">
    探索 `DidConnect` 组件，以声明方式将连接 UI 直接嵌入到你的页面中。
  </x-card>
</x-cards>