---

列出用戶

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 參數在構建用戶選擇界面時非常有用
• 訪問級別：項目用戶列表包括在公司列表中不可用的角色信息

相關操作

• 用戶管理概述 - 用戶管理操作
• 移除用戶 - 從項目中移除用戶
• 自定義角色 - 管理用戶權限