Créer un Code Snippet avec VS Code

Qu’est-ce qu’un code snippet ?

Définition

Les code snippets, aussi appelés « extraits de code » en français sont des morceaux de code prédéfinis qu’il est possible d’insérer rapidement dans l’éditeur de code pour éviter d’écrire des blocs répétitifs.

Ils s’apparentent à des raccourcis.

Il est très utile de créer des raccourcis pour des extraits de code redondants comme par exemple en JS :

• L’écriture dans la console avec console.log()
• La déclaration d’une variable, constante, tableau, objet…
• La structure d’un appel fetch asynchrone avec async/await
• La structure d’une boucle for
• La sélection d’un élément du DOM
• Etc.

Dans VS Code, il est donc possible de créer des snippets personnalisés déclenchables grâce à des abréviations.

Si le Marketplace VS Code propose de nombreux plugins (chercher @category:"snippets" dans le moteur de recherche d’extensions) intégrant de nombreux snippets pré-conçus pour certains langages ou certaines technos, nous allons apprendre ici à créer nos propres snippets.

Imaginez-vous taper le raccourci gebi pour générer l’extrait de code suivant :

const <var> = document.getElementById("<selecteur>");

Ne serait-ce pas génialissime ?! 🤩

Pourquoi utiliser des snippets ?

Vous l’avez sans doute compris, intégrer l’usage de snippets dans son workflow est un véritable atout. Cela permet entre autres de :

• Gagner du temps : en évitant de réécrire du code souvent utilisé.
• Réduire le risque d’erreurs : les code snippets factorisant des extraits de code spécifiques, ils ne sont plus réécrits manuellement, réduisant ainsi les risques d’erreurs répétitives.

Structure d’un code snippet

Dans VS Code, les snippets sont définis via un objet JSON.

Voici à quoi ressemble la structure de base d’un snippet :

{
    "Nom du snippet": {
        "description": ...,
        "scope": ...,
        "prefix": ...,
        "body": ...
    }
}

Chaque snippet possède un :

• Nom : permettant d’identifier le snippet.
• Scope : détermine pour quels langages le snippet est actif.
• Préfixe : indique le raccourci à taper pour déclencher le snippet.
• Corps : le code qui sera inséré.
• Description : une courte explication du snippet.

{
    "Console log": {
        "description": "Insère un console.log()",
        "scope": "javascript,typescript",
        "prefix": "log",
        "body": [
            "console.log('$1');",
            "$0"
        ]
    }
}

Créer un snippet avec VS Code

Pour créer votre propre snippet, suivez ces étapes :

1. Cliquer sur l’icône de gestion (⚙️) dans la barre latérale gauche de VS Code.
2. Sélectionner Snippets.
3. Vient alors le moment de définir les caractéristiques du snippet. 👇

1. Nom

Le nom du snippet est défini en tant que propriété de référence de l’objet JSON :

{
    "Template de fonction": {
        ...
    }
}

Le nom est ici Template de fonction.

2. Description

La description d’un snippet est une propriété qui fournit une brève explication de ce que fait le snippet.

Elle aide les utilisateurs à comprendre rapidement le rôle du snippet lorsqu’ils le consultent dans leur éditeur de code.

{
    "Template de fonction": {
        "description": "Modèle de fonction JavaScript avec des paramètres et un corps personnalisable.",
    }
}

3. Scope

Les snippets sont limités pour ne proposer que des suggestions pertinentes. Ils peuvent être restreints selon :

• Le langage auquel ils sont associés (un ou plusieurs, voire tous)
• Le projet auquel ils sont liés (souvent tous)

Scope par langage

Les snippets peuvent être définis pour un ou plusieurs langages.

Snippet pour un seul langage

Si un snippet est défini pour un seul langage, il est défini dans un fichier spécifique (par exemple 📄 javascript.json) :

{
    "Template de fonction": { ... }
}

Snippet pour plusieurs langages

Si un snippet est défini pour plusieurs langages, il est défini dans un fichier nommé 📄 <nom_snippet>.code-snippets.

Par exemple 📄 Template de fonction.code-snippets :

{
    "Template de fonction": {
        "description": ...,
        "scope": "javascript,typescript",
        ...
    }
}

Ces snippets sont alors rendus accessibles à plusieurs langages grâce à la propriété scope.

Si la propriété scope n’est pas définie, alors les snippets sont disponibles dans tous les langages.

Scope par projet

Les snippets peuvent également être spécifiques à un projet. Ils seront dans ce cas de figure créés dans le dossier 📂 .vscode présent à la racine du projet, et sont partagés entre tous les utilisateurs de ce projet.

4. Préfixe

Le préfixe est le raccourci saisi par le développeur pour déclencher le snippet.

