跳到主要内容

连接 UI (DidConnect)

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

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

在使用 DidConnect 之前,请确保已使用 SessionProvider 包裹您的应用程序,以管理整体会话状态。

基本用法

要使用 DidConnect,您需要导入它并提供一些必要的 props。该组件通常由一个决定其可见性的状态变量控制。

DID Connect 示例

jsx
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 组件协调整个用户认证流程,从显示连接选项到处理最终的成功或错误状态。

Connection UI (DidConnect)

组件 Props

DidConnect 组件可通过其 props 进行高度配置。以下是可用选项的详细列表。

核心配置

这些 props 对于设置组件的基本功能至关重要。

  • action string (required) — 定义连接的目的,例如 login、claim、sign 等。此字符串会传递给您的后端以确定所需的操作。
  • checkFn function (required) — 用于向后端轮询会话状态更新的函数。它应该是一个能发起 API 请求的函数,例如 axios.get。
  • baseUrl string (default: '') — API 端点的基础 URL。如果您的 API 位于不同的域上,请在此处指定。
  • prefix string (default: /api/did) — 您后端上 DID Connect API 端点的 URL 前缀。

行为控制

这些 props 控制连接过程的行为方式。

  • enabledConnectTypes string[] (default: ["web", "mobile", ...]) — 一个字符串数组,用于指定要显示的连接方式。可能的值包括 web、mobile、github、google、apple、passkey 等。
  • passkeyBehavior 'none' | 'both' | 'only-existing' | 'only-new' (default: 'none') — 控制 Passkey 认证的行为。none 表示禁用,both 允许创建新密钥和使用现有密钥,only-existing 限制为仅使用现有密钥,而 only-new 强制创建新密钥。
  • allowWallet boolean (default: true) — 如果为 false,二维码和移动钱包连接选项将被隐藏。
  • autoConnect boolean (default: true) — 如果为 true,组件将自动尝试使用来自同一设备的先前建立的连接。
  • forceConnected boolean | string (default: true) — 如果为 true,用户必须使用与他们已登录的 DID 相同的 DID 进行连接。如果提供了 DID 字符串,则用户必须使用该特定的 DID 进行连接。
  • saveConnect boolean (default: true) — 如果为 true,成功的连接信息将保存在本地,以供将来的 autoConnect 尝试使用。
  • useSocket boolean (default: true) — 如果为 true,则尝试使用 WebSocket 进行实时状态更新,如果无法建立连接,则回退到轮询。

UI 自定义

自定义 DidConnect 组件的外观和文本。

  • mode 'dialog' | 'drawer' | 'page' (default: 'dialog') — 确定组件的显示方式。dialog 将其显示为居中模态框,drawer 显示为底部抽屉(在移动设备上),而 page 将其直接嵌入到文档流中。
  • messages object — 一个用于自定义 UI 中显示的文本的对象。
    • title string — 顶部的​​主标题。
    • scan string — 标题下方的说明性文本。
    • confirm string — 扫描二维码后显示的文本。
    • success string | ReactNode — 连接成功时显示的消息。
    • error string — 发生错误时显示的消息。
  • hideCloseButton boolean (default: false) — 如果为 true,右上角的关闭按钮(X)将被隐藏。
  • extraContent ReactNode (default: null) — 允许您向 UI 中注入自定义的 React 组件或元素,通常显示在主标题/描述下方。
  • customItems ReactNode[] (default: []) — 一个自定义 React 节点数组,将被添加到连接方式列表中。
  • disableSwitchApp boolean (default: false) — 如果您正在使用统一登录站点群,此 prop 会阻止用户在登录过程中在站点群中的不同应用程序之间切换。
  • webWalletUrl string — 用于“使用网页钱包连接”选项的基于 Web 的 DID Wallet 的 URL。默认为官方的 ArcBlock 网页钱包。

回调

在连接生命周期的不同阶段调用的函数。

  • onClose function (required) — 当用户关闭 DidConnect 对话框时(例如,通过点击关闭按钮或模态框外部)执行的回调函数。
  • onSuccess function (required) — 连接成功后执行的回调函数。会话数据作为参数传递。
  • onError function — 在此过程中发生错误时执行的回调函数。错误对象或消息作为参数传递。
  • onRecreateSession function — 当会话需要重置时(例如,在超时后或用户手动取消并重试时)调用的回调函数。

后续步骤

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