@arcblock/did-connect-react 3.1.40 → 3.1.42

package/docs/api-reference.zh-TW.md

@@ -0,0 +1,178 @@
+# 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，則使用 WebSockets 進行即時狀態更新。"></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="定義在驗證過程中如何處理通行密鑰（Passkeys）。"></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="QR code 的大小（以像素為單位）。"></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="網頁版 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="掃描 QR code 的說明文字。"></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>
+
+### 核心資料類型
+
+這些是在各種其他介面中使用的基本字串聯合類型。
+
+| Type | Description | Possible Values |
+| --- | --- | --- |
+| `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'） |

package/docs/api-reference.zh.md

@@ -0,0 +1,178 @@
+# 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') |

package/docs/core-components-did-connect.ja.md

@@ -0,0 +1,214 @@
+# 接続UI (DidConnect)
+
+`DidConnect`コンポーネントは、さまざまな分散型アイデンティティ（DID）接続フローを処理するための、事前に構築された包括的なUIソリューションです。ログイン、認証、プロファイル要求などのアクションに対応したユーザーフレンドリーなインターフェースを提供し、複数の接続方法を標準でサポートしています。
+
+このコンポーネントは`@arcblock/did-connect-react`ライブラリの視覚的な中心的存在として機能し、セッション管理とリアルタイムのステータス更新の複雑さを抽象化します。コンポーネントはDID Walletユーザー向けのQRコードを表示し、ソーシャルログイン（OAuth）やパスワードレス認証（Passkeys）などの代替ログインオプションを提供します。
+
+`DidConnect`を使用する前に、アプリケーションが[`SessionProvider`](./core-components-session-provider.md)でラップされ、全体のセッション状態が管理されていることを確認してください。
+
+## 基本的な使用方法
+
+`DidConnect`を使用するには、コンポーネントをインポートし、いくつかの必須propsを指定する必要があります。通常、コンポーネントの表示・非表示は状態変数によって制御されます。
+
+```jsx DID Connect Example icon=logos:react
+import React, { useState } from 'react';
+import axios from 'axios';
+import DidConnect from '@arcblock/did-connect-react/lib/Connect';
+
+function App() {
+  const [isConnectOpen, setConnectOpen] = useState(false);
+
+  const handleClose = () => setConnectOpen(false);
+  const handleSuccess = () => {
+    // Handle successful login, e.g., redirect the user
+    window.location.href = '/profile';
+  };
+
+  return (
+    <div>
+      <button onClick={() => setConnectOpen(true)}>Login with DID</button>
+      {isConnectOpen && (
+        <DidConnect
+          action="login"
+          checkFn={axios.get}
+          onClose={handleClose}
+          onSuccess={handleSuccess}
+          messages={{
+            title: 'Scan to Sign In',
+            scan: 'Scan QR code with your DID Wallet',
+            confirm: 'Confirm login on your DID Wallet',
+            success: 'You have successfully signed in!',
+          }}
+        />
+      )}
+    </div>
+  );
+}
+
+export default App;
+```
+
+この例では、「Login with DID」ボタンをクリックすると`isConnectOpen`ステートが`true`に設定され、`DidConnect`コンポーネントがモーダルダイアログとしてレンダリングされます。`checkFn` propは非常に重要で、コンポーネントがバックエンドからセッションステータスをポーリングするために使用する関数です。
+
+## 仕組み
+
+`DidConnect`コンポーネントは、接続オプションの表示から最終的な成功またはエラー状態の処理まで、ユーザー認証フロー全体を統括します。
+
+```d2
+direction: down
+
+User: {
+  label: "ユーザー"
+  shape: c4-person
+}
+
+Application: {
+  label: "Reactアプリケーション"
+  shape: rectangle
+
+  Login-Button: {
+    label: "ログインボタン"
+  }
+
+  DidConnect-UI: {
+    label: "DidConnectコンポーネント"
+    shape: rectangle
+
+    QR-Code: {
+      label: "QRコード"
+    }
+
+    Login-Methods: {
+      label: "その他のログイン方法\n(OAuth, Passkey)"
+    }
+  }
+}
+
+Backend: {
+  label: "バックエンドサーバー"
+  shape: rectangle
+}
+
+DID-Wallet: {
+  label: "DID Wallet"
+  icon: "https://www.arcblock.io/image-bin/uploads/37198ddc4a0b9e91e5c1c821ab895a34.svg"
+}
+
+User -> Application.Login-Button: "1. ログインをクリック"
+Application.Login-Button -> Application.DidConnect-UI: "2. UIをレンダリング"
+Application.DidConnect-UI -> Backend: "3. セッションを作成し、checkFn経由でポーリングを開始"
+User -> DID-Wallet: "4a. QRコードをスキャン"
+DID-Wallet -> Backend: "5. 承認を送信"
+User -> Application.DidConnect-UI.Login-Methods: "4b. OAuth/Passkeyをクリック"
+Application.DidConnect-UI.Login-Methods -> Backend: "5. 認証"
+Backend -> Application.DidConnect-UI: "6. 成功ステータスを返す"
+Application.DidConnect-UI -> User: "7. onSuccessを呼び出し、UIを閉じる"
+
+```
+
+## コンポーネントのProps
+
+`DidConnect`コンポーネントは、propsを通じて高度な設定が可能です。以下に、利用可能なオプションの詳細なリストを示します。
+
+### コア設定
+
+これらのpropsは、コンポーネントの基本機能を設定するために不可欠です。
+
+<x-field-group>
+  <x-field data-name="action" data-type="string" data-required="true">
+    <x-field-desc markdown>接続の目的を定義します（例：`login`、`claim`、`sign`など）。この文字列はバックエンドに渡され、必要なアクションを決定するために使用されます。</x-field-desc>
+  </x-field>
+  <x-field data-name="checkFn" data-type="function" data-required="true">
+    <x-field-desc markdown>バックエンドにセッションステータスの更新をポーリングするために使用される関数です。`axios.get`のようにAPIリクエストを行う関数である必要があります。</x-field-desc>
+  </x-field>
+  <x-field data-name="baseUrl" data-type="string" data-default="''">
+    <x-field-desc markdown>APIエンドポイントのベースURLです。APIが別のドメインにある場合は、ここで指定します。</x-field-desc>
+  </x-field>
+  <x-field data-name="prefix" data-type="string" data-default="/api/did">
+    <x-field-desc markdown>バックエンドのDID Connect APIエンドポイントのURLプレフィックスです。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### 動作制御
+
+これらのpropsは、接続プロセスの動作を制御します。
+
+<x-field-group>
+  <x-field data-name="enabledConnectTypes" data-type="string[]" data-default='["web", "mobile", ...]'>
+    <x-field-desc markdown>表示する接続方法を指定する文字列の配列です。設定可能な値には、`web`、`mobile`、`github`、`google`、`apple`、`passkey`などがあります。</x-field-desc>
+  </x-field>
+  <x-field data-name="passkeyBehavior" data-type="'none' | 'both' | 'only-existing' | 'only-new'" data-default="'none'">
+    <x-field-desc markdown>Passkey認証の動作を制御します。`none`は無効化、`both`は新しいパスキーの作成と既存のパスキーの使用を許可、`only-existing`は既存のパスキーに制限、`only-new`は新しいパスキーの作成を強制します。</x-field-desc>
+  </x-field>
+  <x-field data-name="allowWallet" data-type="boolean" data-default="true">
+    <x-field-desc markdown>`false`の場合、QRコードとモバイルウォレットの接続オプションが非表示になります。</x-field-desc>
+  </x-field>
+  <x-field data-name="autoConnect" data-type="boolean" data-default="true">
+    <x-field-desc markdown>`true`の場合、コンポーネントは同じデバイスから以前に確立された接続を自動的に使用しようとします。</x-field-desc>
+  </x-field>
+  <x-field data-name="forceConnected" data-type="boolean | string" data-default="true">
+    <x-field-desc markdown>`true`の場合、ユーザーはすでにログインしているDIDと同じDIDで接続する必要があります。DID文字列が指定された場合は、その特定のDIDで接続する必要があります。</x-field-desc>
+  </x-field>
+  <x-field data-name="saveConnect" data-type="boolean" data-default="true">
+    <x-field-desc markdown>`true`の場合、成功した接続情報が将来の`autoConnect`のためにローカルに保存されます。</x-field-desc>
+  </x-field>
+  <x-field data-name="useSocket" data-type="boolean" data-default="true">
+    <x-field-desc markdown>`true`の場合、リアルタイムのステータス更新にWebSocketの使用を試み、接続が確立できない場合はポーリングにフォールバックします。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### UIのカスタマイズ
+
+`DidConnect`コンポーネントの外観とテキストをカスタマイズします。
+
+<x-field-group>
+  <x-field data-name="mode" data-type="'dialog' | 'drawer' | 'page'" data-default="'dialog'">
+    <x-field-desc markdown>コンポーネントの表示方法を決定します。`dialog`は中央に配置されたモーダルとして、`drawer`はボトムシートとして（モバイルの場合）、`page`はドキュメントフローに直接埋め込みます。</x-field-desc>
+  </x-field>
+  <x-field data-name="messages" data-type="object">
+    <x-field-desc markdown>UIに表示されるテキストをカスタマイズするためのオブジェクトです。</x-field-desc>
+    <x-field data-name="title" data-type="string" data-desc="上部にあるメインタイトルです。"></x-field>
+    <x-field data-name="scan" data-type="string" data-desc="タイトルの下にある説明文です。"></x-field>
+    <x-field data-name="confirm" data-type="string" data-desc="QRコードがスキャンされた後に表示されるテキストです。"></x-field>
+    <x-field data-name="success" data-type="string | ReactNode" data-desc="接続が成功したときに表示されるメッセージです。"></x-field>
+    <x-field data-name="error" data-type="string" data-desc="エラー時に表示されるメッセージです。"></x-field>
+  </x-field>
+  <x-field data-name="hideCloseButton" data-type="boolean" data-default="false">
+    <x-field-desc markdown>`true`の場合、右上隅の閉じるボタン（X）が非表示になります。</x-field-desc>
+  </x-field>
+  <x-field data-name="extraContent" data-type="ReactNode" data-default="null">
+    <x-field-desc markdown>カスタムのReactコンポーネントや要素をUIに挿入できます。通常はメインタイトル/説明の下に表示されます。</x-field-desc>
+  </x-field>
+  <x-field data-name="customItems" data-type="ReactNode[]" data-default="[]">
+    <x-field-desc markdown>接続方法のリストに追加するカスタムReactノードの配列です。</x-field-desc>
+  </x-field>
+  <x-field data-name="disableSwitchApp" data-type="boolean" data-default="false">
+    <x-field-desc markdown>フェデレーションログインを使用している場合、このpropはログインプロセス中にユーザーがグループ内の異なるアプリケーションを切り替えるのを防ぎます。</x-field-desc>
+  </x-field>
+  <x-field data-name="webWalletUrl" data-type="string">
+    <x-field-desc markdown>「Webウォレットで接続」オプションで使用するWebベースのDID WalletのURLです。デフォルトは公式のArcBlock Webウォレットです。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### コールバック
+
+接続ライフサイクルのさまざまな段階で呼び出される関数です。
+
+<x-field-group>
+  <x-field data-name="onClose" data-type="function" data-required="true">
+    <x-field-desc markdown>ユーザーが`DidConnect`ダイアログを閉じたとき（例：閉じるボタンをクリックしたり、モーダルの外側をクリックしたりした場合）に実行されるコールバック関数です。</x-field-desc>
+  </x-field>
+  <x-field data-name="onSuccess" data-type="function" data-required="true">
+    <x-field-desc markdown>接続が成功したときに実行されるコールバック関数です。セッションデータが引数として渡されます。</x-field-desc>
+  </x-field>
+  <x-field data-name="onError" data-type="function">
+    <x-field-desc markdown>プロセス中にエラーが発生したときに実行されるコールバック関数です。エラーオブジェクトまたはメッセージが引数として渡されます。</x-field-desc>
+  </x-field>
+  <x-field data-name="onRecreateSession" data-type="function">
+    <x-field-desc markdown>タイムアウト後やユーザーが手動でキャンセルして再試行した場合など、セッションをリセットする必要があるときに呼び出されるコールバック関数です。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+## 次のステップ
+
+`DidConnect`コンポーネントを十分に理解することで、堅牢な認証体験を構築できるようになります。接続UIをよりプログラム的に制御したい場合は、[`useConnect`フック](./hooks-use-connect.md)を参照してください。これを使用すると、アプリケーションのどこからでも`DidConnect`モーダルを開閉できます。