---

列出用户

Blue 提供多种查询，以在不同范围内列出用户 - 公司范围、项目特定或单个用户查找。这些查询支持分页、过滤和排序，以有效管理大型用户基础。

基本示例 - 公司用户

列出公司中的所有用户：

query ListCompanyUsers {
  companyUserList(companyId: "acme-corp") {
    users {
      id
      email
      fullName
      jobTitle
      lastActiveAt
    }
    pageInfo {
      totalItems
      hasNextPage
    }
  }
}

高级示例 - 过滤的项目用户

列出项目用户，支持搜索和分页：

query ListProjectUsers {
  projectUserList(
    projectId: "web-redesign"
    search: "engineer"
    first: 20
    orderBy: lastActiveAt_DESC
  ) {
    edges {
      node {
        id
        email
        fullName
        accessLevel
        customRole {
          id
          name
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

可用查询

companyUserList

列出公司中的所有用户，支持可选过滤。

输入参数

参数	类型	必需	描述
companyId	String!	✅ 是	公司 ID 或别名
notInProjectId	String	否	排除已在此项目中的用户
search	String	否	按名称或电子邮件搜索
first	Int	否	返回的结果数量（前向分页）
after	String	否	前向分页的游标
last	Int	否	返回的结果数量（后向分页）
before	String	否	后向分页的游标
skip	Int	否	跳过的结果数量
orderBy	UserOrderByInput	否	排序顺序（见下文）

projectUserList

列出特定项目中的所有用户。

输入参数

参数	类型	必需	描述
projectId	String!	✅ 是	项目 ID 或别名
search	String	否	按名称或电子邮件搜索
first	Int	否	结果数量（最大：200）
after	String	否	分页游标
orderBy	UserOrderByInput	否	排序顺序

user

通过 ID 检索单个用户。

输入参数

参数	类型	必需	描述
id	String!	✅ 是	用户 ID

排序选项

UserOrderByInput 值

值	描述
createdAt_ASC	按注册日期排序（最早的在前）
createdAt_DESC	按注册日期排序（最新的在前）
lastActiveAt_ASC	按最后活动排序（最早的在前）
lastActiveAt_DESC	按最后活动排序（最新的在前）
firstName_ASC	按名字排序（A-Z）
firstName_DESC	按名字排序（Z-A）
lastName_ASC	按姓氏排序（A-Z）
lastName_DESC	按姓氏排序（Z-A）
email_ASC	按电子邮件地址排序（A-Z）
email_DESC	按电子邮件地址排序（Z-A）
username_ASC	按用户名排序（A-Z）
username_DESC	按用户名排序（Z-A）
jobTitle_ASC	按职位名称排序（A-Z）
jobTitle_DESC	按职位名称排序（Z-A）

响应字段

用户对象

字段	类型	描述
id	String!	唯一用户标识符
uid	String!	Firebase 认证 UID
username	String!	用户选择的用户名
email	String!	电子邮件地址（仅对拥有者/管理员可见）
firstName	String	名字
lastName	String	姓氏
fullName	String	名字和姓氏的组合
jobTitle	String	职业头衔
phoneNumber	String	联系电话
dateOfBirth	DateTime	出生日期
isEmailVerified	Boolean!	电子邮件验证状态
lastActiveAt	DateTime	最后活动时间戳
createdAt	DateTime!	账户创建日期
updatedAt	DateTime!	最后个人资料更新
isOnline	Boolean!	当前在线状态
timezone	String	用户的时区
locale	String	语言偏好
theme	JSON	UI 主题偏好
image	Image	个人资料图片对象

项目用户附加字段

列出项目用户时，提供附加字段：

字段	类型	描述
accessLevel	UserAccessLevel!	用户在项目中的角色
customRole	ProjectUserRole	自定义角色详细信息（如适用）
joinedAt	DateTime!	用户加入项目的时间

分页信息

字段	类型	描述
totalItems	Int!	用户总数
totalPages	Int	总页数（用于偏移分页）
page	Int	当前页码
perPage	Int	每页项目数
hasNextPage	Boolean!	还有更多结果可用
hasPreviousPage	Boolean!	之前的结果可用
startCursor	String	第一个项目游标
endCursor	String	最后一个项目游标

所需权限

查询	所需权限
companyUserList	Any authenticated user in the company
projectUserList	Any project member (including VIEW_ONLY)
user	Any authenticated user

错误响应

公司未找到

{
  "errors": [{
    "message": "Company not found",
    "extensions": {
      "code": "COMPANY_NOT_FOUND"
    }
  }]
}

项目未找到

{
  "errors": [{
    "message": "Project not found",
    "extensions": {
      "code": "PROJECT_NOT_FOUND"
    }
  }]
}

未授权访问

{
  "errors": [{
    "message": "You don't have access to this resource",
    "extensions": {
      "code": "UNAUTHORIZED"
    }
  }]
}

重要说明

• 性能：对于大型用户列表使用分页（每个请求最多 200 个用户）
• 搜索：在名字、姓氏和电子邮件字段中搜索
• 电子邮件隐私：电子邮件地址仅对拥有者或管理员访问级别的用户可见
• 在线状态： isOnline 通过 WebSocket 连接实时更新
• 个人资料图片：使用 image.variants 字段获取不同尺寸
• 过滤：在构建用户选择界面时，notInProjectId 参数非常有用
• 访问级别：项目用户列表包含公司列表中不可用的角色信息

相关操作

• 用户管理概述 - 用户管理操作
• 移除用户 - 从项目中移除用户
• 自定义角色 - 管理用户权限