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

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

# UserSessions

`UserSessions` 组件渲染一个全面的数据表格，用于显示和管理用户的登录会话。它清晰地概览了用户在各种设备上的所有活跃、已过期和离线会话，让用户能够控制其账户安全。

该组件被设计成一个即插即用的解决方案，供需要实现会话管理功能的开发者使用。它负责处理数据获取、分页、UI 渲染以及登出特定会话等操作。

## 功能

- **会话筛选：** 用户可以轻松按状态（`online`、`expired` 或 `offline`）筛选会话。
- **详细信息：** 每个会话条目都会显示解析后的 user-agent 数据，包括操作系统、设备类型（浏览器）和钱包操作系统。
- **IP 地理位置：** 根据上次登录的 IP 地址自动解析并显示地理区域。
- **会话终止：** 允许用户终止除当前会话之外的任何会话。
- **批量操作：** 包含“全部登出”功能，可终止特定状态下的所有会話。
- **响应式设计：** 适应不同屏幕尺寸，确保在桌面和移动设备上提供一致的用户体验。

## 工作原理

`UserSessions` 组件通过调用开发者提供的函数来请求会话数据。这种设计将组件与任何特定的后端实现解耦，从而提供了更大的灵活性。

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

## 用法

要使用 `UserSessions` 组件，您必须提供一个 `user` 对象和一个 `getUserSessions` 函数。`getUserSessions` 函数负责从您的后端服务获取会话数据。

```javascript Integration Example icon=lucide:code
import { UserSessions } from '@arcblock/blocklet-ui-react';
import { client } from './libs/client'; // 您的 API 客户端实例

// 正在显示其会话的用户对象。
const currentUser = {
  did: 'z1...',
  name: 'Alice',
  // other user properties
};

/**
 * 此函数从您的后端获取会话数据。
 * 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>控制“应用 Pid”列的可见性，该列可以显示与会话关联的 Blocklet 的程序 ID。</x-field-desc>
  </x-field>
</x-field-group>

## 显示信息

该组件在数据表格中为每个会话渲染以下信息：

| 列 | 描述 |
| :--- | :--- |
| **平台** | 从会话的 user-agent 字符串派生的操作系统和版本（例如 `Windows/10`）。 |
| **设备类型** | 用于会话的浏览器或应用程序（例如 `Chrome/108.0.0`）。 |
| **钱包操作系统** | 连接的 DID 钱包的操作系统（如果可用）。 |
| **应用 Pid** | 创建会话的 Blocklet 的程序 ID。（`showAppPid` 为 `true` 时可见）。 |
| **用户** | 与会话关联的用户。（`showUser` 为 `true` 时可见）。 |
| **创建于** | 会话最初创建时的时间戳。 |
| **上次活跃** | 上次活动的时间戳。对于已过期的会话，此列显示“已过期”。 |
| **上次登录 IP** | 会话的最后已知 IP 地址及其解析的地理区域。 |
| **操作** | 提供一个用于登出该会话的按钮。（`showAction` 为 `true` 时可见）。 |

---

要获得完整的用户管理界面，请考虑在 [UserCenter](./components-user-management-user-center.md) 组件中使用 `UserSessions` 组件。