Lister tous les champs personnalisés

Récupérer une liste paginée de champs personnalisés pour un projet ou à travers plusieurs projets avec des options de filtrage et de tri

Lister tous les champs personnalisés

Les champs personnalisés vous permettent d'étendre la structure d'enregistrement standard de Blue avec des champs de données supplémentaires spécifiques à vos besoins commerciaux. Ce point de terminaison récupère les champs personnalisés disponibles dans vos projets, avec un filtrage par type de champ et un support de pagination.

Exemple de base

query ListCustomFields {
  customFields(
    filter: { projectId: "project_123" }
    sort: position_ASC
    take: 20
  ) {
    items {
      id
      uid
      name
      type
      position
    }
    pageInfo {
      totalItems
      hasNextPage
    }
  }
}

Exemple avancé

query ListCustomFieldsAdvanced {
  customFields(
    filter: {
      projectId: "project_123"
      types: [TEXT_SINGLE, NUMBER, SELECT_SINGLE]
    }
    sort: name_ASC
    skip: 20
    take: 50
  ) {
    items {
      id
      uid
      name
      type
      position
      description
      
      # Type-specific fields
      min              # For NUMBER, RATING, PERCENT
      max              # For NUMBER, RATING, PERCENT
      currency         # For CURRENCY type
      prefix           # For UNIQUE_ID type
      isDueDate        # For DATE type
      formula          # For FORMULA type
      
      # Validation settings
      editable
      metadata
      
      # For SELECT types
      customFieldOptions {
        id
        title
        color
        position
      }
    }
    pageInfo {
      totalItems
      hasNextPage
      hasPreviousPage
    }
  }
}

Paramètres d'entrée

CustomFieldFilterInput

Paramètre	Type	Requis	Description
`projectId`	String	Non	Filtrer par ID de projet spécifique
`types`	[CustomFieldType!]	Non	Filtrer par types de champs personnalisés

Valeurs de tri CustomFieldSort

Valeur	Description
`name_ASC`	Trier par nom croissant (A-Z)
`name_DESC`	Trier par nom décroissant (Z-A)
`createdAt_ASC`	Trier par date de création (plus ancien d'abord)
`createdAt_DESC`	Trier par date de création (plus récent d'abord)
`position_ASC`	Trier par position (par défaut)
`position_DESC`	Trier par position décroissante

Valeurs de type CustomFieldType

Valeur	Description
`TEXT_SINGLE`	Champ de texte à une ligne
`TEXT_MULTI`	Zone de texte multi-lignes
`SELECT_SINGLE`	Menu déroulant à sélection unique
`SELECT_MULTI`	Menu déroulant à sélection multiple
`CHECKBOX`	Champ case à cocher booléenne
`RATING`	Évaluation par étoiles (1-5 ou plage personnalisée)
`PHONE`	Numéro de téléphone avec validation
`NUMBER`	Saisie numérique
`CURRENCY`	Montant en devise
`PERCENT`	Valeur en pourcentage
`EMAIL`	Adresse e-mail avec validation
`URL`	URL Web avec validation
`UNIQUE_ID`	Identifiant unique généré automatiquement
`LOCATION`	Localisation géographique (lat/lng)
`FILE`	Pièce jointe
`DATE`	Sélecteur de date
`COUNTRY`	Sélecteur de pays
`FORMULA`	Champ calculé basé sur d'autres champs
`REFERENCE`	Lien vers des enregistrements dans un autre projet
`LOOKUP`	Extraire des données d'enregistrements référencés
`TIME_DURATION`	Champ de suivi du temps
`BUTTON`	Champ de bouton actionnable
`CURRENCY_CONVERSION`	Champ de conversion de devise

Paramètres de pagination

Paramètre	Type	Requis	Description
`skip`	Int	Non	Nombre d'éléments à ignorer (par défaut : 0)
`take`	Int	Non	Nombre d'éléments à retourner (par défaut : 20, max : 500)

Champs de réponse

CustomField

Champ	Type	Description
`id`	String!	Identifiant unique
`uid`	String!	ID convivial unique
`name`	String!	Nom d'affichage du champ
`type`	CustomFieldType!	Type du champ personnalisé
`position`	Float!	Position d'ordre de tri
`description`	String	Description facultative du champ
`min`	Float	Valeur minimale (NOMBRE, ÉVALUATION, POURCENTAGE)
`max`	Float	Valeur maximale (NOMBRE, ÉVALUATION, POURCENTAGE)
`currency`	String	Code de devise (type DEVISE)
`prefix`	String	Préfixe pour la génération de UNIQUE_ID
`isDueDate`	Boolean	Indique si le champ DATE représente une date d'échéance
`formula`	JSON	Configuration de formule (type FORMULE)
`editable`	Boolean	Indique si l'utilisateur actuel peut modifier ce champ
`metadata`	JSON	Configuration de champ supplémentaire
`customFieldOptions`	[CustomFieldOption!]	Options disponibles pour les types SELECT

CustomFieldOption

Champ	Type	Description
`id`	String!	Identifiant unique
`title`	String!	Texte d'affichage pour l'option
`color`	String!	Code couleur hexadécimal
`position`	Float!	Position d'ordre de tri

PageInfo

Champ	Type	Description
`totalItems`	Int	Nombre total de champs personnalisés
`hasNextPage`	Boolean!	Indique si d'autres pages existent
`hasPreviousPage`	Boolean!	Indique si des pages précédentes existent
`endCursor`	String	Curseur pour la pagination (obsolète - utiliser la pagination basée sur le décalage)

Autorisations requises

Les champs personnalisés sont accessibles en fonction de votre rôle de projet. Si vous avez un rôle personnalisé avec un accès restreint aux champs, seuls les champs marqués comme modifiables pour votre rôle seront retournés.

Rôle	Peut lister les champs personnalisés
`OWNER`	✅ Oui (tous les champs)
`ADMIN`	✅ Oui (tous les champs)
`MEMBER`	✅ Oui (en fonction des autorisations de rôle)
`CLIENT`	✅ Oui (en fonction des autorisations de rôle)

Réponses d'erreur

Projet non trouvé

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

Type de champ invalide

{
  "errors": [{
    "message": "Variable \"$filter\" got invalid value \"INVALID_TYPE\" at \"filter.types[0]\"; Value \"INVALID_TYPE\" does not exist in \"CustomFieldType\" enum.",
    "extensions": {
      "code": "GRAPHQL_VALIDATION_FAILED"
    }
  }]
}

Remarques importantes

Les champs personnalisés sont limités aux projets - vous devez spécifier un projectId dans le filtre
Le paramètre take est limité à 500 éléments par demande pour des raisons de performance
Les champs sont retournés en fonction des autorisations utilisateur - les rôles personnalisés peuvent avoir un accès restreint
L'ordre de tri par défaut est par position croissant, ce qui reflète l'ordre affiché dans l'interface utilisateur
Cette requête prend en charge le filtrage par projet unique - pour les requêtes multi-projets, utilisez l'interface imbriquée CustomFieldQueries
Certains types de champs (comme FORMULE et RÉFÉRENCE) peuvent inclure des structures de données imbriquées supplémentaires
Le champ editable indique si l'utilisateur actuel peut modifier les valeurs pour ce champ personnalisé

Points de terminaison associés

Créer un champ personnalisé - Ajouter de nouveaux champs personnalisés à un projet
Mettre à jour un champ personnalisé - Modifier les propriétés d'un champ personnalisé existant
Supprimer un champ personnalisé - Retirer un champ personnalisé d'un projet
Définir la valeur d'un champ personnalisé - Définir des valeurs sur des enregistrements