跳到主要内容

useConnect

useConnect hook 提供了一种强大的、编程化的方式来打开、关闭和管理 DidConnect UI 模态框。当您需要比声明式的 Button 组件提供更多对连接流程的控制时，例如从自定义 UI 元素、菜单项或响应应用程序事件来触发模态框，它就是理想的解决方案。

此 hook 是 Button 组件背后的引擎，让您可以直接访问相同的核心功能。

工作原理

useConnect hook 返回两个主要元素：

  1. `connectHolder`

    一个必须在组件树中渲染的 React 元素。此元素负责在 DidConnect 模态框被激活时进行渲染。在 open 函数被调用之前，它保持不可见。

  2. `connectApi`

    一个包含用于控制模态框生命周期的函数（open、close、openPopup、loginOAuth）的对象。

useConnect

设置

要使用此 hook，请在您的组件中导入并调用它。然后，确保在您的应用程序中的某个位置渲染 connectHolder，最好是在顶层组件中，以确保模态框可以覆盖所有其他内容。

Basic Setup

javascript
import React from 'react';
import { useConnect } from '@arcblock/did-connect-react';

function MyComponent() {
  // 1. 初始化 hook
  const { connectHolder, connectApi } = useConnect();

  const handleLogin = () => {
    // 2. 使用 API 打开模态框
    connectApi.open({
      action: 'login',
      onSuccess: (result) => {
        console.log('登录成功！', result);
      },
      onClose: () => {
        console.log('模态框被用户关闭。');
      }
    });
  };

  return (
    <div>
      <button type="button" onClick={handleLogin}>
        Login with DID
      </button>

      {/* 3. 渲染 holder 组件 */}
      {connectHolder}
    </div>
  );
}

export default MyComponent;

API 参考

connectApi 对象提供了以下方法来控制连接过程。

connectApi.open(options)

这是触发和显示 DidConnect 模态框的主要函数。它接受一个 options 对象，用于配置连接会话的行为、外观和回调。

参数 (options)

  • action string (required) — 连接请求的目的，例如 login、claim、sign 等。这决定了钱包内的操作流程。
  • onSuccess (result: object) => void — 当用户在钱包中成功完成操作时执行的回调函数。result 对象包含来自钱包的响应。
  • onClose () => void — 当用户在未完成操作的情况下手动关闭模态框时执行的回调函数。
  • onError (error: any) => void — 如果在过程中发生错误（例如超时或网络问题）时执行的回调函数。
  • messages ConnectMessages — 一个用于自定义模态框中显示文本的对象。有关详细信息，请参阅 ConnectMessages 类型。
    • title string — 模态框标题。
    • scan string — 二维码附带的文本。
    • confirm string — 确认步骤的文本。
    • success ReactNode — 成功屏幕的内容。
  • popup boolean (default: true) — 如果为 true，UI 将作为模态对话框显示。如果为 false，它将内联渲染，需要设置 containerEl。
  • containerEl Element — 当 popup 设置为 false 时，DidConnect 组件将在此 DOM 元素中渲染。
  • closeTimeout number (default: 2000) — 成功连接后，模态框自动关闭前的延迟时间（以毫秒为单位）。
  • checkInterval number (default: 2000) — 轮询服务器以检查会话状态的间隔时间（以毫秒为单位）。
  • checkTimeout number (default: 300000) — 连接尝试超时的总时间（以毫秒为单位）。
  • extraParams object (default: {}) — 要包含在会话创建请求中的任何额外参数，这些参数可以在服务器端检索。

connectApi.close()

手动关闭 DidConnect 模态框。模态框在成功或用户取消时会自动关闭，但如果需要因其他原因以编程方式关闭它，可以调用此函数。

javascript
// 示例：在成功回调中短暂延迟后关闭模态框
connectApi.open({
  action: 'login',
  onSuccess: () => {
    showTemporarySuccessMessage();
    setTimeout(() => {
      connectApi.close();
    }, 1500);
  },
  closeTimeout: 999999 // 防止自动关闭
});

connectApi.openPopup(params, options)

此函数提供了一种替代的连接方法，它会在新的浏览器弹出窗口中打开 DID Connect 流程，而不是在当前页面内打开模态框。这对于某些类似 OAuth 的流程或在无法注入模态框的网站上进行集成时非常有用。

参数

  • params ConnectProps (required) — 与 open 方法的选项类似。一个关键区别是，params.extraParams.provider 是必需的，用于标识认证方法（例如 'github'、'google'）。
  • options object — 弹出窗口本身的配置。
    • baseUrl string — 用于构建弹出窗口 URL 的基础 URL。
    • locale string (default: en) — 弹出窗口内容的区域设置。
    • popupOptions object — 直接传递给 window.open() 的选项，用于自定义弹出窗口的大小和功能。

用法

openPopup 函数返回一个 Promise，它在成功时解析为认证数据，在失败或取消时拒绝。

javascript
const handleGithubLogin = async () => {
  try {
    const result = await connectApi.openPopup({
      action: 'login',
      onSuccess: () => console.log('此回调也会被触发'),
      extraParams: { provider: 'github' } // 这是必需的
    });
    console.log('通过弹出窗口登录成功：', result);
  } catch (err) {
    if (err.message === 'Popup closed') {
      console.log('用户关闭了弹出窗口。');
    } else {
      console.error('发生错误：', err);
    }
  }
};

connectApi.loginOAuth(options)

这是一个辅助函数，用于直接启动 OAuth 登录流程。它是一个较低级别的实用工具，在库的其他部分内部使用。

参数 (options)

  • provider string (required) — 要使用的 OAuth 提供商，例如 'github'、'google'。
  • action string (required) — 操作，通常是 'login'。
  • extraParams object — OAuth 流程的附加参数。
  • onLogin function (required) — 成功登录后执行的回调函数。