---

列出所有项目

projectList 查询允许您以强大的过滤、排序和分页选项检索项目。

基本示例

query ProjectListQuery {
  projectList(filter: { companyIds: ["ENTER COMPANY ID"] }) {
    items {
      id
      uid
      slug
      name
      description
      archived
      color
      icon
      createdAt
      updatedAt
      allowNotification
      position
      unseenActivityCount
      todoListsMaxPosition
      lastAccessedAt
      isTemplate
      automationsCount
      totalFileCount
      totalFileSize
      todoAlias
    }
    pageInfo {
      totalPages
      totalItems
      page
      perPage
      hasNextPage
      hasPreviousPage
    }
  }
}

带过滤和排序的高级示例

query FilteredProjectList {
  projectList(
    filter: {
      companyIds: ["company-123", "company-456"]
      archived: false
      isTemplate: false
      search: "marketing"
      inProject: true
      folderId: null  # Get root-level projects only
    }
    sort: [position_ASC, name_ASC]
    skip: 0
    take: 50
  ) {
    items {
      id
      name
      slug
      position
      archived
    }
    totalCount
    pageInfo {
      totalItems
      hasNextPage
    }
  }
}

项目字段

下表描述了 ProjectListQuery 中每个项目的所有可用字段：

字段	类型	描述
id	ID!	项目的唯一标识符
uid	String!	用户友好的项目唯一标识符
slug	String!	项目的 URL 友好名称
name	String!	项目的显示名称
description	String	项目的简要描述
archived	Boolean	布尔值，指示项目是否已归档
color	String	与项目相关的颜色，用于视觉识别
icon	String	与项目相关的图标，用于视觉识别
image	Image	项目封面图像对象
createdAt	DateTime!	项目创建的时间戳
updatedAt	DateTime!	项目最后更新的时间戳
allowNotification	Boolean!	布尔值，指示项目是否启用通知
position	Float!	表示项目在列表中的位置的数值
unseenActivityCount	Int!	项目中未查看活动的数量
todoListsMaxPosition	Float!	项目中待办事项列表的最大位置信息
lastAccessedAt	DateTime	项目最后访问的时间戳
isTemplate	Boolean!	布尔值，指示项目是否为模板
isOfficialTemplate	Boolean!	布尔值，指示这是否是官方 Blue 模板
automationsCount(isActive: Boolean)	Int!	与项目相关的自动化数量
totalFileCount	Int	项目中的文件总数
totalFileSize	Float	项目中所有文件的总大小（以字节为单位）
todoAlias	String	项目中使用的“待办事项”的自定义别名
category	ProjectCategory!	项目类别（CRM、市场营销等）
hideEmailFromRoles	[UserAccessLevel!]	应该隐藏电子邮件地址的角色数组
hideStatusUpdate	Boolean	隐藏状态更新的布尔值
company	Company!	完整的公司对象详细信息
accessLevel(userId: String)	UserAccessLevel	获取用户在特定项目中的访问级别
folder	Folder	包含此项目的文件夹
features	[ProjectFeature!]	启用的项目功能数组
sequenceCustomField	CustomField	用于序列编号的自定义字段
coverConfig	TodoCoverConfig	待办事项封面图像的配置
hideRecordCount	Boolean	是否隐藏记录计数
showTimeSpentInTodoList	Boolean	是否显示待办事项列表中的花费时间
showTimeSpentInProject	Boolean	是否显示项目中的花费时间
todoFields	[TodoField]	自定义待办事项字段定义

注意：您可以在 GraphQL 查询中请求这些字段的任意组合。

分页字段

pageInfo 对象提供查询结果的分页详细信息：

字段	类型	描述
totalPages	Int	结果的总页数
totalItems	Int	匹配查询的项目总数
page	Int	当前页码
perPage	Int	每页的项目数量
hasNextPage	Boolean!	布尔值，指示是否有下一页结果
hasPreviousPage	Boolean!	布尔值，指示是否有上一页结果

查询参数

过滤选项 (ProjectListFilter)

参数	类型	必需	描述
companyIds	[String!]!	✅ 是	要搜索的公司 ID 或别名的数组
ids	[String!]	否	按特定项目 ID 过滤
archived	Boolean	否	按归档状态过滤（true/false）
isTemplate	Boolean	否	过滤模板项目（true/false）
search	String	否	按名称搜索项目（不区分大小写）
folderId	String	否	按文件夹 ID 过滤。使用 null 获取根级项目
inProject	Boolean	否	按用户成员资格过滤。请参见下面的说明

关于 inProject 过滤的说明：

• true 或 undefined：返回用户是成员的项目
• false：返回用户不在的项目（需要公司所有者权限）
• 文件夹过滤（folderId）仅在 inProject 不是 false 时有效

排序选项 (ProjectSort)

值	描述
id_ASC	按 ID 升序排序
id_DESC	按 ID 降序排序
name_ASC	按名称升序排序（A-Z）
name_DESC	按名称降序排序（Z-A）
createdAt_ASC	按创建日期排序（最旧优先）
createdAt_DESC	按创建日期排序（最新优先）
updatedAt_ASC	按最后更新排序（最旧优先）
updatedAt_DESC	按最后更新排序（最新优先）
position_ASC	按位置升序排序*
position_DESC	按位置降序排序*

*位置排序仅在查看用户是成员的项目时可用（inProject !== false）

分页参数

参数	类型	默认值	描述
skip	Int	0	要跳过的记录数
take	Int	20	要返回的记录数

重要说明

1. 非成员项目的默认行为 (inProject: false):

   • 排除归档项目，除非明确设置 archived 过滤
   • 排除模板项目，除非明确设置 isTemplate 过滤

2. 文件夹过滤限制：

   • 仅在显示用户的项目时有效
   • 不能与 inProject: false 一起使用
   • 使用 folderId: null 获取不在任何文件夹中的项目

3. 排序回退：

   • 在查看非成员项目时忽略位置排序
   • 在这种情况下回退到名称排序

4. 已弃用的参数：

   • orderBy, after, before, first, last 已被弃用
   • 请改用 sort, skip 和 take 代替