Utiliser les directives multi-champs
Une directive multi-champs est une directive qui peut être appliquée à plusieurs champs, au lieu d'un seul. Lorsqu'elle est activée, un argument affectAdditionalFieldsUnderPos est ajouté à toutes les directives, où l'on peut spécifier les positions relatives des champs supplémentaires auxquels appliquer la directive.
Par exemple, dans la requête suivante, la directive @strTranslate est appliquée uniquement au champ content :
{
posts {
excerpt
content @strTranslate
}
}La directive @strTranslate peut également être appliquée au champ excerpt, en ajoutant l'argument de directive affectAdditionalFieldsUnderPos avec la valeur [1] (car 1 est la position relative du champ excerpt depuis la directive @strTranslate) :
{
posts {
excerpt
content
@strTranslate(
affectAdditionalFieldsUnderPos: [1]
)
}
}Le nombre de champs à ajouter n'est pas limité. Dans cette requête, dateStr est également traduit :
{
posts {
dateStr
excerpt
content
@strTranslate(
affectAdditionalFieldsUnderPos: [1, 2]
)
}
}Le champ sur lequel la directive est naturellement appliquée (comme content dans toutes les requêtes ci-dessus) ne doit pas être spécifié dans l'argument.
Dans la requête ci-dessus, les positions relatives depuis la directive @strTranslate jusqu'aux champs précédents sont :
- Position
2:dateStr - Position
1:excerpt - Position
0:content<= est implicite, toujours appliqué
Cas d'utilisation
Il y a deux cas d'utilisation principaux pour cette fonctionnalité :
- Performance
- Fonctionnalité étendue
Performance
Pour les directives qui exécutent des appels à des API externes, plus le nombre de requêtes qu'elles exécutent est faible, plus elles seront résolues rapidement.
C'est le cas avec la directive @strTranslate, qui se connecte à l'API Google Translate. Normalement, pour traduire les champs content et excerpt d'une liste d'articles, la requête serait celle-ci :
query {
posts {
excerpt @strTranslate
content @strTranslate
}
}En ajoutant @strTranslate deux fois, cette requête exécute deux appels à l'API Google Translate (un pour traduire toutes les valeurs de excerpt, un pour toutes les valeurs de content).
Grâce à la fonctionnalité Multi-Field Directives, la requête ci-dessous traduit également toutes les valeurs pour les champs content et excerpt, mais n'exécute qu'un seul appel à l'API Google Translate :
query {
posts {
excerpt
content
@strTranslate(
affectAdditionalFieldsUnderPos: [1]
)
}
}Fonctionnalité étendue
Les directives recevant des champs supplémentaires peuvent fournir des calculs additionnels.
Par exemple, la directive @export exporte normalement la valeur d'un seul champ, comme le nom de l'utilisateur connecté :
query GetLoggedInUserName {
me {
name @export(as: "userName")
}
}Via l'argument affectAdditionalFieldsUnderPos, @export peut recevoir plusieurs champs, et exportera alors un dictionnaire contenant ces champs comme entrées :
query GetLoggedInUserNameAndSurname {
me {
name
surname
@export(
as: "userProps"
affectAdditionalFieldsUnderPos: [1]
)
}
}@export produira maintenant la valeur suivante dans la variable $userProps
{
"name": "Leo",
"surname": "Loso"
}Configuration
Pour activer ou désactiver les directives multi-champs dans le schéma GraphQL, allez au module "Multi-Field Directives" sur la page des Réglages, et cochez/décochez la case Enable multi-field directives? :
Pour activer ou désactiver les directives multi-champs sur un endpoint spécifique, sélectionnez l'option souhaitée dans le bloc "Multi-Field Directives" de la Schema Configuration correspondante :
