注册
联系 登录 注册
系统状态

使用强大的搜索和分页选项查询和过滤 Blue 中的记录（待办事项）。

列出记录

待办事项查询允许您从 Blue 中检索记录，并提供全面的过滤、排序和分页选项。您可以跨公司、项目查询记录，或按特定标准进行过滤，如指派人、标签和日期。

基本示例

使用最少的参数列出公司中的所有记录：

query ListRecords {
  todoQueries {
    todos(
      filter: {
        companyIds: ["company_123"]
      }
    ) {
      items {
        id
        title
        done
        duedAt
      }
      pageInfo {
        totalItems
        hasNextPage
      }
    }
  }
}

高级示例

使用全面的过滤、排序和字段选择查询记录：

query ListRecordsAdvanced {
  todoQueries {
    todos(
      filter: {
        companyIds: ["company_123"]
        projectIds: ["project_456", "project_789"]
        assigneeIds: ["user_123"]
        tagIds: ["tag_priority", "tag_urgent"]
        showCompleted: false
        dueStart: "2025-01-01T00:00:00Z"
        dueEnd: "2025-12-31T23:59:59Z"
        search: "product launch"
        excludeArchivedProjects: true
        fields: [
          {
            type: "CUSTOM_FIELD"
            customFieldId: "cf_status_123"
            customFieldType: "SELECT_SINGLE"
            values: ["In Progress", "Review"]
            op: "IN"
          }
        ]
        op: "AND"
      }
      sort: [duedAt_ASC, position_ASC]
      limit: 50
      skip: 0
    ) {
      items {
        id
        uid
        position
        title
        text
        html
        startedAt
        duedAt
        timezone
        color
        cover
        done
        archived
        createdAt
        updatedAt
        commentCount
        checklistCount
        checklistCompletedCount
        isRepeating
        todoList {
          id
          title
        }
        users {
          id
          name
          email
        }
        tags {
          id
          title
          color
        }
        customFields {
          id
          title
          type
          value
        }
        createdBy {
          id
          name
        }
      }
      pageInfo {
        totalPages
        totalItems
        page
        perPage
        hasNextPage
        hasPreviousPage
      }
    }
  }
}

输入参数

TodosFilter

参数 类型 必需 描述
companyIds [String!]! ✅ 是 要查询的公司 ID 或别名
projectIds [String!] 否 按特定项目 ID 或别名过滤
todoIds [String!] 否 按其 ID 检索特定待办事项
assigneeIds [String!] 否 按指派用户 ID 过滤
tagIds [String!] 否 按标签 ID 过滤
tagColors [String!] 否 按标签颜色（十六进制格式）过滤
tagTitles [String!] 否 按标签标题过滤
todoListIds [String!] 否 按待办事项列表 ID 过滤
todoListTitles [String!] 否 按待办事项列表标题过滤
done Boolean 否 按完成状态过滤（已弃用，使用 showCompleted）
showCompleted Boolean 否 显示/隐藏已完成的待办事项（默认：true）
startedAt DateTime 否 按开始日期过滤
duedAt DateTime 否 按确切到期日期过滤
dueStart DateTime 否 到期日期范围开始（包含）
dueEnd DateTime 否 到期日期范围结束（包含）
search String 否 在标题和文本内容中搜索
q String 否 替代搜索参数（与搜索相同）
excludeArchivedProjects Boolean 否 从归档项目中排除待办事项
coordinates JSON 否 地理空间过滤以进行地图视图（多边形坐标）
fields JSON 否 自定义字段过滤（请参阅高级过滤）
op FilterLogicalOperator 否 字段过滤的逻辑运算符（AND/OR）

查询参数

参数 类型 必需 描述
filter TodosFilter! ✅ 是 查询的过滤条件
sort [TodosSort!] 否 排序顺序（默认：空数组）
limit Int 否 每页的项目数量（默认：20，最大：500）
skip Int 否 分页时跳过的项目数量（默认：0）

TodosSort 值

值 描述
assignees_ASC 按指派人姓名升序排序
assignees_DESC 按指派人姓名降序排序
createdAt_ASC 按创建日期升序排序（最旧的在前）
createdAt_DESC 按创建日期降序排序（最新的在前）
createdBy_ASC 按创建者姓名升序排序
createdBy_DESC 按创建者姓名降序排序
duedAt_ASC 按到期日期升序排序（最早的在前）
duedAt_DESC 按到期日期降序排序（最新的在前）
position_ASC 按位置升序排序（默认列表顺序）
position_DESC 按位置降序排序
startedAt_ASC 按开始日期升序排序
startedAt_DESC 按开始日期降序排序
title_ASC 按标题字母顺序升序排序
title_DESC 按标题字母顺序降序排序
todoListPosition_ASC 按待办事项列表位置升序排序
todoListPosition_DESC 按待办事项列表位置降序排序
todoListTitle_ASC 按待办事项列表标题升序排序
todoListTitle_DESC 按待办事项列表标题降序排序
todoTags_ASC 按标签升序排序
todoTags_DESC 按标签降序排序

FilterLogicalOperator 值

值 描述
AND 所有条件必须匹配
OR 任何条件必须匹配

自定义字段过滤

fields 参数支持通过自定义字段进行高级过滤：

{
  "fields": [
    {
      "type": "CUSTOM_FIELD",
      "customFieldId": "cf_123",
      "customFieldType": "SELECT_SINGLE",
      "values": ["Option1", "Option2"],
      "op": "IN"
    }
  ]
}

