DIDSpaceConnect | ArcBlock

DIDSpaceConnect 元件提供了一個多功能的按鈕，用於啟動與 DID Space 的連接。它簡化了各種驗證流程，包括初始連接和重新連接，並可以與使用者會話整合以進行持久儲存。

運作方式

該元件會渲染一個分割按鈕，提供使用者兩種主要連接方式：

使用錢包
此方式透過使用者的 DID Wallet 啟動連接流程，這是推薦且最常用的方法。
使用空間網關
此方式允許使用者手動輸入其 DID Space 網關的 URL 來建立連接。

成功連接後，該元件會回傳一個 spaceGateway 物件，其中包含有關已連接空間的基本詳細資訊。

DIDSpaceConnect

Props

DIDSpaceConnect 元件可透過其 props 進行高度自訂。

session object — 一個來自 @arcblock/did-connect-react 的可選會話物件。如果提供，連接的 spaceGateway 將自動儲存到使用者會話中，並呼叫 session.refresh()。
reconnect boolean (default: false) — 如果為 true，元件將渲染為重新連接按鈕。此模式需要設定 spaceDid 和 spaceGatewayUrl。
spaceDid string — 要重新連接的空間的 DID。當 reconnect 為 true 時為必需。
spaceGatewayUrl string — 要重新連接的空間的網關 URL。當 reconnect 為 true 時為必需。
options DIDSpaceConnectOptions — 傳遞給底層驗證流程的額外選項。
connectScope 'user' | 'app' (default: 'user') — 連接的範圍，決定如何處理和儲存連接。
connectText string | React.ReactNode — 在主連接按鈕上顯示的自訂文字或元素。
onSuccess function — 連接成功時執行的回呼函式。它會收到一個包含 spaceGateway、原始 response 和 decrypt 函式的物件。
onError (error: Error) => void — 連接過程中發生錯誤時執行的回呼函式。
...rest ButtonProps — 任何其他來自 Material-UI 的 Button 元件的 props 都會被傳遞下去，以自訂按鈕的外觀。

使用場景

1. 基本連接（無狀態）

這是最直接的使用案例。該元件用於建立連接並透過 onSuccess 回呼函式檢索 spaceGateway 物件。應用程式隨後負責管理此物件。

Demo.tsx

import Toast from '@arcblock/ux/lib/Toast';
import { DIDSpaceConnect, type DIDSpaceGateway } from '@blocklet/did-space-react';
import { useState } from 'react';
import Button from '@mui/material/Button';
import Box from '@mui/material/Box';
import Typography from '@mui/material/Typography';

export default function Demo() {
  const [spaceGateway, setSpaceGateway] = useState<DIDSpaceGateway | null>(null);

  const handleSuccess = async ({ spaceGateway: gw }: { spaceGateway: DIDSpaceGateway }) => {
    try {
      // 根據需要儲存或使用 spaceGateway 物件
      setSpaceGateway(gw);
      Toast.success(`已連接至 ${gw.name}`);
      console.log('已連接的空間網關：', gw);
    } catch (error: any) {
      console.error(error);
      Toast.error(error.message);
    }
  };

  const handleDisconnect = () => {
    setSpaceGateway(null);
    Toast.info('已斷開連接。');
  };

  if (spaceGateway) {
    return (
      <Box>
        <Typography>已連接至：{spaceGateway.name} ({spaceGateway.did})</Typography>
        <Button onClick={handleDisconnect} variant="outlined" sx={{ mt: 2 }}>
          斷開連接
        </Button>
      </Box>
    );
  }

  return <DIDSpaceConnect onSuccess={handleSuccess} variant="contained" />;
}

2. 連接並儲存到使用者會話

透過提供 session prop，該元件將在成功連接後自動將連接詳細資訊儲存到使用者會話中，然後觸發會話刷新。對於具有使用者帳戶的應用程式，這是推薦的方法。

SessionDemo.tsx

import { DIDSpaceConnect } from '@blocklet/did-space-react';
import { useSessionContext } from '@arcblock/did-connect-react';
import Box from '@mui/material/Box';
import Typography from '@mui/material/Typography';

export default function SessionDemo() {
  const session = useSessionContext();

  // 使用者連接的空間將在 session.user.didSpace 中可用
  const connectedSpace = session.user?.didSpace;

  if (connectedSpace) {
    return (
      <Box>
        <Typography variant="h6">歡迎，{session.user.name}！</Typography>
        <Typography>您連接的空間是：{connectedSpace.name}</Typography>
        <Typography variant="caption">DID：{connectedSpace.did}</Typography>
      </Box>
    );
  }

  return (
    <div>
      <p>您尚未連接 DID 空間。</p>
      <DIDSpaceConnect session={session} variant="contained" />
    </div>
  );
}

3. 重新連接到先前連結的空間

如果使用者已經連接了一個 DID Space（例如，儲存在他們的會話中），您可以提供一種方式讓他們重新建立連接。將 reconnect prop 設定為 true，並提供儲存的連接詳細資訊中的 spaceDid 和 spaceGatewayUrl。該元件將渲染一個專用的重新連接按鈕。

ReconnectDemo.tsx

import { DIDSpaceConnect } from '@blocklet/did-space-react';
import { useSessionContext } from '@arcblock/did-connect-react';
import Toast from '@arcblock/ux/lib/Toast';
import { useState } from 'react';
import Button from '@mui/material/Button';
import Box from '@mui/material/Box';
import Typography from '@mui/material/Typography';

export default function ReconnectDemo() {
  const session = useSessionContext();
  const { did, url } = session.user?.didSpace ?? {};
  const [isConnected, setIsConnected] = useState(true); // 假設初始為已連接狀態

  const handleSuccess = () => {
    setIsConnected(true);
    Toast.success('成功重新連接！');
  };

  const handleDisconnect = () => {
    // 在實際應用中，您會在此處清除無效的會話/權杖
    setIsConnected(false);
    Toast.info('連接已斷開。請重新連接。');
  };

  if (!did || !url) {
    // 如果沒有連結的空間，則顯示初始連接按鈕。
    return <DIDSpaceConnect session={session} variant="contained" />;
  }

  if (!isConnected) {
    return (
      <Box>
        <Typography color="error">與 {did} 的連接已斷開。</Typography>
        <DIDSpaceConnect
          reconnect
          spaceDid={did}
          spaceGatewayUrl={url}
          session={session}
          onSuccess={handleSuccess}
          onError={(err) => Toast.error(`重新連接失敗：${err.message}`)}
          variant="outlined"
          sx={{ mt: 1 }}
        />
      </Box>
    );
  }

  return (
    <Box>
      <Typography color="primary">已連接至空間：{did}</Typography>
      <Button onClick={handleDisconnect} variant="text" color="warning" sx={{ mt: 1 }}>
        模擬斷開連接
      </Button>
    </Box>
  );
}

後續步驟

建立連接後，您可能希望顯示有關已連接 DID Space 的資訊。DIDSpaceConnection 元件就是為此目的而設計的。

DIDSpaceConnection

一個顯示卡，用於顯示 DID 空間的資訊和連接狀態，並提供自訂選項。

查看元件