@arcblock/did-connect-react 3.1.40 → 3.1.42

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

@@ -0,0 +1,213 @@
+# Connection UI (DidConnect)
+
+The `DidConnect` component is a pre-built, comprehensive UI solution for handling various decentralized identity (DID) connection flows. It provides a user-friendly interface for actions like login, authentication, and profile requests, supporting multiple connection methods out-of-the-box.
+
+It serves as the visual centerpiece of the `@arcblock/did-connect-react` library, abstracting away the complexity of session management and real-time status updates. The component displays a QR code for DID Wallet users and offers alternative login options such as social logins (OAuth) and passwordless authentication (Passkeys).
+
+Before using `DidConnect`, ensure you have wrapped your application with the [`SessionProvider`](./core-components-session-provider.md) to manage the overall session state.
+
+## Basic Usage
+
+To use `DidConnect`, you need to import it and provide a few essential props. The component is typically controlled by a state variable that determines its visibility.
+
+```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;
+```
+
+In this example, clicking the "Login with DID" button sets the `isConnectOpen` state to `true`, which renders the `DidConnect` component as a modal dialog. The `checkFn` prop is crucial, as it's the function the component uses to poll for the session status from your backend.
+
+## How It Works
+
+The `DidConnect` component orchestrates the entire user authentication flow, from displaying connection options to handling the final success or error state.
+
+```d2
+direction: down
+
+User: { 
+  shape: c4-person 
+}
+
+Application: {
+  label: "React Application"
+  shape: rectangle
+
+  Login-Button: {
+    label: "Login Button"
+  }
+
+  DidConnect-UI: {
+    label: "DidConnect Component"
+    shape: rectangle
+
+    QR-Code: {
+      label: "QR Code"
+    }
+
+    Login-Methods: {
+      label: "Other Login Methods\n(OAuth, Passkey)"
+    }
+  }
+}
+
+Backend: {
+  label: "Backend Server"
+  shape: rectangle
+}
+
+DID-Wallet: {
+  label: "DID Wallet"
+  icon: "https://www.arcblock.io/image-bin/uploads/37198ddc4a0b9e91e5c1c821ab895a34.svg"
+}
+
+User -> Application.Login-Button: "1. Clicks Login"
+Application.Login-Button -> Application.DidConnect-UI: "2. Renders UI"
+Application.DidConnect-UI -> Backend: "3. Creates session, starts polling via checkFn"
+User -> DID-Wallet: "4a. Scans QR Code"
+DID-Wallet -> Backend: "5. Sends approval"
+User -> Application.DidConnect-UI.Login-Methods: "4b. Clicks OAuth/Passkey"
+Application.DidConnect-UI.Login-Methods -> Backend: "5. Authenticates"
+Backend -> Application.DidConnect-UI: "6. Returns success status"
+Application.DidConnect-UI -> User: "7. Calls onSuccess & closes UI"
+
+```
+
+## Component Props
+
+The `DidConnect` component is highly configurable through its props. Below is a detailed list of the available options.
+
+### Core Configuration
+
+These props are essential for setting up the component's basic functionality.
+
+<x-field-group>
+  <x-field data-name="action" data-type="string" data-required="true">
+    <x-field-desc markdown>Defines the purpose of the connection, such as `login`, `claim`, `sign`, etc. This string is passed to your backend to determine the required actions.</x-field-desc>
+  </x-field>
+  <x-field data-name="checkFn" data-type="function" data-required="true">
+    <x-field-desc markdown>The function used to poll the backend for session status updates. It should be a function that makes an API request, like `axios.get`.</x-field-desc>
+  </x-field>
+  <x-field data-name="baseUrl" data-type="string" data-default="''">
+    <x-field-desc markdown>The base URL for the API endpoints. If your API is on a different domain, specify it here.</x-field-desc>
+  </x-field>
+  <x-field data-name="prefix" data-type="string" data-default="/api/did">
+    <x-field-desc markdown>The URL prefix for the DID Connect API endpoints on your backend.</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### Behavior Control
+
+These props control how the connection process behaves.
+
+<x-field-group>
+  <x-field data-name="enabledConnectTypes" data-type="string[]" data-default='["web", "mobile", ...]'>
+    <x-field-desc markdown>An array of strings specifying which connection methods to display. Possible values include `web`, `mobile`, `github`, `google`, `apple`, `passkey`, etc.</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>Controls the behavior of Passkey authentication. `none` disables it, `both` allows creating new passkeys and using existing ones, `only-existing` restricts to existing passkeys, and `only-new` forces new passkey creation.</x-field-desc>
+  </x-field>
+  <x-field data-name="allowWallet" data-type="boolean" data-default="true">
+    <x-field-desc markdown>If `false`, the QR code and mobile wallet connection options will be hidden.</x-field-desc>
+  </x-field>
+  <x-field data-name="autoConnect" data-type="boolean" data-default="true">
+    <x-field-desc markdown>If `true`, the component will automatically try to use a previously established connection from the same device.</x-field-desc>
+  </x-field>
+  <x-field data-name="forceConnected" data-type="boolean | string" data-default="true">
+    <x-field-desc markdown>If `true`, a user must connect with the same DID they are already logged in with. If a DID string is provided, the user must connect with that specific DID.</x-field-desc>
+  </x-field>
+  <x-field data-name="saveConnect" data-type="boolean" data-default="true">
+    <x-field-desc markdown>If `true`, the successful connection information is saved locally for future `autoConnect` attempts.</x-field-desc>
+  </x-field>
+  <x-field data-name="useSocket" data-type="boolean" data-default="true">
+    <x-field-desc markdown>If `true`, attempts to use a WebSocket for real-time status updates, falling back to polling if a connection cannot be established.</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### UI Customization
+
+Customize the appearance and text of the `DidConnect` component.
+
+<x-field-group>
+  <x-field data-name="mode" data-type="'dialog' | 'drawer' | 'page'" data-default="'dialog'">
+    <x-field-desc markdown>Determines how the component is displayed. `dialog` shows it as a centered modal, `drawer` as a bottom sheet (on mobile), and `page` embeds it directly into the document flow.</x-field-desc>
+  </x-field>
+  <x-field data-name="messages" data-type="object">
+    <x-field-desc markdown>An object to customize the text displayed in the UI.</x-field-desc>
+    <x-field data-name="title" data-type="string" data-desc="The main title at the top."></x-field>
+    <x-field data-name="scan" data-type="string" data-desc="The instructional text below the title."></x-field>
+    <x-field data-name="confirm" data-type="string" data-desc="Text shown after the QR code is scanned."></x-field>
+    <x-field data-name="success" data-type="string | ReactNode" data-desc="Message displayed upon successful connection."></x-field>
+    <x-field data-name="error" data-type="string" data-desc="Message displayed on error."></x-field>
+  </x-field>
+  <x-field data-name="hideCloseButton" data-type="boolean" data-default="false">
+    <x-field-desc markdown>If `true`, the close button (X) in the top-right corner is hidden.</x-field-desc>
+  </x-field>
+  <x-field data-name="extraContent" data-type="ReactNode" data-default="null">
+    <x-field-desc markdown>Allows you to inject a custom React component or element into the UI, typically appearing below the main title/description.</x-field-desc>
+  </x-field>
+  <x-field data-name="customItems" data-type="ReactNode[]" data-default="[]">
+    <x-field-desc markdown>An array of custom React nodes to be added to the list of connection methods.</x-field-desc>
+  </x-field>
+  <x-field data-name="disableSwitchApp" data-type="boolean" data-default="false">
+    <x-field-desc markdown>If you are using Federated Login, this prop prevents users from switching between different applications in the group during the login process.</x-field-desc>
+  </x-field>
+  <x-field data-name="webWalletUrl" data-type="string">
+    <x-field-desc markdown>The URL of the web-based DID Wallet to be used for the "Connect with Web Wallet" option. Defaults to the official ArcBlock web wallet.</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### Callbacks
+
+Functions that are called at different stages of the connection lifecycle.
+
+<x-field-group>
+  <x-field data-name="onClose" data-type="function" data-required="true">
+    <x-field-desc markdown>Callback function that is executed when the user closes the `DidConnect` dialog (e.g., by clicking the close button or outside the modal).</x-field-desc>
+  </x-field>
+  <x-field data-name="onSuccess" data-type="function" data-required="true">
+    <x-field-desc markdown>Callback function that is executed upon a successful connection. The session data is passed as an argument.</x-field-desc>
+  </x-field>
+  <x-field data-name="onError" data-type="function">
+    <x-field-desc markdown>Callback function that is executed when an error occurs during the process. The error object or message is passed as an argument.</x-field-desc>
+  </x-field>
+  <x-field data-name="onRecreateSession" data-type="function">
+    <x-field-desc markdown>A callback function that is invoked when the session needs to be reset, for example, after a timeout or when the user manually cancels and retries.</x-field-desc>
+  </x-field>
+</x-field-group>
+
+## Next Steps
+
+With a solid understanding of the `DidConnect` component, you can now build robust authentication experiences. For more programmatic control over the connection UI, explore the [`useConnect` hook](./hooks-use-connect.md), which allows you to open and close the `DidConnect` modal from anywhere in your application.

