---

Getting the User List

v1.1.23+

The User API returns the list of users in your current tenant.

ℹ️ Version requirement This feature requires SDK v1.1.23 or later.

API Signature

client.api.user.getList(): Promise<User[]>

⚠️ Note: client.api.user.getList() does not support pagination. By default it returns the matching users in your current tenant in one shot, but to prevent oversized responses, the SDK caps the result at 1000 records — the "full" list, with an upper bound.

Return Type Example

(The authoritative type is the SDK source code.)

type User = {
  code: string; // 用户唯一编码
  userName: string; // 系统用户名
  nickName?: string | null;
  mobile: string;
  email?: string | null;
  avatar?: string | null;
};

Quick Start

The example below shows how to call user.getList() safely in your project:

const users = await client.api.user.getList();
console.log(`返回 ${users.length} 个用户`);

// 注意：SDK 在内部已经对请求异常做了处理。在出现异常时，client.api.user.getList() 会返回空数组（[]）作为降级结果。

Usage Examples

Get nicknames and usernames only (quick mapping)

const users = await client.api.user.getList();
const mapped = users
  .filter((u) => !!u.nickName)
  .map((u) => ({ username: u.userName, nickName: u.nickName }));

console.log(mapped);

Get a single user (fetch the full list, then filter)

The example below fetches the full user list for the current tenant (up to 1000 records) with client.api.user.getList(), then filters for a single user on the client side (matching by username or another field). Note that this is in-memory filtering — suitable for small datasets or dropdown scenarios. For larger user bases, switch to a server-side paginated/filtered API.

// 先获取列表（SDK 内部会做短期缓存与异常降级）
const users = await client.api.user.getList();

// 使用 filter 获取匹配的用户，然后取第一个（返回 null 表示未找到）
const matches = users.filter((u) => u.userName === "alice");
// 或者按用户编码筛选： users.filter(u => u.code === "user-001")

const user = matches.length ? matches[0] : null;
console.log(user);

Notes and Best Practices

• Scope of results: this method returns all users in the current tenant by default, but caps the record count (at most 1000). Use it only for small lists or one-shot loads such as dropdown pickers. When your tenant has many users or you need to walk every user, switch to filter(), a server-side paginated API, or a batched loading strategy to avoid performance and memory issues.
• Error handling: the SDK catches request errors internally and returns an empty array ([]) as a safe fallback. Callers can simply treat the empty array as the fallback strategy; if you need to distinguish error causes, report them, or implement specific retry logic.
• Caching: the list is cached briefly to improve performance. Since user information changes infrequently, the SDK caches the list data for 30 seconds by default — a balance between freshness and performance.

FAQ

Does the response contain sensitive information?

The returned fields are regular display fields (username, nickname, avatar, etc.) — no passwords or security credentials.

Related Documentation

• Quick start

---

Last updated: 2025-12-01