---

刪除自定義字段

永久性地從項目中移除自定義字段及所有相關數據、值和配置。此操作無法撤銷，並將影響所有使用此字段的記錄。

基本示例

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
}