@arcblock/did-connect-react 3.1.40 → 3.1.42

package/docs/hooks-use-connect.zh.md

@@ -0,0 +1,214 @@
+# useConnect
+
+`useConnect` hook 提供了一种强大的、编程化的方式来打开、关闭和管理 `DidConnect` UI 模态框。当您需要比声明式的 `Button` 组件提供更多对连接流程的控制时，例如从自定义 UI 元素、菜单项或响应应用程序事件来触发模态框，它就是理想的解决方案。
+
+此 hook 是 `Button` 组件背后的引擎，让您可以直接访问相同的核心功能。
+
+## 工作原理
+
+`useConnect` hook 返回两个主要元素：
+
+1.  **`connectHolder`**：一个必须在组件树中渲染的 React 元素。此元素负责在 `DidConnect` 模态框被激活时进行渲染。在 `open` 函数被调用之前，它保持不可见。
+2.  **`connectApi`**：一个包含用于控制模态框生命周期的函数（`open`、`close`、`openPopup`、`loginOAuth`）的对象。
+
+```d2
+direction: down
+
+User: { 
+  shape: c4-person 
+}
+
+Your-App: {
+  label: "你的应用程序"
+  shape: rectangle
+
+  Custom-Button: {
+    label: "自定义按钮"
+  }
+
+  useConnect-Hook: {
+    label: "useConnect()"
+  }
+  
+  connectHolder: {
+    label: "connectHolder"
+  }
+}
+
+DID-Wallet: {
+  label: "DID Wallet"
+  icon: "https://www.arcblock.io/image-bin/uploads/37198ddc4a0b9e91e5c1c821ab895a34.svg"
+}
+
+User -> Your-App.Custom-Button: "1. 点击"
+Your-App.Custom-Button -> Your-App.useConnect-Hook: "2. 调用 connectApi.open()"
+Your-App.useConnect-Hook -> Your-App.connectHolder: "3. 激活模态框"
+Your-App.connectHolder -> User: "4. 显示 DidConnect UI"
+User -> DID-Wallet: "5. 扫描二维码并批准"
+DID-Wallet -> Your-App.connectHolder: "6. 发送响应"
+Your-App.connectHolder -> Your-App.useConnect-Hook: "7. 触发 onSuccess 回调"
+Your-App.useConnect-Hook -> Your-App.connectHolder: "8. 停用模态框"
+
+```
+
+## 设置
+
+要使用此 hook，请在您的组件中导入并调用它。然后，确保在您的应用程序中的某个位置渲染 `connectHolder`，最好是在顶层组件中，以确保模态框可以覆盖所有其他内容。
+
+```javascript Basic Setup icon=logos:javascript
+import React from 'react';
+import { useConnect } from '@arcblock/did-connect-react';
+
+function MyComponent() {
+  // 1. 初始化 hook
+  const { connectHolder, connectApi } = useConnect();
+
+  const handleLogin = () => {
+    // 2. 使用 API 打开模态框
+    connectApi.open({
+      action: 'login',
+      onSuccess: (result) => {
+        console.log('登录成功！', result);
+      },
+      onClose: () => {
+        console.log('模态框被用户关闭。');
+      }
+    });
+  };
+
+  return (
+    <div>
+      <button type="button" onClick={handleLogin}>
+        Login with DID
+      </button>
+
+      {/* 3. 渲染 holder 组件 */}
+      {connectHolder}
+    </div>
+  );
+}
+
+export default MyComponent;
+```
+
+## API 参考
+
+`connectApi` 对象提供了以下方法来控制连接过程。
+
+### `connectApi.open(options)`
+
+这是触发和显示 `DidConnect` 模态框的主要函数。它接受一个 `options` 对象，用于配置连接会话的行为、外观和回调。
+
+**参数 (`options`)**
+
+<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="onSuccess" data-type="(result: object) => void" data-required="false">
+    <x-field-desc markdown>当用户在钱包中成功完成操作时执行的回调函数。`result` 对象包含来自钱包的响应。</x-field-desc>
+  </x-field>
+  <x-field data-name="onClose" data-type="() => void" data-required="false">
+    <x-field-desc markdown>当用户在未完成操作的情况下手动关闭模态框时执行的回调函数。</x-field-desc>
+  </x-field>
+  <x-field data-name="onError" data-type="(error: any) => void" data-required="false">
+    <x-field-desc markdown>如果在过程中发生错误（例如超时或网络问题）时执行的回调函数。</x-field-desc>
+  </x-field>
+  <x-field data-name="messages" data-type="ConnectMessages" data-required="false">
+    <x-field-desc markdown>一个用于自定义模态框中显示文本的对象。有关详细信息，请参阅 `ConnectMessages` 类型。</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="ReactNode" data-desc="成功屏幕的内容。"></x-field>
+  </x-field>
+  <x-field data-name="popup" data-type="boolean" data-default="true">
+    <x-field-desc markdown>如果为 `true`，UI 将作为模态对话框显示。如果为 `false`，它将内联渲染，需要设置 `containerEl`。</x-field-desc>
+  </x-field>
+  <x-field data-name="containerEl" data-type="Element" data-required="false">
+    <x-field-desc markdown>当 `popup` 设置为 `false` 时，`DidConnect` 组件将在此 DOM 元素中渲染。</x-field-desc>
+  </x-field>
+  <x-field data-name="closeTimeout" data-type="number" data-default="2000">
+    <x-field-desc markdown>成功连接后，模态框自动关闭前的延迟时间（以毫秒为单位）。</x-field-desc>
+  </x-field>
+  <x-field data-name="checkInterval" data-type="number" data-default="2000">
+    <x-field-desc markdown>轮询服务器以检查会话状态的间隔时间（以毫秒为单位）。</x-field-desc>
+  </x-field>
+  <x-field data-name="checkTimeout" data-type="number" data-default="300000">
+    <x-field-desc markdown>连接尝试超时的总时间（以毫秒为单位）。</x-field-desc>
+  </x-field>
+  <x-field data-name="extraParams" data-type="object" data-default="{}">
+    <x-field-desc markdown>要包含在会话创建请求中的任何额外参数，这些参数可以在服务器端检索。</x-field-desc>
+  </x-field>
+</x-field-group>
+
+### `connectApi.close()`
+
+手动关闭 `DidConnect` 模态框。模态框在成功或用户取消时会自动关闭，但如果需要因其他原因以编程方式关闭它，可以调用此函数。
+
+```javascript icon=lucide:x-circle
+// 示例：在成功回调中短暂延迟后关闭模态框
+connectApi.open({
+  action: 'login',
+  onSuccess: () => {
+    showTemporarySuccessMessage();
+    setTimeout(() => {
+      connectApi.close();
+    }, 1500);
+  },
+  closeTimeout: 999999 // 防止自动关闭
+});
+```
+
+### `connectApi.openPopup(params, options)`
+
+此函数提供了一种替代的连接方法，它会在新的浏览器弹出窗口中打开 DID Connect 流程，而不是在当前页面内打开模态框。这对于某些类似 OAuth 的流程或在无法注入模态框的网站上进行集成时非常有用。
+
+**参数**
+
+<x-field-group>
+  <x-field data-name="params" data-type="ConnectProps" data-required="true">
+    <x-field-desc markdown>与 `open` 方法的选项类似。一个关键区别是，`params.extraParams.provider` 是**必需的**，用于标识认证方法（例如 'github'、'google'）。</x-field-desc>
+  </x-field>
+  <x-field data-name="options" data-type="object" data-required="false">
+    <x-field-desc markdown>弹出窗口本身的配置。</x-field-desc>
+    <x-field data-name="baseUrl" data-type="string" data-desc="用于构建弹出窗口 URL 的基础 URL。"></x-field>
+    <x-field data-name="locale" data-type="string" data-default="en" data-desc="弹出窗口内容的区域设置。"></x-field>
+    <x-field data-name="popupOptions" data-type="object" data-desc="直接传递给 `window.open()` 的选项，用于自定义弹出窗口的大小和功能。"></x-field>
+  </x-field>
+</x-field-group>
+
+**用法**
+
+`openPopup` 函数返回一个 `Promise`，它在成功时解析为认证数据，在失败或取消时拒绝。
+
+```javascript icon=lucide:external-link
+const handleGithubLogin = async () => {
+  try {
+    const result = await connectApi.openPopup({
+      action: 'login',
+      onSuccess: () => console.log('此回调也会被触发'),
+      extraParams: { provider: 'github' } // 这是必需的
+    });
+    console.log('通过弹出窗口登录成功：', result);
+  } catch (err) {
+    if (err.message === 'Popup closed') {
+      console.log('用户关闭了弹出窗口。');
+    } else {
+      console.error('发生错误：', err);
+    }
+  }
+};
+```
+
+### `connectApi.loginOAuth(options)`
+
+这是一个辅助函数，用于直接启动 OAuth 登录流程。它是一个较低级别的实用工具，在库的其他部分内部使用。
+
+**参数 (`options`)**
+
+<x-field-group>
+  <x-field data-name="provider" data-type="string" data-required="true" data-desc="要使用的 OAuth 提供商，例如 'github'、'google'。"></x-field>
+  <x-field data-name="action" data-type="string" data-required="true" data-desc="操作，通常是 'login'。"></x-field>
+  <x-field data-name="extraParams" data-type="object" data-required="false" data-desc="OAuth 流程的附加参数。"></x-field>
+  <x-field data-name="onLogin" data-type="function" data-required="true" data-desc="成功登录后执行的回调函数。"></x-field>
+</x-field-group>

