跳到主要内容

API 参考

本节为 @arcblock/did-connect-react 库中使用的所有主要 TypeScript 类型提供了全面的参考。理解这些数据结构对于有效使用像 SessionProvider 这样的组件和像 useConnect 这样的钩子至关重要。

连接类型

这些类型主要用于配置 DID Connect 模态框以及与之交互。

ConnectProps

这是从 useConnect 钩子传递给 open 函数或从会话上下文传递给 openDidConnect 函数的主要配置对象。它允许对连接流程的行为和外观进行广泛的自定义。

  • action string (required) — 连接的主要操作，例如 'login'。
  • containerEl Element — 连接模态框应附加到的 DOM 元素。
  • prefix string (default: /api/did) — DID Connect 服务的 API 端点前缀。
  • locale 'en' | 'zh' (default: en) — 用于 UI 的语言。
  • popup boolean (default: false) — 如果为 true，连接 UI 将显示在弹出窗口中而不是模态框中。
  • checkInterval number (default: 2000) — 检查会话状态的间隔时间（以毫秒为单位）。
  • checkTimeout number (default: 300000) — 整个会话检查过程的超时时间（以毫秒为单位）（5 分钟）。
  • closeTimeout number (default: 2000) — 成功连接后关闭模态框前的延迟时间（以毫秒为单位）。
  • extraParams object (default: {}) — 随连接请求发送的任何额外参数。
  • tokenKey string (default: _t_) — 用于存储会话令牌的键。
  • encKey string (default: _ek_) — 用于加密的键。
  • baseUrl string (default: '') — API 请求的基础 URL。
  • messages ConnectMessages — 用于自定义连接 UI 中显示的文本的对象。
  • autoConnect boolean (default: true) — 如果为 true，则自动尝试使用已保存的会话进行连接。
  • forceConnected boolean | string (default: true) — 强制将连接视为已建立。
  • saveConnect boolean (default: true) — 如果为 true，成功的连接会话将被保存以用于 autoConnect。
  • useSocket boolean (default: true) — 如果为 true，则使用 WebSocket 进行实时状态更新。
  • allowWallet boolean (default: true) — 如果为 true，则允许通过 DID Wallet 连接。
  • passkeyBehavior 'none' | 'both' | 'only-existing' | 'only-new' (default: true) — 定义在认证过程中如何处理 Passkey。
  • provider 'wallet' | 'auth0' | '' (default: wallet) — 指定认证提供者。
  • qrcodeSize number (default: 160) — 二维码的尺寸（以像素为单位）。
  • showDownload boolean (default: true) — 如果为 true，则显示 DID Wallet 的下载链接。
  • webWalletUrl string (default: https://web.abtwallet.io) — 基于 Web 的 DID Wallet 的 URL。
  • enabledConnectTypes Array<'web' | 'mobile' | 'auth0' | 'github' | 'apple' | 'google' | 'passkey'> (default: ["web", "mobile", "github", "apple", "google", "auth0", "passkey"]) — 在 UI 中启用的连接方法数组。
  • extraContent any — 在连接模态框内渲染的自定义内容。
  • loadingEle any — 要显示的自定义加载元素。
  • disableSwitchApp boolean (default: false) — 如果为 true，则禁用移动设备上的自动应用切换。
  • hideCloseButton boolean (default: false) — 如果为 true，则隐藏模态框中的关闭按钮。
  • options object (default: {}) — 附加配置选项。
    • showQuickConnect boolean (default: true) — 如果为 true，则显示已保存会话的快速连接选项。
  • onRecreateSession Function — 会话重新创建时执行的回调函数。
  • checkFn () => boolean — 用于检查连接状态的自定义函数。
  • onSuccess (result: object) => void — 连接成功时执行的回调函数。
  • onError (error: any) => void — 发生错误时执行的回调函数。
  • onClose Function — 连接模态框关闭时执行的回调函数。

ConnectMessages

用于自定义 DID Connect UI 中显示的文本的对象。

  • title string (required) — 连接模态框的主标题。
  • scan string (required) — 扫描二维码的说明文本。
  • success ReactNode (required) — 成功连接后显示的消息或组件。
  • confirm string — 提示用户在钱包中确认操作的文本。
  • error string — 要显示的自定义错误消息。

OpenDidConnect

此函数类型定义了用于打开具有高级要求的 DID Connect 流程的签名，通常用于渐进式授权。

  • params ConnectProps (required) — 标准连接属性。
  • options object — 用于控制连接模式和指定要求的附加选项。
    • openMode 'redirect' | 'window' | 'popup' (default: popup) — 决定 DID Connect 窗口的打开方式。
    • requirements object — 指定会话的要求。
      • login boolean (default: true) — 如果为 true，则要求用户已登录。
      • bindWallet boolean (default: true) — 如果为 true，则要求用户已绑定 DID Wallet 账户。
      • bindDidSpaces false | 'read' | 'full' (default: false) — 指定是否需要绑定 DID Spaces，以及需要何种级别的访问权限。
    • baseUrl string — API 请求的基础 URL。
    • locale BaseLocale — UI 的语言 ('en' 或 'zh')。

会话和用户类型

这些类型定义了由 SessionProvider 管理的用户和会话数据的结构。

SessionProps

主会话对象，可通过 useSession 钩子访问。它包含用户状态、会话信息以及管理会话的方法。

  • action string — 当前正在执行的操作（例如 'login'）。
  • error string — 会话管理期间发生的任何错误消息。
  • initialized boolean — 如果会话已初始化，则为 True。
  • loading boolean — 如果会话当前处于加载状态，则为 True。
  • open boolean — 如果 DID Connect 模态框当前已打开，则为 True。
  • walletOS WalletOS — 已连接钱包的操作系统 ('web', 'android', 'ios')。
  • user User — 已认证的用户对象。如果没有用户登录，则为 Undefined。
  • locale UserLocale — 用户的当前区域设置。
  • provider WalletProvider — 当前会话使用的提供者。
  • baseUrl string — 用于 API 调用的基础 URL。
  • federatedMaster object — 关于统一登录站点群中主站点的信息。
  • login LoginSessionFn — 用于启动登录过程的函数。
  • logout LogoutSessionFn — 用于注销用户的函数。
  • switch Function — 用于在不同用户账户之间切换的函数。
  • switchDid CommonSessionFn — 用于切换用户活动 DID 的函数。
  • autoSwitchDid Function — 用于自动切换 DID 的函数。
  • switchProfile CommonSessionFn — 用于切换用户个人资料的函数。
  • switchPassport CommonSessionFn — 用于在不同通行证之间切换的函数。
  • bindWallet CommonSessionFn — 用于启动钱包绑定过程的函数。
  • refresh Function — 用于手动刷新会话数据的函数。
  • updateConnectedInfo (data: object) => void — 用于更新连接信息的函数。
  • openDidConnect OpenDidConnect — 用于打开具有高级要求的 DID Connect 模态框的函数。
  • useOAuth Function — 用于 OAuth 集成的钩子。
  • OAuthProvider Function — 用于 OAuth 上下文的提供者组件。
  • OAuthConsumer Function — 用于 OAuth 上下文的消费者组件。
  • OAuthContext object — 用于 OAuth 的 React 上下文对象。
  • usePasskey Function — 用于 Passkey 集成的钩子。
  • PasskeyProvider Function — 用于 Passkey 上下文的提供者组件。
  • PasskeyConsumer Function — 用于 Passkey 上下文的消费者组件。
  • PasskeyContext object — 用于 Passkey 的 React 上下文对象。
  • useDid (options: { session: Session }) => void — 一个用于处理 DID 信息的实用钩子。
  • WrapDid Function — 一个与 DID 功能相关的包装器组件。
  • getUserSessions () => Promise<UserSession[]> — 用于获取当前用户所有活动会话的函数。

User

表示已认证用户的详细个人资料。

  • did string (required) — 用户的去中心化标识符 (DID)。
  • pk string (required) — 用户的公钥。
  • avatar string (required) — 用户头像的 URL。
  • fullName string (required) — 用户的全名。
  • email string (required) — 用户的电子邮件地址。
  • role UserRole (required) — 用户在应用程序中的角色（例如 'guest', 'member', 'admin'）。
  • locale UserLocale (required) — 用户的首选语言。
  • connectedAccounts ConnectAccount[] (required) — 连接到用户 DID 的账户列表。
  • passports Passport[] (required) — 与用户关联的通行证列表。
  • permissions any[] (required) — 授予用户的权限列表。
  • didSpace object — 关于用户 DID Space 的信息。
  • approved boolean (required) — 指示用户是否已被批准。
  • remark string — 关于用户的可选备注或注释。
  • createdAt string (required) — 用户账户创建时的时间戳。
  • updatedAt string (required) — 用户账户最后更新的时间戳。
  • firstLoginAt string — 用户首次登录的时间戳。
  • lastLoginAt string — 用户最后一次登录的时间戳。
  • lastLoginIp string — 用户最后一次登录的 IP 地址。

UserSession

表示用户的单个活动会话，通常从 getUserSessions 中检索。

  • id string (required) — 会话的唯一标识符。
  • appName string (required) — 此会话的应用程序名称。
  • appPid string (required) — 应用程序的通行证 ID。
  • updatedAt string (required) — 上次会话更新的时间戳。
  • userDid string (required) — 此会话用户的 DID。
  • visitorId string (required) — 与会话关联的访客 ID。
  • extra object (required) — 与会话关联的任何额外数据。
  • user SessionUser (required) — 会话的简化用户对象。
  • passportId string — 此会话使用的通行证 ID。

核心数据类型

这些是跨各种其他接口使用的基本字符串联合类型。

类型描述可能的值
WalletProvider标识认证方法或提供者。wallet, auth0, apple, github, google, passkey
WalletOS表示 DID Wallet 的操作系统。web, android, ios, '' (空字符串)
UserRole定义用户在应用程序中的角色。guest, member, admin, owner, 或任何 string
BaseLocale支持的基础语言集。en, zh
UserLocale用户的区域设置，可以是基础区域设置或更具体的设置。en, zh, 或任何 string (例如 'en-US')