package/docs/core-components-did-connect.zh-TW.md

@@ -0,0 +1,214 @@
+# 連線 UI (DidConnect)
+
+`DidConnect` 元件是一個預先建置、全面的 UI 解決方案，用於處理各種去中心化身分 (DID) 連線流程。它為登入、驗證和個人資料請求等操作提供了一個使用者友善的介面，並支援多種開箱即用的連線方法。
+
+它是 `@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 = () => {
+    // 處理成功登入，例如，重新導向使用者
+    window.location.href = '/profile';
+  };
+
+  return (
+    <div>
+      <button onClick={() => setConnectOpen(true)}>使用 DID 登入</button>
+      {isConnectOpen && (
+        <DidConnect
+          action="login"
+          checkFn={axios.get}
+          onClose={handleClose}
+          onSuccess={handleSuccess}
+          messages={{
+            title: '掃描以登入',
+            scan: '使用您的 DID Wallet 掃描 QR 碼',
+            confirm: '在您的 DID Wallet 上確認登入',
+            success: '您已成功登入！',
+          }}
+        />
+      )}
+    </div>
+  );
+}
+
+export default App;
+```
+
+在此範例中，點擊「使用 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>用於輪詢後端以獲取會話狀態更新的函式。它應該是一個發出 API 請求的函式，例如 `axios.get`。</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` 允許建立新的 passkey 並使用現有的，`only-existing` 限制為使用現有的 passkey，而 `only-new` 強制建立新的 passkey。</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 進行連線。</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>用於「使用網頁錢包連線」選項的網頁版 DID Wallet 的 URL。預設為官方的 ArcBlock 網頁錢包。</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` hook](./hooks-use-connect.md)，它允許您從應用程式的任何地方開啟和關閉 `DidConnect` 強制回應視窗。

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