package/docs/hooks-use-did.ja.md

@@ -0,0 +1,107 @@
+# useDid
+
+`useDid`フックは、`session.user`オブジェクトから特定のDID関連情報を簡単に抽出して操作するための便利なユーティリティです。手動での処理なしに、永続DID、ウォレット情報、接続済みアカウントなどの一般的に必要なデータを取得するためにユーザーオブジェクトの解析を簡素化します。
+
+このフックは、セッションコンテキストにアクセスできるように、`SessionProvider`の子であるコンポーネント内で使用する必要があります。
+
+## 使用方法
+
+このフックを使用するには、`useSession`と一緒にインポートします。`useSession`を呼び出して現在のセッション状態を取得し、その`session`オブジェクトを`useDid`に渡します。
+
+```javascript Basic Usage icon=logos:react
+import { useSession } from '@arcblock/did-connect-react';
+import { useDid } from '@arcblock/did-connect-react/lib/User';
+
+function UserProfile() {
+  const { session } = useSession();
+  const {
+    did,
+    walletDid,
+    connectedDids,
+    sourceProvider,
+    connectedAccounts,
+  } = useDid({ session });
+
+  if (!session.user) {
+    return <p>DID情報を表示するにはログインしてください。</p>;
+  }
+
+  return (
+    <div>
+      <h2>ユーザーDID情報</h2>
+      <p><strong>永続DID:</strong> {did}</p>
+      <p><strong>ウォレットDID:</strong> {walletDid || 'N/A'}</p>
+      <p><strong>ログイン方法:</strong> {sourceProvider}</p>
+      <h3>接続済みアカウント ({connectedAccounts.length})</h3>
+      <ul>
+        {connectedAccounts.map((account) => (
+          <li key={account.did}>
+            {account.provider}: {account.did}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+## パラメータ
+
+`useDid`フックは、単一のオブジェクトをパラメータとして受け取ります。
+
+<x-field data-name="options" data-type="object" data-required="true">
+  <x-field data-name="session" data-type="object" data-required="true" data-desc="`useSession`フックから取得したセッションオブジェクト。このフックは`session.user`が存在する場合にのみデータを計算します。">
+    <x-field data-name="user" data-type="object" data-required="false" data-desc="ログイン成功後にセッションコンテキストによって提供されるユーザーオブジェクト。"></x-field>
+  </x-field>
+</x-field>
+
+## 戻り値
+
+このフックは、派生したさまざまなDID情報を含む状態オブジェクトを返します。このオブジェクトは、`session.user`オブジェクトが変更されるたびに更新されます。
+
+<x-field-group>
+  <x-field data-name="did" data-type="string" data-desc="ユーザーの永続DID。これは`permanentDid`のエイリアスです。"></x-field>
+  <x-field data-name="wallet" data-type="object" data-desc="プロバイダーが'wallet'である接続済みアカウントオブジェクト。ウォレットが接続されていない場合は`undefined`を返します。">
+      <x-field data-name="did" data-type="string" data-desc="ウォレットアカウントのDID。"></x-field>
+      <x-field data-name="provider" data-type="string" data-desc="プロバイダー名。'wallet'になります。"></x-field>
+  </x-field>
+  <x-field data-name="walletDid" data-type="string" data-desc="ユーザーの接続済みウォレットのDID。ウォレットが接続されていない場合は`undefined`を返します。"></x-field>
+  <x-field data-name="permanentDid" data-type="string" data-desc="ユーザーの永続DIDで、`user.did`からのプライマリ識別子です。"></x-field>
+  <x-field data-name="connectedDids" data-type="string[]" data-desc="ユーザーの接続済みアカウントのすべてのDIDを含む配列。"></x-field>
+  <x-field data-name="connectedAccounts" data-type="object[]" data-desc="接続済みアカウントオブジェクトの完全な配列。">
+    <x-field data-name="did" data-type="string" data-desc="接続済みアカウントのDID。"></x-field>
+    <x-field data-name="provider" data-type="string" data-desc="アカウントのプロバイダー（例：'wallet'、'github'）。"></x-field>
+  </x-field>
+  <x-field data-name="sourceProvider" data-type="string" data-desc="ユーザーが最初にログインに使用したプロバイダー（例：'wallet'、'github'）。デフォルトは'wallet'です。"></x-field>
+  <x-field data-name="sourceProviders" data-type="string[]" data-desc="ユーザーの接続済みアカウントのすべてのプロバイダー名の配列。"></x-field>
+</x-field-group>
+
+## スタンドアロンのヘルパー関数
+
+`useDid`フックは、エクスポートされた一連のヘルパー関数に基づいて構築されています。フックのリアクティブな状態管理が不要で、単にユーザーオブジェクトから特定の情報を抽出したい場合は、これらの関数を直接インポートして使用できます。
+
+| Function                 | Description                                                  |
+| ------------------------ | ------------------------------------------------------------ |
+| `getPermanentDid(user)`  | ユーザーオブジェクトから永続DIDを抽出します。             |
+| `getWalletDid(user)`     | 接続済みウォレットのDIDを抽出します。                    |
+| `getConnectedAccounts(user)` | 接続済みアカウントの配列を取得します。                 |
+| `getConnectedDids(user)`   | すべての接続済みアカウントからDIDの配列を取得します。      |
+| `getSourceProvider(user)`  | 初回ログインに使用されたプロバイダーを取得します。                |
+| `getSourceProviders(user)` | 接続されているすべてのプロバイダー名の配列を取得します。               |
+| `getWallet(user)`        | 完全なウォレットアカウントオブジェクトを検索して返します。        |
+
+### 例：ヘルパー関数の使用
+
+```javascript Direct Function Usage icon=logos:javascript
+import { getWalletDid } from '@arcblock/did-connect-react/lib/User/use-did';
+import { useSession } from '@arcblock/did-connect-react';
+
+// このアプローチは、イベントハンドラーやその他の非React関数内で役立ちます
+function handleUserAction() {
+  const { session } = useSession();
+  if (session.user) {
+    const walletDid = getWalletDid(session.user);
+    console.log('ユーザーのウォレットDID:', walletDid);
+  }
+}
+```

package/docs/hooks-use-did.md

@@ -0,0 +1,107 @@
+# useDid
+
+The `useDid` hook is a convenient utility for easily extracting and working with specific DID-related information from the `session.user` object. It simplifies parsing the user object to get commonly needed data like the permanent DID, wallet information, and connected accounts without manual processing.
+
+This hook should be used within a component that is a child of the `SessionProvider` to ensure it has access to the session context.
+
+## How to Use
+
+To use the hook, import it along with `useSession`. Call `useSession` to get the current session state, and then pass the `session` object to `useDid`.
+
+```javascript Basic Usage icon=logos:react
+import { useSession } from '@arcblock/did-connect-react';
+import { useDid } from '@arcblock/did-connect-react/lib/User';
+
+function UserProfile() {
+  const { session } = useSession();
+  const {
+    did,
+    walletDid,
+    connectedDids,
+    sourceProvider,
+    connectedAccounts,
+  } = useDid({ session });
+
+  if (!session.user) {
+    return <p>Please log in to view your DID information.</p>;
+  }
+
+  return (
+    <div>
+      <h2>User DID Information</h2>
+      <p><strong>Permanent DID:</strong> {did}</p>
+      <p><strong>Wallet DID:</strong> {walletDid || 'N/A'}</p>
+      <p><strong>Login Method:</strong> {sourceProvider}</p>
+      <h3>Connected Accounts ({connectedAccounts.length})</h3>
+      <ul>
+        {connectedAccounts.map((account) => (
+          <li key={account.did}>
+            {account.provider}: {account.did}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+## Parameters
+
+The `useDid` hook accepts a single object as its parameter.
+
+<x-field data-name="options" data-type="object" data-required="true">
+  <x-field data-name="session" data-type="object" data-required="true" data-desc="The session object obtained from the `useSession` hook. The hook will only compute data when `session.user` is present.">
+    <x-field data-name="user" data-type="object" data-required="false" data-desc="The user object provided by the session context after a successful login."></x-field>
+  </x-field>
+</x-field>
+
+## Return Value
+
+The hook returns a state object containing various pieces of derived DID information. This object will be updated whenever the `session.user` object changes.
+
+<x-field-group>
+  <x-field data-name="did" data-type="string" data-desc="The user's permanent DID. This is an alias for `permanentDid`."></x-field>
+  <x-field data-name="wallet" data-type="object" data-desc="The connected account object where the provider is 'wallet'. Returns `undefined` if no wallet is connected.">
+      <x-field data-name="did" data-type="string" data-desc="The DID of the wallet account."></x-field>
+      <x-field data-name="provider" data-type="string" data-desc="The provider name, which will be 'wallet'."></x-field>
+  </x-field>
+  <x-field data-name="walletDid" data-type="string" data-desc="The DID of the user's connected wallet. Returns `undefined` if no wallet is connected."></x-field>
+  <x-field data-name="permanentDid" data-type="string" data-desc="The user's permanent DID, which is the primary identifier from `user.did`."></x-field>
+  <x-field data-name="connectedDids" data-type="string[]" data-desc="An array of all DIDs from the user's connected accounts."></x-field>
+  <x-field data-name="connectedAccounts" data-type="object[]" data-desc="The full array of connected account objects.">
+    <x-field data-name="did" data-type="string" data-desc="The DID of the connected account."></x-field>
+    <x-field data-name="provider" data-type="string" data-desc="The provider of the account (e.g., 'wallet', 'github')."></x-field>
+  </x-field>
+  <x-field data-name="sourceProvider" data-type="string" data-desc="The provider the user originally used to log in (e.g., 'wallet', 'github'). Defaults to 'wallet'."></x-field>
+  <x-field data-name="sourceProviders" data-type="string[]" data-desc="An array of all provider names from the user's connected accounts."></x-field>
+</x-field-group>
+
+## Standalone Helper Functions
+
+The `useDid` hook is built on a set of exported helper functions. If you don't need the reactive state management of a hook and just want to extract a specific piece of information from a user object, you can import and use these functions directly.
+
+| Function                 | Description                                                  |
+| ------------------------ | ------------------------------------------------------------ |
+| `getPermanentDid(user)`  | Extracts the permanent DID from the user object.             |
+| `getWalletDid(user)`     | Extracts the DID of the connected wallet.                    |
+| `getConnectedAccounts(user)` | Retrieves the array of connected accounts.                 |
+| `getConnectedDids(user)`   | Retrieves an array of DIDs from all connected accounts.      |
+| `getSourceProvider(user)`  | Gets the provider used for the initial login.                |
+| `getSourceProviders(user)` | Gets an array of all connected provider names.               |
+| `getWallet(user)`        | Finds and returns the complete wallet account object.        |
+
+### Example: Using a Helper Function
+
+```javascript Direct Function Usage icon=logos:javascript
+import { getWalletDid } from '@arcblock/did-connect-react/lib/User/use-did';
+import { useSession } from '@arcblock/did-connect-react';
+
+// This approach can be useful inside event handlers or other non-React functions
+function handleUserAction() {
+  const { session } = useSession();
+  if (session.user) {
+    const walletDid = getWalletDid(session.user);
+    console.log('User Wallet DID:', walletDid);
+  }
+}
+```

package/docs/hooks-use-did.zh-TW.md

@@ -0,0 +1,107 @@
+# useDid
+
+`useDid` hook 是一個方便的實用程式，可輕鬆地從 `session.user` 物件中提取和使用特定的 DID 相關資訊。它簡化了使用者物件的解析過程，無需手動處理即可獲取永久 DID、錢包資訊和已連接帳戶等常用資料。
+
+此 hook 應在 `SessionProvider` 的子元件中使用，以確保它能存取 session 上下文。
+
+## 如何使用
+
+若要使用此 hook，請將其與 `useSession` 一起匯入。呼叫 `useSession` 以取得目前的 session 狀態，然後將 `session` 物件傳遞給 `useDid`。
+
+```javascript Basic Usage icon=logos:react
+import { useSession } from '@arcblock/did-connect-react';
+import { useDid } from '@arcblock/did-connect-react/lib/User';
+
+function UserProfile() {
+  const { session } = useSession();
+  const {
+    did,
+    walletDid,
+    connectedDids,
+    sourceProvider,
+    connectedAccounts,
+  } = useDid({ session });
+
+  if (!session.user) {
+    return <p>請登入以查看您的 DID 資訊。</p>;
+  }
+
+  return (
+    <div>
+      <h2>使用者 DID 資訊</h2>
+      <p><strong>永久 DID：</strong> {did}</p>
+      <p><strong>錢包 DID：</strong> {walletDid || 'N/A'}</p>
+      <p><strong>登入方式：</strong> {sourceProvider}</p>
+      <h3>已連接的帳戶 ({connectedAccounts.length})</h3>
+      <ul>
+        {connectedAccounts.map((account) => (
+          <li key={account.did}>
+            {account.provider}: {account.did}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+## 參數
+
+`useDid` hook 接受一個物件作為其參數。
+
+<x-field data-name="options" data-type="object" data-required="true">
+  <x-field data-name="session" data-type="object" data-required="true" data-desc="從 `useSession` hook 取得的 session 物件。只有當 `session.user` 存在時，此 hook 才會計算資料。">
+    <x-field data-name="user" data-type="object" data-required="false" data-desc="成功登入後由 session 上下文提供的使用者物件。"></x-field>
+  </x-field>
+</x-field>
+
+## 傳回值
+
+此 hook 會傳回一個狀態物件，其中包含各種衍生的 DID 資訊。每當 `session.user` 物件變更時，此物件都會更新。
+
+<x-field-group>
+  <x-field data-name="did" data-type="string" data-desc="使用者的永久 DID。這是 `permanentDid` 的別名。"></x-field>
+  <x-field data-name="wallet" data-type="object" data-desc="提供者為 'wallet' 的已連接帳戶物件。如果沒有連接錢包，則傳回 `undefined`。">
+      <x-field data-name="did" data-type="string" data-desc="錢包帳戶的 DID。"></x-field>
+      <x-field data-name="provider" data-type="string" data-desc="提供者名稱，此處為 'wallet'。"></x-field>
+  </x-field>
+  <x-field data-name="walletDid" data-type="string" data-desc="使用者已連接錢包的 DID。如果沒有連接錢包，則傳回 `undefined`。"></x-field>
+  <x-field data-name="permanentDid" data-type="string" data-desc="使用者的永久 DID，即來自 `user.did` 的主要識別碼。"></x-field>
+  <x-field data-name="connectedDids" data-type="string[]" data-desc="一個包含使用者所有已連接帳戶 DID 的陣列。"></x-field>
+  <x-field data-name="connectedAccounts" data-type="object[]" data-desc="完整的已連接帳戶物件陣列。">
+    <x-field data-name="did" data-type="string" data-desc="已連接帳戶的 DID。"></x-field>
+    <x-field data-name="provider" data-type="string" data-desc="帳戶的提供者（例如 'wallet'、'github'）。"></x-field>
+  </x-field>
+  <x-field data-name="sourceProvider" data-type="string" data-desc="使用者最初用於登入的提供者（例如 'wallet'、'github'）。預設為 'wallet'。"></x-field>
+  <x-field data-name="sourceProviders" data-type="string[]" data-desc="一個包含使用者所有已連接帳戶提供者名稱的陣列。"></x-field>
+</x-field-group>
+
+## 獨立的輔助函數
+
+`useDid` hook 建立在一組匯出的輔助函數之上。如果您不需要 hook 的響應式狀態管理，而只想從使用者物件中提取特定資訊，可以直接匯入並使用這些函數。
+
+| Function                 | Description                                                  |
+| ------------------------ | ------------------------------------------------------------ |
+| `getPermanentDid(user)`  | 從使用者物件中提取永久 DID。             |
+| `getWalletDid(user)`     | 提取已連接錢包的 DID。                    |
+| `getConnectedAccounts(user)` | 擷取已連接帳戶的陣列。                 |
+| `getConnectedDids(user)`   | 擷取一個包含所有已連接帳戶 DID 的陣列。      |
+| `getSourceProvider(user)`  | 取得用於初始登入的提供者。                |
+| `getSourceProviders(user)` | 取得一個包含所有已連接提供者名稱的陣列。               |
+| `getWallet(user)`        | 尋找並傳回完整的錢包帳戶物件。        |
+
+### 範例：使用輔助函數
+
+```javascript Direct Function Usage icon=logos:javascript
+import { getWalletDid } from '@arcblock/did-connect-react/lib/User/use-did';
+import { useSession } from '@arcblock/did-connect-react';
+
+// 這種方法在事件處理常式或其他非 React 函數中可能很有用
+function handleUserAction() {
+  const { session } = useSession();
+  if (session.user) {
+    const walletDid = getWalletDid(session.user);
+    console.log('使用者錢包 DID：', walletDid);
+  }
+}
+```

package/docs/hooks-use-did.zh.md

@@ -0,0 +1,107 @@
+# useDid
+
+`useDid` Hook 是一个便捷的实用程序，可以轻松地从 `session.user` 对象中提取和使用特定的 DID 相关信息。它简化了用户对象的解析过程，无需手动处理即可获取永久 DID、钱包信息和已连接账户等常用数据。
+
+此 Hook 应在 `SessionProvider` 的子组件中使用，以确保其能够访问会话上下文。
+
+## 如何使用
+
+要使用此 Hook，请将其与 `useSession` 一起导入。调用 `useSession` 获取当前会话状态，然后将 `session` 对象传递给 `useDid`。
+
+```javascript Basic Usage icon=logos:react
+import { useSession } from '@arcblock/did-connect-react';
+import { useDid } from '@arcblock/did-connect-react/lib/User';
+
+function UserProfile() {
+  const { session } = useSession();
+  const {
+    did,
+    walletDid,
+    connectedDids,
+    sourceProvider,
+    connectedAccounts,
+  } = useDid({ session });
+
+  if (!session.user) {
+    return <p>请登录以查看您的 DID 信息。</p>;
+  }
+
+  return (
+    <div>
+      <h2>用户 DID 信息</h2>
+      <p><strong>永久 DID：</strong> {did}</p>
+      <p><strong>钱包 DID：</strong> {walletDid || 'N/A'}</p>
+      <p><strong>登录方法：</strong> {sourceProvider}</p>
+      <h3>已连接账户 ({connectedAccounts.length})</h3>
+      <ul>
+        {connectedAccounts.map((account) => (
+          <li key={account.did}>
+            {account.provider}: {account.did}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+## 参数
+
+`useDid` Hook 接受一个对象作为其唯一参数。
+
+<x-field data-name="options" data-type="object" data-required="true">
+  <x-field data-name="session" data-type="object" data-required="true" data-desc="从 `useSession` Hook 获取的会话对象。只有当 `session.user` 存在时，该 Hook 才会计算数据。">
+    <x-field data-name="user" data-type="object" data-required="false" data-desc="成功登录后由会话上下文提供的用户对象。"></x-field>
+  </x-field>
+</x-field>
+
+## 返回值
+
+该 Hook 返回一个状态对象，其中包含各种派生的 DID 信息。每当 `session.user` 对象发生变化时，此对象都会更新。
+
+<x-field-group>
+  <x-field data-name="did" data-type="string" data-desc="用户的永久 DID。这是 `permanentDid` 的别名。"></x-field>
+  <x-field data-name="wallet" data-type="object" data-desc="提供者为 'wallet' 的已连接账户对象。如果没有连接钱包，则返回 `undefined`。">
+      <x-field data-name="did" data-type="string" data-desc="钱包账户的 DID。"></x-field>
+      <x-field data-name="provider" data-type="string" data-desc="提供者名称，即 'wallet'。"></x-field>
+  </x-field>
+  <x-field data-name="walletDid" data-type="string" data-desc="用户已连接钱包的 DID。如果没有连接钱包，则返回 `undefined`。"></x-field>
+  <x-field data-name="permanentDid" data-type="string" data-desc="用户的永久 DID，即来自 `user.did` 的主标识符。"></x-field>
+  <x-field data-name="connectedDids" data-type="string[]" data-desc="一个包含用户所有已连接账户 DID 的数组。"></x-field>
+  <x-field data-name="connectedAccounts" data-type="object[]" data-desc="包含所有已连接账户对象的完整数组。">
+    <x-field data-name="did" data-type="string" data-desc="已连接账户的 DID。"></x-field>
+    <x-field data-name="provider" data-type="string" data-desc="账户的提供者（例如 'wallet'、'github'）。"></x-field>
+  </x-field>
+  <x-field data-name="sourceProvider" data-type="string" data-desc="用户最初用于登录的提供者（例如 'wallet'、'github'）。默认为 'wallet'。"></x-field>
+  <x-field data-name="sourceProviders" data-type="string[]" data-desc="一个包含用户所有已连接账户提供者名称的数组。"></x-field>
+</x-field-group>
+
+## 独立的辅助函数
+
+`useDid` Hook 构建在一组导出的辅助函数之上。如果您不需要 Hook 的响应式状态管理，而只想从用户对象中提取特定信息，则可以直接导入并使用这些函数。
+
+| Function                 | Description                                                  |
+| ------------------------ | ------------------------------------------------------------ |
+| `getPermanentDid(user)`  | 从用户对象中提取永久 DID。             |
+| `getWalletDid(user)`     | 提取已连接钱包的 DID。                    |
+| `getConnectedAccounts(user)` | 检索已连接账户的数组。                 |
+| `getConnectedDids(user)`   | 从所有已连接账户中检索一个 DID 数组。      |
+| `getSourceProvider(user)`  | 获取用于初始登录的提供者。                |
+| `getSourceProviders(user)` | 获取所有已连接提供者名称的数组。               |
+| `getWallet(user)`        | 查找并返回完整的钱包账户对象。        |
+
+### 示例：使用辅助函数
+
+```javascript Direct Function Usage icon=logos:javascript
+import { getWalletDid } from '@arcblock/did-connect-react/lib/User/use-did';
+import { useSession } from '@arcblock/did-connect-react';
+
+// 这种方法在事件处理程序或其他非 React 函数中可能很有用
+function handleUserAction() {
+  const { session } = useSession();
+  if (session.user) {
+    const walletDid = getWalletDid(session.user);
+    console.log('User Wallet DID:', walletDid);
+  }
+}
+```