@blocklet/ui-react/docs/components-user-management-user-sessions.zh-TW.md

Some useful front-end web components that can be used in Blocklets.

# UserSessions

`UserSessions` 元件會渲染一個全面的資料表，用於顯示和管理使用者的登入會話。它清晰地概覽了所有在各種裝置上的活躍、過期和離線會話，讓使用者能夠掌控其帳戶安全。

此元件被設計為一個隨插即用的解決方案，供需要實作會話管理功能的開發人員使用。它處理資料擷取、分頁、UI 渲染以及登出特定會話等操作。

## 功能

- **會話篩選：** 使用者可以輕鬆地按會話狀態篩選：`online`、`expired` 或 `offline`。
- **詳細資訊：** 每個會話條目都會顯示解析後的使用者代理資料，包括作業系統、裝置類型（瀏覽器）和錢包作業系統。
- **IP 地理位置：** 根據上次登入的 IP 位址自動解析並顯示地理區域。
- **終止會話：** 允許使用者終止除了當前會話以外的任何會話。
- **批次操作：** 包含「全部登出」功能，以終止特定狀態下的所有會話。
- **響應式設計：** 適應不同螢幕尺寸，確保在桌面和行動裝置上擁有一致的使用者體驗。

## 運作方式

`UserSessions` 元件透過向開發人員提供的函式請求會話資料來運作。這種設計將元件與任何特定的後端實作解耦，提供了更大的靈活性。

<!-- DIAGRAM_IMAGE_START:sequence:16:9:1765962229 -->
![UserSessions](assets/diagram/user-sessions-diagram-0.zh-TW.jpg)
<!-- DIAGRAM_IMAGE_END -->

## 使用方式

要使用 `UserSessions` 元件，您必須提供一個 `user` 物件和一個 `getUserSessions` 函式。`getUserSessions` 函式負責從您的後端服務中擷取會話資料。

```javascript 整合範例 icon=lucide:code
import { UserSessions } from '@arcblock/blocklet-ui-react';
import { client } from './libs/client'; // 您的 API 客戶端實例

// 正在顯示其會話的使用者物件。
const currentUser = {
  did: 'z1...',
  name: 'Alice',
  // 其他使用者屬性
};

/**
 * 此函式從您的後端擷取會話資料。
 * 每當需要新資料時，UserSessions 元件將會呼叫此函式。
 *
 * @param {object} params - 查詢參數。
 * @param {number} params.page - 當前頁碼。
 * @param {number} params.pageSize - 每頁的項目數。
 * @param {string} params.status - 用於篩選的會話狀態（'online'、'expired'、'offline'）。
 * @returns {Promise<{ list: UserSession[], paging: { total: number } }>} 一個解析為會話資料的 promise。
 */
const fetchUserSessions = async ({ page, pageSize, status }) => {
  const response = await client.user.getSessions({
    page,
    pageSize,
    status,
  });

  // 確保回傳格式符合元件的要求
  return {
    list: response?.list || [],
    paging: {
      total: response?.paging?.total || 0,
    },
  };
};

export default function MyAccountSessionsPage() {
  return (
    <div>
      <h2>管理您的登入會話</h2>
      <UserSessions
        user={currentUser}
        getUserSessions={fetchUserSessions}
      />
    </div>
  );
}
```

## 屬性

`UserSessions` 元件接受以下屬性以自訂其行為和外觀。

<x-field-group>
  <x-field data-name="user" data-type="User" data-required="true">
    <x-field-desc markdown>正在顯示其會話的使用者物件。元件需要此物件來為會話列表提供上下文。</x-field-desc>
  </x-field>
  <x-field data-name="getUserSessions" data-type="function" data-required="true">
    <x-field-desc markdown>一個非同步函式，負責從您的後端擷取分頁的會話資料。它會接收一個包含 `page`、`pageSize` 和 `status` 的物件，並且必須回傳一個解析為 `{ list: UserSession[], paging: { total: number } }` 形狀物件的 `Promise`。</x-field-desc>
  </x-field>
  <x-field data-name="showAction" data-type="boolean" data-default="true" data-required="false">
    <x-field-desc markdown>控制「操作」欄位的可見性，該欄位包含登出按鈕。設定為 `false` 可建立唯讀視圖。</x-field-desc>
  </x-field>
  <x-field data-name="showUser" data-type="boolean" data-default="true" data-required="false">
    <x-field-desc markdown>控制「使用者」欄位的可見性。這在多使用者或管理情境中很有用，因為在這些情境下需要識別每個會話的使用者。</x-field-desc>
  </x-field>
  <x-field data-name="showOffline" data-type="boolean" data-default="false" data-required="false">
    <x-field-desc markdown>決定「離線」篩選選項是否在 UI 中可用。離線會話通常代表目前不活躍的長期會話。</x-field-desc>
  </x-field>
  <x-field data-name="showAppPid" data-type="boolean" data-default="false" data-required="false">
    <x-field-desc markdown>控制「App Pid」欄位的可見性，該欄位可以顯示與會話關聯的 Blocklet 的程式 ID。</x-field-desc>
  </x-field>
</x-field-group>

## 顯示資訊

此元件在資料表中為每個會話渲染以下資訊：

| 欄位 | 說明 |
| :--- | :--- |
| **Platform** | 從會話的使用者代理字串中解析出的作業系統和版本（例如 `Windows/10`）。 |
| **Device Type** | 用於此會話的瀏覽器或應用程式（例如 `Chrome/108.0.0`）。 |
| **Wallet OS** | 已連接的 DID 錢包的作業系統（如果有的話）。 |
| **App Pid** | 建立此會話的 Blocklet 的程式 ID。（如果 `showAppPid` 為 `true` 則可見）。 |
| **User** | 與此會話關聯的使用者。（如果 `showUser` 為 `true` 則可見）。 |
| **Created At** | 會話最初建立的時間戳。 |
| **Last Active** | 上次活動的時間戳。對於已過期的會話，此欄位顯示「已過期」。 |
| **Last Login IP** | 此會話的最後已知 IP 位址，及其解析出的地理區域。 |
| **Actions** | 提供一個登出此會話的按鈕。（如果 `showAction` 為 `true` 則可見）。 |

---

若要獲得一個完整的使用者管理介面，請考慮在 [UserCenter](./components-user-management-user-center.md) 元件中使用 `UserSessions` 元件。