跳到主要内容

类型

本节提供了 @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) — 基于 Web 的 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) — 客户端的 User-Agent 字符串。
  • 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。

全局窗口声明

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。