---

概述

Blue中的列表是用于在项目中组织待办事项的容器。每个列表可以容纳多个待办事项，并帮助将工作结构化为逻辑组。列表支持定位、锁定和基于角色的访问控制。

关键概念

• 每个项目最多可以有 50 个列表
• 列表按位置排序（升序）
• 列表可以被锁定以防止修改
• 列表遵循项目级别和基于角色的权限
• 删除的列表会移至垃圾箱（软删除）

查询

获取单个列表

通过ID检索特定的待办事项列表。

query GetTodoList($id: String!) {
  todoList(id: $id) {
    id
    uid
    title
    position
    isDisabled
    isLocked
    createdAt
    updatedAt
    project {
      id
      name
    }
    createdBy {
      id
      username
    }
  }
}

获取项目中的所有列表

检索特定项目的所有待办事项列表。

query GetProjectLists($projectId: String!) {
  todoLists(projectId: $projectId) {
    id
    uid
    title
    position
    isDisabled
    isLocked
    createdAt
    updatedAt
  }
}

高级列表查询

使用过滤、排序和分页查询列表。

query SearchTodoLists($filter: TodoListsFilterInput!, $sort: [TodoListsSort!], $skip: Int, $take: Int) {
  todoListQueries {
    todoLists(filter: $filter, sort: $sort, skip: $skip, take: $take) {
      items {
        id
        uid
        title
        position
        isDisabled
        isLocked
        createdAt
        updatedAt
        project {
          id
          name
        }
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
        total
      }
    }
  }
}

变更

创建列表

在项目中创建新的待办事项列表。

mutation CreateTodoList($input: CreateTodoListInput!) {
  createTodoList(input: $input) {
    id
    uid
    title
    position
    isDisabled
    isLocked
    createdAt
    project {
      id
      name
    }
  }
}

示例：

mutation {
  createTodoList(input: {
    projectId: "project-123"
    title: "Sprint 1 Tasks"
    position: 1.0
  }) {
    id
    title
  }
}

编辑列表

更新现有待办事项列表的属性。

mutation EditTodoList($input: EditTodoListInput!) {
  editTodoList(input: $input) {
    id
    title
    position
    isLocked
    updatedAt
  }
}

示例：

mutation {
  editTodoList(input: {
    todoListId: "list-123"
    title: "Sprint 1 - In Progress"
    position: 2.0
    isLocked: true
  }) {
    id
    title
    isLocked
  }
}

删除列表

删除待办事项列表（移至垃圾箱）。

mutation DeleteTodoList($input: DeleteTodoListInput!) {
  deleteTodoList(input: $input) {
    success
  }
}

示例：

mutation {
  deleteTodoList(input: {
    projectId: "project-123"
    todoListId: "list-123"
  }) {
    success
  }
}

标记列表为完成/未完成

将列表中的所有待办事项标记为完成或未完成。

# Mark as done
mutation MarkListDone($todoListId: String!, $filter: TodosFilter) {
  markTodoListAsDone(todoListId: $todoListId, filter: $filter)
}

# Mark as undone
mutation MarkListUndone($todoListId: String!, $filter: TodosFilter) {
  markTodoListAsUndone(todoListId: $todoListId, filter: $filter)
}

输入类型

CreateTodoListInput

参数	类型	必需	描述
projectId	String!	✅ 是	列表将要创建的项目ID
title	String!	✅ 是	列表名称
position	Float!	✅ 是	列表的位置（用于排序）

EditTodoListInput

参数	类型	必需	描述
todoListId	String!	✅ 是	要编辑的列表的ID
title	String	否	列表的新标题
position	Float	否	列表的新位置
isLocked	Boolean	否	列表是否应被锁定

DeleteTodoListInput

参数	类型	必需	描述
projectId	String!	✅ 是	项目ID（用于验证）
todoListId	String!	✅ 是	要删除的列表ID

TodoListsFilterInput

参数	类型	必需	描述
companyIds	[String!]!	✅ 是	按公司ID过滤
projectIds	[String!]	否	按特定项目ID过滤
ids	[String!]	否	按特定列表ID过滤
titles	[String!]	否	按列表标题过滤
search	String	否	按标题搜索列表

TodoListsSort 值

值	描述
title_ASC	按标题升序排序
title_DESC	按标题降序排序
createdAt_ASC	按创建日期升序排序
createdAt_DESC	按创建日期降序排序
updatedAt_ASC	按更新时间升序排序
updatedAt_DESC	按更新时间降序排序
position_ASC	按位置升序排序（默认）
position_DESC	按位置降序排序

响应类型

TodoList 类型

字段	类型	描述
id	ID!	唯一标识符
uid	String!	用户友好的标识符
position	Float!	列表位置用于排序
title	String!	列表名称
isDisabled	Boolean!	列表是否被禁用
isLocked	Boolean	列表是否被锁定
createdAt	DateTime!	创建时间戳
updatedAt	DateTime!	最后更新时间戳
activity	Activity	关联的活动日志
createdBy	User	创建列表的用户
project	Project!	父项目
todos	[Todo!]!	此列表中的待办事项
todosCount	Int!	待办事项数量

TodoListsPagination 类型

字段	类型	描述
items	[TodoList!]!	待办事项列表数组
pageInfo	PageInfo!	分页信息

所需权限

查询权限

操作	所需权限
todoList	Must be authenticated
todoLists	Must be authenticated and in company
todoListQueries.todoLists	Must be authenticated and in company

变更权限

操作	允许的项目级角色
createTodoList	OWNER, ADMIN, MEMBER
editTodoList	OWNER, ADMIN, MEMBER, CLIENT
deleteTodoList	OWNER, ADMIN, MEMBER
markTodoListAsDone	OWNER, ADMIN, MEMBER
markTodoListAsUndone	OWNER, ADMIN, MEMBER

注意： 具有CLIENT角色的用户可以编辑列表，但不能创建或删除它们。具有VIEW_ONLY或COMMENT_ONLY角色的用户不能创建、编辑或删除列表。

错误响应

TodoListNotFoundError

{
  "errors": [{
    "message": "Todo list was not found.",
    "extensions": {
      "code": "TODO_LIST_NOT_FOUND"
    }
  }]
}

ProjectNotFoundError

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

最大列表错误

{
  "errors": [{
    "message": "You have reached the maximum number of todo lists for this project.",
    "extensions": {
      "code": "INTERNAL_SERVER_ERROR"
    }
  }]
}

UnauthorizedError

{
  "errors": [{
    "message": "Unauthorized",
    "extensions": {
      "code": "UNAUTHORIZED"
    }
  }]
}

重要说明

• 列表限制：每个项目最多可以有50个列表
• 软删除：删除的列表会移至垃圾箱，并可能被恢复
• 位置管理：创建列表时，确保位置不冲突。使用增量值（1.0、2.0、3.0）以允许在列表之间插入
• 基于角色的访问：可以使用ProjectUserRoleTodoList权限隐藏某些角色的列表
• Webhooks：列表创建、更新和删除会触发webhooks（如果已配置）
• 活动跟踪：所有列表操作都会记录在活动记录中
• 实时更新：列表更改通过订阅发布以实现实时更新

相关操作

• 使用 todos 查询以获取列表中的待办事项
• 使用 createTodo 变更以将待办事项添加到列表
• 使用 moveTodo 变更以在列表之间移动待办事项
• 通过 subscribeToTodoList 订阅列表更改