Bibliothèques

Une bibliothèque est un projet de script dont les fonctions peuvent être réutilisées dans d'autres scripts.

Avertissement :Un script qui utilise une bibliothèque ne s'exécute pas aussi rapidement que si tout le code était contenu dans un seul projet de script. Bien que les bibliothèques puissent rendre le développement et la maintenance plus pratiques, utilisez-les avec parcimonie dans les projets où la vitesse est essentielle. En raison de ce problème, l'utilisation de la bibliothèque doit être limitée dans les modules complémentaires.

Obtenir l'accès à une bibliothèque

Pour inclure une bibliothèque dans votre projet, vous devez au moins disposer d'un accès en lecture à celle-ci. Si vous n'êtes pas l'auteur de la bibliothèque que vous souhaitez inclure, contactez-le et demandez l'accès.

Vous avez besoin de l'ID de script de la bibliothèque que vous souhaitez inclure. Lorsque vous avez accès à la bibliothèque, vous pouvez trouver l'ID de script sur la page Paramètres du projet .

Ajouter une bibliothèque à votre projet de script

1. À gauche de l'éditeur Apps Script, à côté de "Bibliothèques", cliquez sur Ajouter une bibliothèque .
2. Dans le champ "ID de script", collez l'ID de script de la bibliothèque.
3. Cliquez sur Rechercher.
   Si vous rencontrez une erreur, assurez-vous de disposer au moins d'un accès en lecture au projet que vous essayez d'inclure.
4. Cliquez sur la liste déroulante Version, puis sélectionnez la version de la bibliothèque à utiliser.
5. Vérifiez si le nom "Identifier" par défaut est bien celui que vous souhaitez utiliser avec cette bibliothèque. Il s'agit du nom que votre script utilise pour faire référence à la bibliothèque. Par exemple, si vous la définissez sur Test, vous pouvez appeler une méthode de cette bibliothèque comme suit: Test.libraryMethod().
   Si vous utilisez un identifiant correspondant au nom d'un service existant, tel que MailApp, ou d'une bibliothèque précédemment ajoutée, la dernière bibliothèque que vous avez ajoutée remplace la bibliothèque ou le service existants.
6. Cliquez sur Add (Ajouter).

Utiliser une bibliothèque

Utilisez la bibliothèque incluse comme vous utiliseriez un service par défaut. Par exemple, si Test est l'identifiant de votre bibliothèque, saisissez Test immédiatement suivi d'un point pour afficher la liste des méthodes de la bibliothèque.

Pour ouvrir la documentation de référence d'une bibliothèque incluse, procédez comme suit:

À gauche de l'éditeur de scripts, à côté du nom de la bibliothèque, cliquez sur Plus > Ouvrir dans un nouvel onglet.

Supprimer une bibliothèque

À gauche de l'éditeur de scripts, à côté du nom de la bibliothèque, cliquez sur Plus > Supprimer > Supprimer la bibliothèque.

Si une bibliothèque est supprimée par l'auteur, vous devez toujours la supprimer de votre liste de bibliothèques incluses.

Mettre à jour une bibliothèque

Vous pouvez modifier la version de la bibliothèque ou mettre à jour son identifiant.

1. À gauche de l'éditeur, sous "Bibliothèques", cliquez sur le nom de la bibliothèque.
2. Apportez les modifications nécessaires, puis cliquez sur Enregistrer.

Créer et partager une bibliothèque

Pour utiliser et partager votre projet de script en tant que bibliothèque, procédez comme suit :

1. Créez un déploiement avec versions gérées de votre script.
2. Accordez au moins un accès en lecture à tous les utilisateurs potentiels de la bibliothèque.
3. Attribuez à ces utilisateurs l'ID de script, que vous trouverez sur la page Paramètres du projet .

Bonnes pratiques

Voici quelques consignes à suivre lors de la création d'une bibliothèque:

