DIDSpaceConnection

DIDSpaceConnection 元件是一款多功能的 UI 卡片，旨在顯示已連接 DID Space 的關鍵資訊。它以清晰且互動的方式呈現空間的詳細資訊，包括其 NFT 頭像、名稱、DID 和目前的連線狀態。

此元件具有高度可自訂性，允許您新增自訂操作和頁腳內容，以根據應用程式的需求調整使用者體驗。

Props

endpoint string (required) — DID Space 物件的 API 端點 URL。範例：https://example.com/app/api/space/{spaceDid}/app/{appDid}/object/。
selected boolean (default: false) — 若為 true，卡片將帶有醒目提示邊框並顯示連線狀態。
compat boolean — 若為 true，則強制使用緊湊佈局。若為 undefined，則在行動裝置上自動切換到緊湊佈局。
action React.ReactNode | ((props: DIDSpaceConnectionContext) => React.ReactNode) (default: null) — 在卡片的操作區域中渲染的自訂內容或元件。
footer boolean | React.ReactNode | ((props: DIDSpaceConnectionContext & { originalFooter: React.ReactNode }) => React.ReactNode) (default: false) — 頁腳的自訂內容。若設為 true，預設會顯示最新的稽核日誌。
deps any[] (default: []) — 一個依賴項陣列，當其變更時，將觸發 DID Space 資訊的重新整理。

Context 類型

當為 action 或 footer 使用函式 props 時，您會收到一個具有以下結構的 context 物件：

DIDSpaceConnectionContext

spaceGateway DIDSpaceGateway (required) — 包含有關已連接 DID Space 的基本資訊。
spaceStatus DIDSpaceStatus (required) — DID Space 目前的連線狀態。
errorCode number (required) — 如果 spaceStatus 為 'unavailable'，則為特定的錯誤碼。
selected boolean (required) — 傳遞給元件的 selected prop 的值。
compat boolean (required) — 指示元件是否處於緊湊模式。
refresh () => void (required) — 一個手動觸發空間資訊和狀態重新整理的函式。

DIDSpaceGateway

did string (required) — 空間的 DID。
name string (required) — 空間的名稱。
url string (required) — DID Space 閘道的基本 URL（例如，https://spaces.arcblock.io）。
endpoint string (required) — 完整的物件端點 URL。
ownerDid string (required) — 空間擁有者的 DID。

DIDSpaceStatus

DIDSpaceStatus enum — 一個表示連線狀態的列舉。可能的值包括：loading、connected、disconnected、unavailable。

基本用法

要顯示 DID Space，您只需要提供 endpoint prop。該元件將處理擷取和顯示必要的資訊。

Basic DIDSpaceConnection Example

import { DIDSpaceConnection } from '@blocklet/did-space-react';

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return <DIDSpaceConnection endpoint={endpoint} />;
}

使用場景

選取狀態與狀態

將 selected prop 設為 true 以應用醒目提示邊框並顯示連線狀態。這對於在列表中指示當前作用中或選取的 DID Space 很有用。

Selected DIDSpaceConnection

import { DIDSpaceConnection } from '@blocklet/did-space-react';

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return <DIDSpaceConnection endpoint={endpoint} selected />;
}

緊湊佈局

使用 compat prop 來渲染卡片的更精簡版本，這對於列表或行動裝置視圖非常理想。

Compact DIDSpaceConnection

import { DIDSpaceConnection } from '@blocklet/did-space-react';

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return <DIDSpaceConnection endpoint={endpoint} selected compat />;
}

自訂操作

您可以使用 action prop 新增自訂互動元素，如按鈕或連結。傳遞一個函式來存取連線 context，包括 spaceGateway 的詳細資訊和 refresh 函式。

範例 1：重新連線已斷線的空間

一個常見的使用案例是提供一種方式，讓使用者在連線中斷時可以重新連線。您可以檢查 spaceStatus 並渲染一個 DIDSpaceConnect 元件來啟動重新連線流程。DIDSpaceConnect 元件預設會渲染一個按鈕。

DIDSpaceConnection with Reconnect Action

