跳到主要內容

類型

本節為 @blocklet/js-sdk 匯出的核心 TypeScript 類型和介面提供了詳細的參考。在您的專案中使用這些類型，可以幫助您利用 TypeScript 的靜態分析和自動完成功能，以獲得更好的開發體驗。

核心 Blocklet 類型

這些類型定義了 Blocklet 應用程式及其元件的基本結構。

Blocklet

代表一個 Blocklet 的完整元資料和設定。當應用程式在 Blocklet Server 環境中執行時，此物件通常可作為全域變數 window.blocklet 使用。

  • did string (required) — Blocklet 的去中心化識別碼（DID）。
  • appId string (required) — 應用程式 ID，同時也是主要元件的 DID。
  • appPk string (required) — 與應用程式關聯的公鑰。
  • appIds string[] — 關聯的應用程式 ID 列表，用於聯合登入群組。
  • appPid string (required) — 應用程式的程序 ID。
  • appName string (required) — 應用程式的人類可讀名稱。
  • appDescription string (required) — 應用程式的簡短描述。
  • appLogo string (required) — 應用程式標誌（方形）的 URL。
  • appLogoRect string (required) — 應用程式標誌（矩形）的 URL。
  • appUrl string (required) — 應用程式託管的主要 URL。
  • domainAliases string[] — 應用程式的備用網域名稱。
  • isComponent boolean (required) — 表示該 Blocklet 是否為另一個 Blocklet 的元件。
  • prefix string (required) — Blocklet 路由的 URL 前綴。
  • groupPrefix string (required) — 聯合登入群組的 URL 前綴。
  • pageGroup string (required) — 此頁面所屬的群組。
  • version string (required) — Blocklet 的版本。
  • mode string (required) — Blocklet 的執行模式（例如 'development'、'production'）。
  • tenantMode 'single' | 'multiple' (required) — Blocklet 的租賃模式。
  • theme BlockletTheme (required) — Blocklet 的主題設定。
  • navigation BlockletNavigation[] (required) — 用於 Blocklet UI 的導覽項目陣列。
  • preferences Record<string, any> (required) — 使用者可設定的偏好設定。
  • languages { code: string; name: string }[] (required) — 支援的語言列表。
  • passportColor string (required) — DID 錢包護照中使用的主要顏色。
  • componentMountPoints BlockletComponent[] (required) — 由此 Blocklet 掛載的子元件列表。
  • alsoKnownAs string[] (required) — 備用識別碼列表。
  • trustedFactories string[] (required) — 受信任的工廠 DID 列表。
  • status string (required) — Blocklet 目前的執行狀態。
  • serverDid string (required) — Blocklet Server 實例的 DID。
  • serverVersion string (required) — Blocklet Server 的版本。
  • componentId string (required) — 元件的 ID。
  • webWalletUrl string (required) — 網頁版 DID 錢包的 URL。
  • updatedAt number (required) — 上次更新的時間戳。
  • settings BlockletSettings (required) — Blocklet 的詳細設定。

BlockletSettings

包含 Blocklet 的各種設定，包括會話管理、聯合登入群組設定和 OAuth 提供者詳細資訊。

  • session object (required) — 會話設定。
    • ttl number (required) — 會話的存活時間（以秒為單位）。
    • cacheTtl number (required) — 快取的存活時間（以秒為單位）。
  • federated object (required) — 聯合登入群組設定。
    • master object (required) — 群組中主應用程式的資訊。
      • appId string (required) — 主應用程式 ID。
      • appPid string (required) — 主應用程式程序 ID。
      • appName string (required) — 主應用程式名稱。
      • appDescription string (required) — 主應用程式描述。
      • appUrl string (required) — 主應用程式 URL。
      • appLogo string (required) — 主應用程式標誌 URL。
      • version string (required) — 主應用程式版本。
    • config Record<string, any> (required) — 聯合群組的額外設定。
  • oauth Record<string, { enabled: boolean; [x: string]: any }> (required) — OAuth 提供者設定，以提供者名稱為鍵。

BlockletComponent

描述一個掛載在父 Blocklet 中的元件。它繼承自 TComponentInternalInfo 的屬性。

  • status keyof typeof BlockletStatus (required) — 元件的執行狀態（例如 'running'、'stopped'）。

使用者與驗證類型

AuthService 使用這些類型來管理使用者個人資料、設定和與驗證相關的資料。

UserPublicInfo

代表使用者的基本公開個人資料資訊。

  • avatar string (required) — 使用者頭像圖片的 URL。
  • did string (required) — 使用者的去中心化識別碼（DID）。
  • fullName string (required) — 使用者的全名。
  • sourceAppPid string | null (required) — 使用者來源應用程式的程序 ID（如果適用）。

