Comment lire les signatures de fonction

Les signatures de fonction se présentent généralement comme suit :

vnode = m(selector, attributes, children)

Argument	Type	Requis	Description
selector	String|Object	Oui	Un sélecteur CSS ou un composant.
attributes	Object	Non	Attributs HTML ou propriétés d'éléments.
children	Array<Vnode>|String|Number|Boolean	Non	Vnodes enfants. Peut être écrit sous forme de splat d'arguments.
returns	Vnode		Un vnode.

La ligne de signature au-dessus du tableau indique la syntaxe générale de la méthode, en précisant le nom de la méthode, l'ordre de ses arguments et un nom de variable suggéré pour sa valeur de retour.

La colonne Argument du tableau indique quelle partie de la signature est expliquée par la ligne correspondante. La ligne returns fournit des informations sur la valeur de retour de la méthode.

La colonne Type indique le type attendu pour l'argument.

Une barre verticale (|) indique qu'un argument est valide s'il correspond à l'un des types répertoriés. Par exemple, String|Object indique que selector peut être une chaîne OU un objet.

Des chevrons (< >) après un Array indiquent le type attendu pour les éléments du tableau. Par exemple, Array<String> indique que l'argument doit être un tableau et que tous les éléments de ce tableau doivent être des chaînes. Des chevrons après un Object indiquent une map. Par exemple, Object<String,Component> indique que l'argument doit être un objet, dont les clés sont des chaînes et les valeurs sont des composants.

Parfois, des types non natifs peuvent apparaître pour indiquer qu'une signature d'objet spécifique est requise. Par exemple, Vnode est un objet qui a la structure d'un nœud DOM virtuel.

La colonne Requis indique si un argument est obligatoire ou facultatif. Si un argument est facultatif, vous pouvez le définir sur null ou undefined, ou l'omettre complètement, de sorte que l'argument suivant prenne sa place.

Arguments optionnels

Les arguments de fonction entourés de crochets [ ] sont facultatifs. Dans l'exemple ci-dessous, l'argument url est optionnel :

m.request([url, ] options)

Splats

Un argument splat signifie que si l'argument est un tableau, vous pouvez omettre les crochets et passer un nombre variable d'arguments à la méthode.

Dans l'exemple en haut, cela signifie que m("div", {id: "foo"}, ["a", "b", "c"]) peut également être écrit comme m("div", {id: "foo"}, "a", "b", "c").

Les splats sont utiles dans certains langages qui se compilent vers JS, tels que CoffeeScript, et permettent également des raccourcis pratiques pour certains cas d'utilisation courants.

Signatures de fonction

Les fonctions sont notées avec une flèche (->). Le côté gauche de la flèche indique les types des arguments d'entrée et le côté droit indique le type de la valeur de retour.

Par exemple, parseFloat a la signature String -> Number, c'est-à-dire qu'elle prend une chaîne en entrée et renvoie un nombre en sortie.

Les fonctions avec plusieurs arguments sont notées avec des parenthèses : (String, Array) -> Number

Signatures de composant

Les composants sont notés par des appels à m, mais avec l'argument de sélecteur initial défini sur une constante nommée dans le texte pertinent :

vnode = m(m.route.Link, attributes, enfants )

Argument	Type	Requis	Description
attributes.href	Object	Oui	La route cible vers laquelle naviguer.
attributes.selector	String|Object|Function	Non	Définit le nom de la balise à utiliser. Doit être un sélecteur valide pour m si spécifié, par défaut "a".
attributes.options	Object	Non	Définit les options passées à m.route.set.
attributes	Object	Non	D'autres attributs à appliquer au vnode retourné.
children	Array<Vnode>|String|Number|Boolean	Non	Vnodes enfants pour ce lien.
returns	Vnode		Un vnode.

Les enfants ici, s'ils sont spécifiés, sont supposés pouvoir être écrits sous forme de splat d'arguments, sauf indication contraire dans le texte.

Un élément sans enfants et/ou attributs pertinents peut choisir d'omettre complètement le paramètre correspondant :

vnode = m(Component, attributes)

Argument	Type	Requis	Description
attributes.href	Object	Oui	The
attributes	Object	Non	D'autres attributs à appliquer au vnode retourné
returns	Vnode		Un vnode