@@ -0,0 +1,213 @@
+# 连接 UI (DidConnect)
+
+`DidConnect` 组件是一个预构建的、全面的 UI 解决方案，用于处理各种去中心化身份（DID）连接流程。它为登录、身份验证和个人资料请求等操作提供了用户友好的界面，并开箱即用地支持多种连接方法。
+
+它作为 `@arcblock/did-connect-react` 库的视觉核心，抽象了会话管理和实时状态更新的复杂性。该组件显示一个供 DID 钱包用户使用的二维码，并提供其他登录选项，如社交登录（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 = () => {
+    // 处理成功登录，例如，重定向用户
+    window.location.href = '/profile';
+  };
+
+  return (
+    <div>
+      <button onClick={() => setConnectOpen(true)}>使用 DID 登录</button>
+      {isConnectOpen && (
+        <DidConnect
+          action="login"
+          checkFn={axios.get}
+          onClose={handleClose}
+          onSuccess={handleSuccess}
+          messages={{
+            title: '扫描以登录',
+            scan: '使用您的 DID 钱包扫描二维码',
+            confirm: '在您的 DID 钱包上确认登录',
+            success: '您已成功登录！',
+          }}
+        />
+      )}
+    </div>
+  );
+}
+
+export default App;
+```
+
+在此示例中，单击“使用 DID 登录”按钮会将 `isConnectOpen` 状态设置为 `true`，这会将 `DidConnect` 组件渲染为模态对话框。`checkFn` 属性至关重要，因为它是组件用来从您的后端轮询会话状态的函数。
+
+## 工作原理
+
+`DidConnect` 组件协调整个用户身份验证流程，从显示连接选项到处理最终的成功或错误状态。
+
+```d2
+direction: down
+
+User: { 
+  shape: c4-person 
+}
+
+Application: {
+  label: "React Application"
+  shape: rectangle
+
+  Login-Button: {
+    label: "Login Button"
+  }
+
+  DidConnect-UI: {
+    label: "DidConnect Component"
+    shape: rectangle
+
+    QR-Code: {
+      label: "QR Code"
+    }
+
+    Login-Methods: {
+      label: "Other Login Methods\n(OAuth, Passkey)"
+    }
+  }
+}
+
+Backend: {
+  label: "Backend Server"
+  shape: rectangle
+}
+
+DID-Wallet: {
+  label: "DID Wallet"
+  icon: "https://www.arcblock.io/image-bin/uploads/37198ddc4a0b9e91e5c1c821ab895a34.svg"
+}
+
+User -> Application.Login-Button: "1. Clicks Login"
+Application.Login-Button -> Application.DidConnect-UI: "2. Renders UI"
+Application.DidConnect-UI -> Backend: "3. Creates session, starts polling via checkFn"
+User -> DID-Wallet: "4a. Scans QR Code"
+DID-Wallet -> Backend: "5. Sends approval"
+User -> Application.DidConnect-UI.Login-Methods: "4b. Clicks OAuth/Passkey"
+Application.DidConnect-UI.Login-Methods -> Backend: "5. Authenticates"
+Backend -> Application.DidConnect-UI: "6. Returns success status"
+Application.DidConnect-UI -> User: "7. Calls onSuccess & closes UI"
+
+```
+
+## 组件属性
+
+`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>用于向后端轮询会话状态更新的函数。它应该是一个发出 API 请求的函数，例如 `axios.get`。</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`，二维码和移动钱包连接选项将被隐藏。</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 进行连接。</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="扫描二维码后显示的文本。"></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>如果您正在使用统一登录站点群，此属性可防止用户在登录过程中在站点群中的不同应用程序之间切换。</x-field-desc>
+  </x-field>
+  <x-field data-name="webWalletUrl" data-type="string">
+    <x-field-desc markdown>用于“使用网页钱包连接”选项的基于 Web 的 DID 钱包的 URL。默认为官方的 ArcBlock 网页钱包。</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` 模态框。