import { DIDSpaceConnection, DIDSpaceConnect, DIDSpaceStatus } from '@blocklet/did-space-react';

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return (
    <DIDSpaceConnection
      endpoint={endpoint}
      selected
      action={({ spaceStatus, spaceGateway, refresh }) => {
        if (spaceStatus === DIDSpaceStatus.DISCONNECTED) {
          return (
            <DIDSpaceConnect
              reconnect
              spaceDid={spaceGateway.did}
              spaceGatewayUrl={spaceGateway.url}
              onSuccess={refresh} // Refresh the card after successful reconnection
            />
          );
        }
        return null;
      }}
    />
  );
}

範例 2：開啟 DID Space 網站

這個範例新增了一個圖示按鈕，連結到 DID Space 的公開頁面。

DIDSpaceConnection with Custom Action

import { DIDSpaceConnection } from '@blocklet/did-space-react';
import { IconButton, Link } from '@mui/material';
import OpenInNewIcon from '@mui/icons-material/OpenInNew';

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return (
    <DIDSpaceConnection
      endpoint={endpoint}
      selected
      action={({ spaceGateway }) => (
        <IconButton
          size="small"
          component={Link}
          href={`${spaceGateway.url}/space/${spaceGateway.did}`}
          target="_blank"
        >
          <OpenInNewIcon />
        </IconButton>
      )}
    />
  );
}

自訂頁腳

footer prop 允許強大的自訂功能。您可以啟用預設的稽核日誌顯示或渲染完全自訂的內容。

顯示預設稽核日誌

將 footer 設為 true，以自動擷取並顯示該 DID Space 內應用程式的最新稽核日誌條目。

DIDSpaceConnection with Audit Log Footer

import { DIDSpaceConnection } from '@blocklet/did-space-react';

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return <DIDSpaceConnection endpoint={endpoint} selected footer />;
}

新增自訂頁腳內容

提供一個函式給 footer prop 來渲染自訂元件。該函式會收到連線 context 和 originalFooter（預設的稽核日誌欄），讓您可以組合自己的佈局。

DIDSpaceConnection with Custom Footer Content

import { DIDSpaceConnection } from '@blocklet/did-space-react';
import { Box, Typography } from '@mui/material';

export default function Demo() {
  const endpoint = 'https://arcblock.net/app/api/space/z8iZufAgx4Z1y5tA5y5Q4z4a5y5Q4z4a5y5Q/app/zNKd5QmRt3h5VX8u4J4egJkA4xQaDKwM2n5D/object/';

  return (
    <DIDSpaceConnection
      endpoint={endpoint}
      selected
      footer={({ spaceGateway, originalFooter }) => (
        <>
          {/* Display the default audit log */}
          {originalFooter}
          {/* Display additional custom info */}
          <Box display="flex" alignItems="center" mt={1}>
            <Typography variant="caption">Owner: {spaceGateway.ownerDid}</Typography>
          </Box>
        </>
      )}
    />
  );
}

連線狀態

該元件以視覺化方式表示與 DID Space 的連線狀態。了解這些狀態有助於偵錯並提供更好的使用者回饋。

載入中：元件在擷取有關 DID Space 的資訊時，最初處於載入狀態。在此階段會顯示骨架載入器。
已連線：表示成功且有效的連線。應用程式擁有必要的權限，且 DID Space 完全運作正常。它會以「已連線」標籤和成功圖示顯示。
已斷線：應用程式未被授權存取 DID Space。這通常意味著使用者需要通過連線流程來授予權限。它會以「已斷線」標籤和中性圖示顯示。
無法使用：由於問題，無法連線或使用 DID Space。此狀態會以錯誤標籤和圖示顯示。當無法使用時，懸停時的工具提示會提供更多詳細資訊。常見原因包括：
- 訂閱過期/逾期：DID Space 的訂閱已過期。
- 超過使用限制：DID Space 已達到其使用量上限。
- 版本不相容：DID Space 版本與元件庫的要求不相容。
- CORS 封鎖：跨來源資源共享 (CORS) 錯誤正在阻止連線。這通常需要在 DID Space 主機上進行設定變更。
- 網路錯誤：由於網路問題（如逾時或 DNS 失敗），元件無法連線到 DID Space 端點。

現在您已了解如何顯示 DID Space 資訊，您可能會想更深入地了解元件所使用的資料結構。更多詳細資訊，請參閱 API 參考：類型。