1. Choisissez un nom explicite pour votre projet, car il est utilisé comme identifiant par défaut lorsque votre bibliothèque est incluse par d'autres utilisateurs.
2. Si vous souhaitez qu'une ou plusieurs méthodes de votre script ne soient pas visibles (ni utilisables) par les utilisateurs de votre bibliothèque, vous pouvez ajouter un trait de soulignement à la fin du nom de la méthode. Par exemple, myPrivateMethod_().
3. Seules les propriétés globales énumérables sont visibles par les utilisateurs de la bibliothèque. Cela inclut les déclarations de fonction, les variables créées en dehors d'une fonction avec var et les propriétés définies explicitement sur l'objet global. Par exemple, Object.defineProperty() avec enumerable défini sur false crée un symbole que vous pouvez utiliser dans votre bibliothèque, mais vos utilisateurs ne peuvent pas y accéder.

4. Si vous souhaitez que les utilisateurs de votre bibliothèque utilisent la saisie semi-automatique de l'éditeur de script et la documentation générée automatiquement, vous devez disposer d'une documentation de type JSDoc pour toutes vos fonctions. Exemple :

   /**
    * Raises a number to the given power, and returns the result.
    *
    * @param {number} base the number we're raising to a power
    * @param {number} exp the exponent we're raising the base to
    * @return {number} the result of the exponential calculation
    */
   function power(base, exp) { ... }
   

Portée des ressources

Lorsque vous travaillez avec des bibliothèques, il existe deux types de ressources: partagées et non partagées. Une ressource partagée signifie que la bibliothèque et le script d'inclusion disposent d'un accès intégré à la même instance de la ressource. Le schéma suivant illustre une ressource partagée à l'aide de l'exemple de propriétés utilisateur:

Une ressource non partagée signifie que la bibliothèque et le script d'inclusion ne disposent d'un accès intégré qu'à leur instance de la ressource. Cependant, une bibliothèque peut fournir un accès à ses ressources non partagées en ayant des fonctions explicites qui s'exécutent sur celles-ci. Voici un exemple de fonction que vous pouvez inclure dans votre bibliothèque pour exposer ses propriétés de script:

  function getLibraryProperty(key) {
    return ScriptProperties.getProperty(key);
  }

Le schéma suivant illustre une ressource non partagée à l'aide de l'exemple des propriétés de script:

Ce tableau répertorie les ressources partagées et non partagées pour référence:

Ressource	Partagé*	Non partagé**	Remarques
Verrouiller			La même instance est visible par tous, y compris les scripts, lorsqu'elle est créée dans la bibliothèque.
Propriétés du script			La même instance est visible par tous, y compris les scripts, lorsqu'elle est créée dans la bibliothèque.
Cache			La même instance est visible par tous, y compris les scripts, lorsqu'elle est créée dans la bibliothèque.
Déclencheurs			Les déclencheurs simples créés dans la bibliothèque ne sont pas déclenchés par le script d'inclusion.
ScriptApp
UiApp
Propriétés utilisateur
Enregistreur et transcription d'exécution
Sites, Sheets et autres conteneurs			Un appel à getActive() renvoie le conteneur du script d'inclusion.
MailApp et GmailApp
* Cela signifie que la bibliothèque ne possède pas sa propre instance de l'élément géographique ou de la ressource, et qu'elle utilise à la place celle créée par le script qui l'a appelée. ** Cela signifie que la bibliothèque possède sa propre instance de la ressource/fonctionnalité, et que tous les scripts qui l'utilisent partagent la même instance et y ont accès.

Tester une bibliothèque

Pour tester votre bibliothèque, utilisez le déploiement "head". Toute personne disposant d'un accès éditeur au script peut utiliser le déploiement "head".

Vous devez encore enregistrer au moins une version de la bibliothèque.

Déboguer une bibliothèque

Lorsque vous utilisez le débogueur dans un projet qui inclut une bibliothèque, vous pouvez entrer dans une fonction de la bibliothèque incluse. Le code s'affiche dans le débogueur en mode lecture seule et dans la bonne version.