NotificationConfig

定義使用者的通知偏好設定，包括 webhook 設定和通知管道。

  • webhooks Webhook[] — 已設定的 webhook 陣列。
  • notifications object — 特定管道的通知設定。
    • email boolean — 啟用或停用電子郵件通知。
    • wallet boolean — 啟用或停用 DID 錢包通知。
    • phone boolean — 啟用或停用電話通知。

Webhook

定義單一 webhook 設定的結構。

  • type 'slack' | 'api' (required) — webhook 端點的類型。
  • url string (required) — 將發送 webhook 通知的 URL。

PrivacyConfig

代表使用者隱私設定的物件，其中鍵對應特定的隱私選項。

  • [key] boolean (required) — 代表隱私設定的動態鍵，其布林值表示是否啟用。

SpaceGateway

定義 DID Space 閘道的屬性。

  • did string (required) — 空間閘道的 DID。
  • name string (required) — 空間閘道的名稱。
  • url string (required) — 空間閘道的公開 URL。
  • endpoint string (required) — 空間閘道的 API 端點。

會話管理類型

UserSessionService 使用這些類型來管理跨不同裝置和應用程式的使用者登入會話。

UserSession

代表單一使用者登入會話，包含有關裝置、應用程式和使用者的詳細資訊。

  • appName string (required) — 會話所屬應用程式的名稱。
  • appPid string (required) — 會話所屬應用程式的程序 ID。
  • extra object (required) — 關於會話的額外元資料。
    • walletOS 'android' | 'ios' | 'web' (required) — 用於登入的錢包作業系統。
  • id string (required) — 會話的唯一識別碼。
  • lastLoginIp string (required) — 上次登入的 IP 位址。
  • passportId string | null (required) — 用於登入的護照 ID。
  • ua string (required) — 客戶端的使用者代理字串。
  • createdAt string — 會話建立時的 ISO 字串時間戳。
  • updatedAt string (required) — 上次會話活動的 ISO 字串時間戳。
  • status string — 會話的目前狀態（例如 'online'、'expired'）。
  • user UserSessionUser — 與會話關聯的使用者的詳細資訊。
  • userDid string (required) — 使用者的 DID。
  • visitorId string (required) — 裝置/瀏覽器的唯一識別碼。

UserSessionUser

包含與 UserSession 相關的詳細使用者資訊。

  • avatar string (required) — 使用者頭像圖片的 URL。
  • did string (required) — 使用者的去中心化識別碼（DID）。
  • email string (required) — 使用者的電子郵件地址。
  • fullName string (required) — 使用者的全名。
  • pk string (required) — 使用者的公鑰。
  • remark string — 關於使用者的選填備註或註記。
  • role string (required) — 使用者的角色（例如 'owner'、'admin'）。
  • roleTitle string (required) — 使用者角色的顯示標題。
  • sourceAppPid string | null (required) — 使用者來源應用程式的程序 ID。
  • sourceProvider 'wallet' | 'auth0' | 'nft' (required) — 用於驗證的原始提供者。

UserSessionList

用於使用者會話列表的分頁回應物件。

  • list UserSession[] (required) — 使用者會話物件的陣列。
  • paging object (required) — 分頁資訊。
    • page number (required) — 目前頁碼。
    • pageSize number (required) — 每頁的項目數。
    • total number (required) — 可用的會話總數。

全域與環境類型

這些類型定義了全域可用的物件和伺服器環境設定。

ServerEnv

代表伺服器端的環境變數，這些變數通常以 window.env 的形式暴露給客戶端。

  • appId string (required) — 應用程式 ID。
  • appPid string (required) — 應用程式程序 ID。
  • appName string (required) — 應用程式名稱。
  • appDescription string (required) — 應用程式描述。
  • apiPrefix string (required) — 後端 API 路由的前綴。
  • baseUrl string (required) — 應用程式的基礎 URL。

全域 Window 宣告

當在瀏覽器環境中執行時，SDK 依賴於 window 物件中存在的某些全域變數。

TypeScript Definition

typescript
declare global {
  interface Window {
    blocklet: Blocklet;
    env?: ServerEnv;
  }
}

工具類型

用於 API 請求和權杖管理的輔助類型。

TokenResult

代表權杖更新操作的成功結果。

  • nextToken string (required) — 新的會話權杖。
  • nextRefreshToken string (required) — 新的更新權杖。

RequestParams

定義了在使用 SDK 的 API 輔助工具發出請求時可以使用的通用參數。

  • lazy boolean — 如果為 true，請求可能會被延遲或延後執行。
  • lazyTime number — 延遲請求的延遲時間（以毫秒為單位）。
  • componentDid string — 請求目標元件的 DID。