---

创建记录

createTodo 变更允许您在 Blue 中创建新记录，提供全面的配置选项，包括自定义字段、标签、分配等。记录可以在特定列表中创建，或自动放置在默认列表中。

基本示例

创建一个仅包含标题的简单记录：

mutation CreateRecord {
  createTodo(
    input: {
      title: "New Task"
    }
  ) {
    id
    title
    position
  }
}

高级示例

创建一个包含所有可用选项的记录：

mutation CreateRecordAdvanced {
  createTodo(
    input: {
      todoListId: "clm4n8qwx000008l0g4oxdqn7"
      title: "Product Launch Planning"
      placement: TOP
      description: "<p>Complete product launch preparation including marketing materials and documentation.</p>"
      startedAt: "2025-01-15T09:00:00Z"
      duedAt: "2025-02-01T17:00:00Z"
      notify: true
      assigneeIds: ["user_123", "user_456"]
      tags: [
        { id: "tag_existing_123" }
        { title: "Priority", color: "#ff4b4b" }
        { title: "Marketing" }
      ]
      customFields: [
        {
          customFieldId: "cf_budget_123"
          value: "50000 USD"
        }
        {
          customFieldId: "cf_status_456"
          value: "In Progress"
        }
      ]
      checklists: [
        {
          title: "Pre-launch Checklist"
          position: 1
        }
      ]
    }
  ) {
    id
    uid
    title
    position
    startedAt
    duedAt
    todoList {
      id
      title
    }
    users {
      id
      fullName
    }
    tags {
      id
      title
      color
    }
  }
}

输入参数

CreateTodoInput

参数	类型	必需	描述
todoListId	String	否	要添加记录的待办事项列表的 ID。如果未提供，则使用项目中的第一个待办事项列表
title	String!	✅ 是	记录的标题（必需）
position	Float	否	列表中的自定义位置。如果未提供，则使用放置参数
placement	CreateTodoInputPlacement	否	如果未指定位置，则放置记录的位置（顶部或底部）
startedAt	DateTime	否	记录的开始日期/时间
duedAt	DateTime	否	记录的截止日期/时间
notify	Boolean	否	是否发送此记录创建的通知
description	String	否	HTML 描述内容（将被清理）
assigneeIds	[String!]	否	要分配给此记录的用户 ID 数组
checklists	[CreateChecklistWithoutTodoInput!]	否	要与记录一起创建的检查表数组
customFields	[CreateTodoInputCustomField]	否	自定义字段值数组
tags	[CreateTodoTagInput!]	否	要附加到记录的标签数组

CreateTodoInputPlacement 值

值	描述
TOP	放置在列表顶部（最高位置）
BOTTOM	放置在列表底部（最低位置）

CreateTodoTagInput

参数	类型	必需	描述
id	String	否*	要连接的现有标签的 ID
title	String	否*	标签的标题（如果不存在，则创建新标签）
color	String	否	新标签的十六进制颜色（默认为 #4a9fff）

*注意：您必须提供 id（用于现有标签）或 title（通过标题创建/查找）

CreateTodoInputCustomField

参数	类型	必需	描述
customFieldId	String	否	自定义字段的 ID
value	String	否	自定义字段的值（请参见下面的格式指南）

CreateChecklistWithoutTodoInput

参数	类型	必需	描述
title	String!	✅ 是	检查表的标题
position	Float	否	检查表在记录中的位置

自定义字段值格式

设置自定义字段值时，根据字段类型使用以下格式：

字段类型	格式	示例
CHECKBOX	"true", "1", or "checked" for checked	"true"
COUNTRY	Country name or ISO code	"United States" or "US"
CURRENCY	Amount with optional currency	"50000 USD"
DATE	YYYY-MM-DD or date range	"2025-01-15" or "2025-01-15,2025-01-20"
NUMBER	Numeric value	"42"
PERCENT	Numeric value (% optional)	"75" or "75%"
RATING	Numeric value within range	"4" (if max is 5)
PHONE	International phone format	"+1234567890"
SELECT_SINGLE	Custom field option ID	"option_123"
SELECT_MULTI	Comma-separated option IDs	"option_1,option_2"
LOCATION	Latitude,longitude	"40.7128,-74.0060"
EMAIL	Valid email address	"user@example.com"
URL	Valid URL	"https://example.com"
TEXT	Plain text value	"Any text content"

响应字段

该变更返回一个 Todo 对象，包含全面的记录详细信息：

字段	类型	描述
id	String!	记录的唯一标识符
uid	String!	替代唯一标识符
title	String!	记录标题
position	Float!	列表中的位置
done	Boolean!	完成状态
startedAt	DateTime	开始日期/时间
duedAt	DateTime	截止日期/时间
todoList	TodoList	相关待办事项列表详细信息
users	[User!]	被分配的用户
tags	[Tag!]	相关标签
checklists	[Checklist!]	相关检查表
customFields	[CustomFieldValue!]	自定义字段值

所需权限

用户必须具有适当的项目访问权限才能创建记录：

访问级别	可以创建记录
OWNER	✅ 是
ADMIN	✅ 是
MEMBER	✅ 是
CLIENT	✅ 是
COMMENT_ONLY	❌ 否
VIEW_ONLY	❌ 否

该变更要求用户的项目访问级别为 OWNER、ADMIN、MEMBER 或 CLIENT。具有 VIEW_ONLY 或 COMMENT_ONLY 角色的用户无法创建记录。

错误响应

ProjectNotFoundError

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

何时：用户没有可用的项目上下文。

TodoListCreateTodoLimitError

{
  "errors": [{
    "message": "Todo list has reached the maximum number of todos.",
    "extensions": {
      "code": "TODO_LIST_CREATE_TODO_LIMIT_ERROR"
    }
  }]
}

何时：待办事项列表已经包含 100,000 条记录（最大限制）。

TodoListNotFoundError

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

何时：指定的 todoListId 不存在或用户缺乏访问权限。

CustomFieldValueParseError

{
  "errors": [{
    "message": "Invalid phone number format",
    "extensions": {
      "code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
    }
  }]
}

何时：自定义字段值未通过验证（例如，无效的电话，评分超出范围）。

重要说明

性能

• 每个待办事项列表最多可以包含 100,000 条记录
• 创建记录会触发多个后台进程（网络钩子、自动化、搜索索引）
• 批量操作比逐个创建记录更高效

业务逻辑

• 位置处理：当未指定 position 或 placement 时，默认位置为 65535.0
• 日期逻辑：
  • 如果仅提供 duedAt，则 startedAt 设置为当天的开始
  • 如果仅提供 startedAt，则 duedAt 设置为相同的值
• 标签创建：如果指定的标题/颜色不存在，则会自动创建新标签
• 列表选择：如果未提供 todoListId，则使用项目中的第一个待办事项列表

副作用

创建记录会触发：

• 活动日志条目创建
• 网络钩子通知
• 搜索索引更新
• 自动化规则执行（如果已配置）
• 电子邮件/推送通知（如果 notify: true）
• 公式和时间持续时间自定义字段计算
• 分析和图表更新

相关端点

• 列出记录：查询待办事项以检索现有记录
• 更新记录：使用 updateTodo 变更修改记录
• 列出自定义字段：查询以获取可用的自定义字段 ID
• 列出标签：查询以获取现有标签 ID
• 列出待办事项列表：查询以获取可用的待办事项列表 ID