# 连接 UI (DidConnect)

`DidConnect` 组件是一个预构建的、全面的 UI 解决方案，用于处理各种去中心化身份（DID）连接流程。它为登录、认证和个人资料请求等操作提供了用户友好的界面，并开箱即用地支持多种连接方式。

它作为 `@arcblock/did-connect-react` 库的视觉核心，抽象了会话管理和实时状态更新的复杂性。该组件为 DID Wallet 用户显示二维码，并提供其他登录选项，如社交登录（OAuth）和无密码认证（Passkeys）。

在使用 `DidConnect` 之前，请确保已使用 [`SessionProvider`](./core-components-session-provider.md) 包裹您的应用程序，以管理整体会话状态。

## 基本用法

要使用 `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)}>Login with DID</button>
      {isConnectOpen && (
        <DidConnect
          action="login"
          checkFn={axios.get}
          onClose={handleClose}
          onSuccess={handleSuccess}
          messages={{
            title: 'Scan to Sign In',
            scan: 'Scan QR code with your DID Wallet',
            confirm: 'Confirm login on your DID Wallet',
            success: 'You have successfully signed in!',
          }}
        />
      )}
    </div>
  );
}

export default App;
```

在此示例中，点击 “Login with DID” 按钮会将 `isConnectOpen` 状态设置为 `true`，从而将 `DidConnect` 组件渲染为模态对话框。`checkFn` prop 至关重要，因为它是组件用于从您的后端轮询会话状态的函数。

## 工作原理

`DidConnect` 组件协调整个用户认证流程，从显示连接选项到处理最终的成功或错误状态。

<!-- DIAGRAM_IMAGE_START:flowchart:4:3:1765962229 -->
![Connection UI (DidConnect)](assets/diagram/did-connect-diagram-0.zh.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>用于向后端轮询会话状态更新的函数。它应该是一个能发起 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` 允许创建新密钥和使用现有密钥，`only-existing` 限制为仅使用现有密钥，而 `only-new` 强制创建新密钥。</x-field-desc>
  </x-field>
  <x-field data-name="allowWallet" data-type="boolean" data-default="true">
    <x-field-desc markdown>如果为 `false`，二维码和移动钱包连接选项将被隐藏。</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 字符串，则用户必须使用该特定的 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="扫描二维码后显示的文本。"></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>允许您向 UI 中注入自定义的 React 组件或元素，通常显示在主标题/描述下方。</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>用于“使用网页钱包连接”选项的基于 Web 的 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>连接成功后执行的回调函数。会话数据作为参数传递。</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>当会话需要重置时（例如，在超时后或用户手动取消并重试时）调用的回调函数。</x-field-desc>
  </x-field>
</x-field-group>

## 后续步骤

在对 `DidConnect` 组件有了扎实的理解之后，您现在可以构建稳健的认证体验。要对连接 UI 进行更多的程序化控制，请探索 [`useConnect` hook](./hooks-use-connect.md)，它允许您从应用程序的任何位置打开和关闭 `DidConnect` 模态框。