{
    "Template de fonction": {
        "description": ...,
        "scope": ...,
        "prefix": "fct"
    }
}

VS Code propose une autocomplétion pour les préfixes, ce qui permet d’afficher le snippet dès qu’on commence à taper le mot.

La saisie de fct déclenchera ici le snippet créant un template de fonction.

5. Body

Le corps est la partie la plus importante du snippet, c’est le code qui sera inséré.

Il est ici possible d’utiliser des constructions spéciales pour contrôler la position du curseur et le texte inséré.

Marqueurs de position

Les marqueurs de position dans les snippets définissent les emplacements où le curseur de l’utilisateur doit s’arrêter pour saisir du contenu.

Ces points de saisie successifs rendent l’utilisation des snippets plus interactive et dynamique, en facilitant l’insertion rapide de contenu tout en guidant l’utilisateur.

On distingue 3 types de marqueurs de position :

1. Les marqueurs génériques (tabstops)
2. Les marqueurs nommés (placeholders)
3. Les sélécteurs (choices)

Marqueurs génériques (tabstops)

Les marqueurs génériques, ou « tabstops », sont des points d’arrêt numérotés dans un snippet, déterminant l’ordre de navigation du curseur à travers l’extrait de code.

Ils sont identifiés par des numéros comme $1, $2, etc.

Quand l’utilisateur déclenche le snippet, il peut passer d’un tabstop à l’autre en appuyant sur la touche Tab.

• $1 représente le premier point où le curseur s’arrête
• $2 le second
• Et ainsi de suite…

Le tabstop final peut être défini avec $0, plaçant ainsi le curseur à un emplacement de saisie final après avoir complété tous les autres points. Cela permet d’écrire du code à la suite du snippet sans avoir à cliquer après manuellement.

{
    "Template de fonction": {
        "description": ...,
        "scope": ...,
        "prefix": ...,
        "body": [
            "function $1($2) {",
            "  $3",
            "}",
            "$0"
        ]
    }
}

Si le snippet contient plusieurs lignes, on les notera dans un tableau.

Dans cet exemple :

• $1 : Le curseur s’arrête d’abord pour saisir le nom de la fonction.
• $2 : Ensuite, pour saisir les paramètres de la fonction.
• $3 : Ensuite, pour insérer le corps de la fonction.
• $0 : Enfin, le curseur se place à la fin du snippet.

Marqueurs nommés (placeholders)

Les placeholders permettent non seulement de définir un emplacement pour la saisie, mais aussi d’inclure du texte par défaut qui peut être modifié par l’utilisateur.

Ils apparaissent sous la forme ${1:placeholder}, où placeholder est un exemple ou une valeur par défaut que l’utilisateur peut écraser.

{
    "Template de fonction": {
        "scope": "javascript,typescript",
        "prefix": "fct",
        "body": [
            "function ${1:name}(${2:params}) {",
            "  $3",
            "}",
            "$0"
        ]
    }
}

Ici, le placeholder $1 contient le texte name, qui peut être modifié directement après que l’utilisateur ait déclenché le snippet.

Ils servent à guider l’utilisateur en offrant des suggestions contextuelles.

Si l’utilisateur passe au marqueur suivant, alors la valeur de ce placeholder sera conservée.

Sélecteurs (choices)

Les sélecteurs sont une forme avancée de placeholder qui permettent à l’utilisateur de choisir parmi une liste prédéfinie d’options.

Ils apparaissent sous la forme ${1|option1,option2,option3|}.

Cette suggestion de valeurs est particulièrement utile lorsque le choix d’une option est limité.

{
    "Insert Bootstrap button": {
        "scope": "html,php,twig",
        "prefix": "btn",
        "body": [
            "<a href='$1' class='btn btn-${2|primary,secondary,success,warning,danger|}'>$3</a>",
            "$0"
        ]
    }
}

Dans cet exemple, au niveau du second marqueur $2, l’utilisateur pourra sélectionner parmi primary, secondary, success, warning ou danger dans un menu déroulant.

Variables

Les variables vont permettre d’injecter des données dynamiques au sein des snippets, mais contrairement aux marqueurs, celles-ci seront définies automatiquement.

La syntaxe pour les utiliser est simple : $MA_VARIABLE en veillant à bien respecter l’UPPERCASE.

Bien qu’il soit possible de découvrir toutes les variables sur la documentation officielle, voici quelques exemples de variables utiles pour vos snippets.

Variables Système

Ces variables récupèrent des informations système spécifiques :

Variables Date et heure

Ces variables récupèrent des informations d’horodatage spécifiques :

Variables de valeurs aléatoires

Ces variables génèrent des informations aléatoires :

Variables de commentaires

Ces variables génèrent les caractères de commentaires correspondant au langage cible :