# API 参考

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

## 连接类型

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

### ConnectProps

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

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

### ConnectMessages

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

<x-field-group>
  <x-field data-name="title" data-type="string" data-required="true" data-desc="连接模态框的主标题。"></x-field>
  <x-field data-name="scan" data-type="string" data-required="true" data-desc="扫描二维码的说明文本。"></x-field>
  <x-field data-name="success" data-type="ReactNode" data-required="true" data-desc="成功连接后显示的消息或组件。"></x-field>
  <x-field data-name="confirm" data-type="string" data-required="false" data-desc="提示用户在钱包中确认操作的文本。"></x-field>
  <x-field data-name="error" data-type="string" data-required="false" data-desc="要显示的自定义错误消息。"></x-field>
</x-field-group>

### OpenDidConnect

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

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

## 会话和用户类型

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

### SessionProps

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

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

### User

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

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

### UserSession

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

<x-field-group>
  <x-field data-name="id" data-type="string" data-required="true" data-desc="会话的唯一标识符。"></x-field>
  <x-field data-name="appName" data-type="string" data-required="true" data-desc="此会话的应用程序名称。"></x-field>
  <x-field data-name="appPid" data-type="string" data-required="true" data-desc="应用程序的通行证 ID。"></x-field>
  <x-field data-name="updatedAt" data-type="string" data-required="true" data-desc="上次会话更新的时间戳。"></x-field>
  <x-field data-name="userDid" data-type="string" data-required="true" data-desc="此会话用户的 DID。"></x-field>
  <x-field data-name="visitorId" data-type="string" data-required="true" data-desc="与会话关联的访客 ID。"></x-field>
  <x-field data-name="extra" data-type="object" data-required="true" data-desc="与会话关联的任何额外数据。"></x-field>
  <x-field data-name="user" data-type="SessionUser" data-required="true" data-desc="会话的简化用户对象。"></x-field>
  <x-field data-name="passportId" data-type="string" data-required="false" data-desc="此会话使用的通行证 ID。"></x-field>
</x-field-group>

### 核心数据类型

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

| 类型 | 描述 | 可能的值 |
| --- | --- | --- |
| `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') |