自定义字段过滤结构

字段 类型 描述
type String 必须为 "CUSTOM_FIELD"
customFieldId String 自定义字段的 ID
customFieldType String 自定义字段的类型
values [String!] 要过滤的值
op String 比较运算符（IN, NOT_IN, EQ 等）

支持的自定义字段类型

  • 文本字段: TEXT_SINGLE, TEXT_MULTI, URL, EMAIL, PHONE, UNIQUE_ID
  • 数值字段: CURRENCY, NUMBER, FORMULA
  • 选择字段: SELECT_SINGLE, SELECT_MULTI, CHECKBOX, COUNTRY
  • 引用字段: REFERENCE, LOOKUP
  • 日期字段: DATE

响应字段

TodosResult

字段 类型 描述
items [Todo!]! 待办事项记录数组
pageInfo PageInfo! 分页元数据

PageInfo

字段 类型 描述
totalPages Int 可用页面总数
totalItems Int 所有页面的项目总数
page Int 当前页面编号（根据跳过/限制计算）
perPage Int 每页的项目数量
hasNextPage Boolean! 是否有下一页
hasPreviousPage Boolean! 是否有上一页

Todo 字段

字段 类型 描述
id ID! 唯一标识符
uid String! 用户友好的唯一标识符
position Float! 列表中的位置
title String! 待办事项标题
text String! 纯文本内容
html String! HTML 格式内容
startedAt DateTime 开始日期/时间
duedAt DateTime 到期日期/时间
timezone String 日期的时区
color String 视觉颜色指示器
cover String 封面图像 URL
done Boolean! 完成状态
archived Boolean! 存档状态
createdAt DateTime! 创建时间戳
updatedAt DateTime! 最后更新时间戳
commentCount Int! 评论数量
checklistCount Int! 总检查项数量
checklistCompletedCount Int! 已完成的检查项数量
isRepeating Boolean! 待办事项是否为重复
isRead Boolean 当前用户的阅读状态
isSeen Boolean 当前用户的查看状态
todoList TodoList! 父待办事项列表
users [User!]! 指派用户
tags [Tag!]! 关联标签
checklists [Checklist!]! 关联检查列表
createdBy User 创建待办事项的用户
customFields [CustomField!]! 自定义字段值
dependOn [Todo!] 阻塞待办事项（依赖项）
dependBy [Todo!] 依赖待办事项（被此阻塞）
timeTracking TimeTracking 时间跟踪数据

所需权限

用户必须具有适当的访问权限以查询记录：

访问类型 要求
Company Access User must be a member of the company
Project Access User must have access to specific projects (if filtering by project)
Todo Visibility Depends on user's role and permissions:
- VIEW_ONLY Can view all accessible todos
- COMMENT_ONLY Can view all accessible todos
- CLIENT May be restricted to assigned todos only
- MEMBER Can view all project todos
- ADMIN Can view all project todos
- OWNER Can view all company todos

特殊限制：

  • 拥有 showOnlyAssignedTodos 权限的用户只能看到分配给他们的待办事项
  • 隐藏的待办事项列表（基于角色配置）会自动排除
  • 基于标签的权限可能会进一步过滤结果

错误响应

常见错误

查询优雅地处理错误，并返回空结果以应对：

  • 无效的公司 ID
  • 无法访问的项目
  • 权限被拒绝的场景

对于严重错误，可能会返回 GraphQL 错误：

{
  "errors": [{
    "message": "Query timeout exceeded",
    "extensions": {
      "code": "QUERY_TIMEOUT"
    }
  }]
}

重要说明

性能

  • 默认限制：每页 20 项（如果未指定，则自动应用）
  • 最大限制：每个请求 500 项（自动限制）
  • 优化：查询使用优化的连接，使用 STRAIGHT_JOIN 以获得最佳性能
  • 索引：常见过滤字段已建立索引，以快速查询
  • 自定义字段：广泛支持自定义字段过滤，性能影响最小
  • 地理查询：支持基于多边形的坐标过滤以进行地图视图

日期过滤

  • 日期范围是包含的
  • 支持重叠的日期范围（在范围内开始或结束的待办事项）
  • 空日期会被优雅地处理（没有到期日期的待办事项不会匹配日期过滤）
  • 所有日期应为 ISO 8601 格式

搜索行为

  • 搜索不区分大小写
  • 在标题和文本内容中进行搜索
  • 支持部分单词匹配
  • 特殊字符得到适当处理

分页策略

  • 使用 skip 和 limit 进行基于偏移的分页
  • 计算当前页面： page = Math.floor(skip / limit) + 1
  • 对于大型数据集，考虑使用过滤器来减少结果大小
  • 在增加跳过之前，请始终检查 hasNextPage

相关端点

  • 创建记录：使用 createTodo 变更创建新记录
  • 更新记录：使用 updateTodo 变更修改记录
  • 删除记录：使用 deleteTodo 变更删除记录
  • 列出自定义字段：查询可用于过滤的自定义字段
  • 列出项目：查询可用于过滤的项目
© Blue | 用心设计 ❤ 遍布

AI助手

响应是通过人工智能生成的，可能包含错误。

我能帮您什么？

随时问我关于 Blue 或本文档的任何问题。

输入发送 • Shift+Enter 换行 • ⌘I 打开