Bibliotecas

Una biblioteca es un proyecto de secuencia de comandos cuyas funciones se pueden volver a usar en otras secuencias de comandos.

Cómo obtener acceso a una biblioteca

Para incluir una biblioteca en tu proyecto, debes tener al menos acceso de nivel de vista a ella. Si no eres el autor de la biblioteca que quieres incluir, comunícate con él y solicítale acceso.

Necesitas el ID de secuencia de comandos de la biblioteca que deseas incluir. Cuando tengas acceso a la biblioteca, puedes encontrar el ID de la secuencia de comandos en la página Configuración del proyecto .

Cómo agregar una biblioteca a tu proyecto de secuencia de comandos

  1. A la izquierda del editor de Apps Script, junto a "Bibliotecas", haz clic en Agregar una biblioteca .
  2. En el campo "ID de secuencia de comandos", pega el ID de secuencia de comandos de la biblioteca.
  3. Haz clic en Buscar.
  4. Haz clic en el menú desplegable Versión y selecciona la versión de la biblioteca que se usará.
  5. Comprueba si el nombre del "Identificador" predeterminado es el que quieres usar con esta biblioteca. Este es el nombre que usa la secuencia de comandos para hacer referencia a la biblioteca. Por ejemplo, si la estableces en Test, puedes llamar a un método de esa biblioteca de la siguiente manera: Test.libraryMethod().
  6. Haz clic en Agregar.

Cómo usar una biblioteca

Usa la biblioteca incluida como lo harías con un servicio predeterminado. Por ejemplo, si Test es el identificador de la biblioteca, escribe Test inmediatamente seguido de un punto para ver la lista de métodos de la biblioteca.

Para abrir la documentación de referencia de una biblioteca incluida, sigue estos pasos:

A la izquierda del editor de secuencias de comandos, junto al nombre de la biblioteca, haz clic en Más > Abrir en una pestaña nueva.

Cómo quitar una biblioteca

A la izquierda del editor de secuencia de comandos, junto al nombre de la biblioteca, haz clic en Más > Quitar > Quitar biblioteca.

Cómo actualizar una biblioteca

Puedes cambiar la versión de la biblioteca o actualizar su identificador.

  1. A la izquierda del editor, en "Bibliotecas", haz clic en el nombre de la biblioteca.
  2. Realice los cambios y haga clic en Guardar.

Cómo crear y compartir una biblioteca

Para utilizar y compartir el proyecto de secuencias de comandos como biblioteca, sigue los pasos que se indican a continuación.

  1. Crea una implementación con versión de la secuencia de comandos.
  2. Comparte, al menos, acceso de nivel de vista con todos los usuarios potenciales de la biblioteca.
  3. Proporciona a esos usuarios el ID de la secuencia de comandos, que se puede encontrar en la página Configuración del proyecto .

Prácticas recomendadas

A continuación, se incluyen algunas pautas que debes seguir cuando escribes una biblioteca:

  1. Elige un nombre significativo para tu proyecto, ya que se usará como identificador predeterminado cuando otros incluyan tu biblioteca.
  2. Si quieres que uno o más métodos de la secuencia de comandos no sean visibles (ni útiles) para los usuarios de la biblioteca, puedes terminar el nombre del método con un guion bajo. Por ejemplo, myPrivateMethod_().
  3. Los usuarios de la biblioteca solo pueden ver las propiedades globales que se pueden enumerar. Esto incluye declaraciones de funciones, variables creadas fuera de una función con var y propiedades configuradas explícitamente en el objeto global. Por ejemplo, Object.defineProperty() con enumerable configurado como false crea un símbolo que puedes usar en tu biblioteca, pero los usuarios no pueden acceder a este símbolo.
  4. Si quieres que los usuarios de tu biblioteca usen el autocompletado del editor de secuencias de comandos y la documentación generada automáticamente, debes tener documentación de estilo JSDoc para todas tus funciones. Por ejemplo:

    /**
     * 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) { ... }
    

Alcance de recursos

Cuando trabajas con bibliotecas, hay dos tipos de recursos: compartidos y no compartidos. Un recurso compartido significa que la biblioteca y la secuencia de comandos incluida tienen acceso integrado a la misma instancia del recurso. En el siguiente diagrama, se ilustra un recurso compartido con el ejemplo de Propiedades del usuario:

Recurso compartido

Un recurso no compartido significa que la biblioteca y la secuencia de comandos de inclusión tienen acceso integrado solo a su instancia del recurso. Sin embargo, una biblioteca puede proporcionar acceso a sus recursos no compartidos si tiene funciones explícitas que operan en ellos. A continuación, puedes ver un ejemplo de una función que puedes incluir en la biblioteca para exponer sus propiedades de la secuencia de comandos:

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

En el siguiente diagrama, se ilustra un recurso no compartido con el ejemplo de las propiedades de la secuencia de comandos:

Recurso no compartido

En esta tabla, se enumeran los recursos compartidos y no compartidos como referencia:

Recurso Compartido* No se compartió** Notas
Bloquear La misma instancia es visible para todos, incluidas las secuencias de comandos, cuando se crean en la biblioteca.
Propiedades de secuencia de comandos La misma instancia es visible para todos, incluidas las secuencias de comandos, cuando se crean en la biblioteca.
Caché La misma instancia es visible para todos, incluidas las secuencias de comandos, cuando se crean en la biblioteca.
Activadores La secuencia de comandos de inclusión no activa los activadores simples creados en la biblioteca.
ScriptApp
UiApp
Propiedades del usuario
Transcripción del registrador y la ejecución
Sites, Hojas de cálculo y otros contenedores Una llamada a getActive() muestra el contenedor de la secuencia de comandos incluida.
MailApp y GmailApp
* Esto significa que la biblioteca no tiene su propia instancia de la función o el recurso, sino que utiliza la que creó la secuencia de comandos que la invocó.
** Esto significa que la biblioteca tiene su propia instancia del recurso o la función y que todas las secuencias de comandos que la usan comparten y tienen acceso a esa misma instancia.

Cómo probar una biblioteca

Para probar tu biblioteca, usa la implementación principal. Cualquier persona que tenga acceso de nivel de editor a la secuencia de comandos puede usar la implementación principal.

Cómo depurar una biblioteca

Cuando usas el depurador en un proyecto que incluye una biblioteca, puedes ingresar a una función de la biblioteca incluida. El código se muestra en el depurador en modo de solo lectura y en la versión correcta.