Bibliotecas

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

Una secuencia de comandos que usa una biblioteca no se ejecuta tan rápido como lo haría si todo el código estuviera contenido en un solo proyecto de secuencia de comandos. Aunque las bibliotecas pueden hacer que el desarrollo y el mantenimiento sean más convenientes, úsalas con moderación en proyectos en los que la velocidad sea fundamental. Debido a este problema, el uso de la biblioteca debe limitarse en los complementos de Google Workspace.

Obtén acceso a una biblioteca

Para incluir una biblioteca en tu proyecto, debes tener al menos acceso de nivel de visualización. Si no eres el autor de la biblioteca que quieres incluir, comunícate con él y solicita acceso.

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

Agrega una biblioteca a tu proyecto de secuencia de comandos

A la izquierda del editor de Apps Script, junto a "Bibliotecas", haz clic en Agregar una biblioteca .
En el campo "ID de secuencia de comandos", pega el ID de secuencia de comandos de la biblioteca.
Haz clic en Buscar.
Si encuentras un error, asegúrate de tener al menos acceso de nivel de visualización al proyecto que intentas incluir.
Haz clic en el menú desplegable Versión y selecciona la versión de la biblioteca que deseas usar.
Verifica si el nombre predeterminado "Identificador" es el que deseas usar con esta biblioteca. Este es el nombre que usa tu secuencia de comandos para hacer referencia a la biblioteca. Por ejemplo, si lo configuras como Test, llama a un método de esa biblioteca de la siguiente manera: Test.libraryMethod.
Si usas un nombre de identificador que coincida con el nombre de un servicio ya existente, como MailApp, o una biblioteca agregada anteriormente, la biblioteca que agregaste más recientemente anula el servicio o la biblioteca existentes.
Haz clic en Agregar.

Usa una biblioteca

Usa la biblioteca incluida como usarías un servicio predeterminado. Por ejemplo, si Test es el identificador de tu biblioteca, escribe Test seguido inmediatamente de un punto para ver la lista de métodos en 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.

Quita una biblioteca

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

Si el autor borra una biblioteca, debes quitarla de la lista de bibliotecas incluidas.

Actualiza una biblioteca

Cambia la versión de la biblioteca o actualiza su identificador.

A la izquierda del editor, en "Bibliotecas", haz clic en el nombre de la biblioteca.
Realiza los cambios que desees y haz clic en Guardar.

Crea y comparte una biblioteca

Para usar y compartir tu proyecto de secuencia de comandos como una biblioteca, sigue estos pasos:

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

Prácticas recomendadas

A continuación, se incluyen algunas pautas que puedes seguir cuando escribas una biblioteca:

Elige un nombre significativo para tu proyecto, ya que se usa como identificador predeterminado cuando otros incluyen tu biblioteca.
Para que uno o más métodos de tu secuencia de comandos no sean visibles (ni utilizables) para los usuarios de tu biblioteca, termina el nombre del método con un guion bajo. Por ejemplo, myPrivateMethod_.
Solo las propiedades globales enumerables son visibles para los usuarios de la biblioteca. Esto incluye declaraciones de funciones, variables creadas fuera de una función con var y propiedades establecidas 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 tus usuarios no pueden acceder a él.

Para asegurarte de que los usuarios de tu biblioteca puedan usar la función de autocompletar del editor de secuencias de comandos y la documentación generada automáticamente, incluye 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

Hay dos tipos de recursos cuando trabajas con bibliotecas: compartidos y no compartidos. Un recurso compartido significa que tanto la biblioteca como la secuencia de comandos que la incluye tienen acceso integrado a la misma instancia del recurso. En el siguiente diagrama, se ilustra un recurso compartido con el ejemplo de las propiedades del usuario:

Recurso compartido

Un recurso no compartido significa que tanto la biblioteca como la secuencia de comandos que la incluye 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, se muestra un ejemplo de una función que incluirías en tu biblioteca para exponer sus propiedades de secuencia de comandos:

  function getLibraryProperty(key) {
    const scriptProperties = PropertiesService.getScriptProperties();
    return scriptProperties.getProperty(key);
  }

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

Ejemplo de un recurso no compartido

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

Recurso	Compartido*	No compartido**	Notas
Bloquear			La misma instancia es visible para todas las secuencias de comandos incluidas cuando se crea en la biblioteca.
Propiedades de secuencia de comandos			La misma instancia es visible para todas las secuencias de comandos incluidas cuando se crea en la biblioteca.
Caché			La misma instancia es visible para todas las secuencias de comandos incluidas cuando se crea en la biblioteca.
Activadores			La secuencia de comandos incluida no activa los activadores simples creados en la biblioteca.
ScriptApp
UiApp
Propiedades del usuario
Registrador y transcripción de ejecución
Sitios, 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 y, en su lugar, usa 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 usan la biblioteca comparten y tienen acceso a esa misma instancia.

Prueba 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.

Aún necesitas guardar al menos una versión de la biblioteca.

Depura una biblioteca

Cuando depuras una secuencia de comandos que incluye una biblioteca, no puedes ingresar al código de la biblioteca ni establecer puntos de interrupción en ella. Si intentas ingresar a una función de biblioteca en modo de depuración, el depurador omite la función y pasa a la siguiente línea de la secuencia de comandos de llamada.

El uso de HEAD (modo de desarrollo) para la versión de la biblioteca no permite ingresar a la biblioteca ni alcanzar puntos de interrupción dentro de ella.

Para depurar el código de la biblioteca, usa uno de los siguientes métodos:

Depurar desde el proyecto de biblioteca: Abre el proyecto de secuencia de comandos de la biblioteca en el editor de Apps Script. Para probar las funciones de la biblioteca con argumentos específicos, crea una función "test" temporal dentro del proyecto de la biblioteca que llame a las funciones de la biblioteca y, luego, ejecuta esa función de prueba en modo de depuración.
Registro: Usa console.log() dentro de las funciones de la biblioteca para generar información en los registros de ejecución. Cuando otra secuencia de comandos llama a la biblioteca, estos registros aparecen en los registros de ejecución de la secuencia de comandos de llamada.