Skip to main content

Get User List

v1.1.23+

User API allows you to get the user list under your current tenant.

Version Requirement

This feature is supported from SDK v1.1.23 onwards.

API Signature​

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

⚠️ Note: client.api.user.getList() does not support pagination. By default, this method returns all users matching the conditions under the current tenant at once, but to prevent returning too much data at once, the SDK will return at most 1000 records (i.e., "full" but with a limit).

Return Type Example​

(Actual types are subject to SDK source code)

type User = {
  code: string; // User unique code
  userName: string; // System username
  nickName?: string | null;
  mobile: string;
  email?: string | null;
  avatar?: string | null;
};

Quick Start​

The following example demonstrates how to safely call user.getList() in a project:

const users = await client.api.user.getList();
console.log(`Returned ${users.length} users`);

// Note: The SDK has already handled request exceptions internally. When an exception occurs, client.api.user.getList() will return an empty array ([]) as a fallback result.

Usage Examples​

Get Only Nickname and Username (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 Single User (Get Full Data First Then Filter)​

The following example demonstrates first getting the full user list (up to 1000 records) under the current tenant via client.api.user.getList(), then filtering on the client side to get a single user (matching by username or other fields). Note this is in-memory filtering, suitable for small data volumes or dropdown scenarios; if the user volume is large, please use server-side pagination/filtering interfaces instead.

// First get the list (SDK internally does short-term caching and exception fallback)
const users = await client.api.user.getList();

// Use filter to get matching users, then take the first one (returns null if not found)
const matches = users.filter((u) => u.userName === "alice");
// Or filter by user code: users.filter(u => u.code === "user-001")

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

Notes and Best Practices​

  • Return Result Range: This method will return all users under the current tenant by default, but will limit the number of returned records (up to 1000). Therefore, it is recommended to use only in small-scale lists or one-time loading scenarios (such as dropdown selectors). When the tenant has a large user volume or needs to traverse all users completely, please use filter(), server-side pagination interfaces, or batch loading strategies to avoid performance and memory issues.
  • Error Handling: The SDK will catch request exceptions internally and return an empty array ([]) as a safe fallback result when an error occurs. Callers can directly use the returned empty array as a fallback strategy; if you need to distinguish error causes, report, or implement specific retry logic.
  • Caching Behavior: Short-term caching of the list to improve performance. Since user information changes infrequently, the SDK internally defaults to short-term caching of list data, with a cache duration of 30 seconds, to improve performance while maintaining timeliness.

Common Questions​

Does the returned data contain sensitive information?​

The returned fields are regular display fields (username, nickname, avatar, etc.) and will not contain passwords or security credentials.

Last updated: 2025-12-01