註冊
聯絡 登入 註冊
系統狀態

使用強大的搜索和分頁選項查詢和篩選 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 打開