---

删除自定义字段

永久性地从项目中移除自定义字段及其所有相关数据、值和配置。此操作无法撤销，并将影响所有使用该字段的记录。

基本示例

mutation DeleteCustomField {
  deleteCustomField(id: "field_abc123")
}

高级示例

mutation DeleteCustomFieldWithResponse {
  deleteCustomField(id: "field_abc123")
}

输入参数

参数	类型	必需	描述
id	String!	✅ 是	要删除的自定义字段的唯一标识符

响应字段

字段	类型	描述
deleteCustomField	Boolean!	删除成功时始终返回 true

所需权限

只有项目所有者和管理员可以删除自定义字段。

角色	可以删除自定义字段
OWNER	✅ 是
ADMIN	✅ 是
MEMBER	❌ 否
CLIENT	❌ 否

级联影响

当自定义字段被删除时，以下清理操作会自动发生：

数据清理

• 自定义字段值 - 所有记录中的该字段的值将被移除
• 字段选项 - 所有下拉选项和配置将被删除
• 活动历史 - 与该字段相关的所有活动记录将被移除
• 查找配置 - 任何查找字段引用将被清理

按钮字段的特殊处理

如果被删除的字段类型为 BUTTON，将进行额外的清理：

• 自动化 - 由该按钮触发的所有自动化将被删除
• 自动化历史 - 相关的自动化活动将被移除

实时更新

• 图表 - 项目图表将被标记为更新以反映更改
• 公式 - 项目中的所有公式字段将被重新计算
• 时间跟踪 - 时间持续计算将被更新
• 订阅 - 实时通知将发送给连接的客户端
• Webhook - 集成Webhook将被触发以记录删除事件

错误响应

未找到自定义字段

{
  "errors": [{
    "message": "Custom field was not found.",
    "extensions": {
      "code": "CUSTOM_FIELD_NOT_FOUND"
    }
  }]
}

权限不足

{
  "errors": [{
    "message": "You don't have permission to perform this action",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }]
}

重要说明

永久删除

• 无法撤销 - 被删除的自定义字段无法恢复
• 数据丢失 - 所有记录中的字段值将被永久移除
• 立即生效 - 更改将在所有项目用户中立即生效

性能考虑

• 大型项目 - 在记录较多的项目中，删除可能需要更长时间
• 公式重新计算 - 复杂公式的项目可能会经历短暂的处理延迟
• 图表更新 - 仪表板图表将刷新以反映更改

最佳实践

1. 备份数据 - 在删除之前导出重要的字段值
2. 沟通更改 - 在删除字段之前通知团队成员
3. 检查依赖关系 - 确保没有自动化或公式依赖于该字段
4. 审查报告 - 更新任何引用已删除字段的报告

相关操作

• 使用 列出自定义字段 查找字段ID
• 考虑 创建自定义字段 以重新创建类似字段
• 审查 自定义字段值 以了解数据影响

常见用例

移除未使用的字段

# First, list fields to identify unused ones
query ListCustomFields {
  customFields(projectId: "project_123") {
    id
    name
    type
    createdAt
    # Check usage in records
  }
}

# Then delete the unused field
mutation DeleteUnusedField {
  deleteCustomField(id: "field_to_remove")
}

清理测试字段

# Remove fields created during testing
mutation CleanupTestFields {
  field1: deleteCustomField(id: "test_field_1")
  field2: deleteCustomField(id: "test_field_2")
  field3: deleteCustomField(id: "test_field_3")
}

重新结构化项目字段

# When reorganizing field structure
mutation RestructureFields {
  # Delete old fields
  deleteOldPriorityField: deleteCustomField(id: "old_priority_field")
  deleteOldStatusField: deleteCustomField(id: "old_status_field")
  
  # Note: Create new fields in separate mutations
}

Webhook 事件

当自定义字段被删除时，将触发以下Webhook事件：

{
  "event": "CUSTOM_FIELD_DELETED",
  "projectId": "project_123",
  "timestamp": "2024-01-15T10:30:00Z",
  "previousValue": {
    "id": "field_abc123",
    "name": "Priority Level",
    "type": "SELECT_SINGLE",
    "projectId": "project_123"
  },
  "currentValue": null
}