Bibliotecas

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

Advertencia: 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 facilitar el desarrollo y el mantenimiento, úsalas con moderación en proyectos en los que la velocidad sea fundamental. Debido a este problema, el uso de bibliotecas debe limitarse en los complementos.

Cómo obtener acceso a una biblioteca

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

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

Agrega 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 la secuencia de comandos", pega el ID de la secuencia de comandos de la biblioteca.
3. Haz clic en Buscar.
   Si encuentras un error, asegúrate de tener al menos acceso a nivel de vista al proyecto que intentas incluir.
4. Haz clic en el menú desplegable Versión y selecciona la versión de la biblioteca que deseas usar.
5. Verifica si el nombre predeterminado "Identifier" es el que deseas usar con esta biblioteca. Este es el nombre que usa la secuencia de comandos para hacer referencia a la biblioteca. Por ejemplo, si lo configuras en Test, puedes llamar a un método de esa biblioteca de la siguiente manera: Test.libraryMethod().
   Si usas un nombre de identificador que coincide con el nombre de un servicio que ya existe, como MailApp, o una biblioteca que ya agregaste, la biblioteca que agregaste más recientemente anula el servicio o la biblioteca existentes.
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 tu 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 secuencia 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.

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

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.

Crea y comparte una biblioteca

Para usar y compartir tu proyecto de secuencia de comandos como una biblioteca, sigue los pasos que se indican a continuación.

1. Crea una implementación con control de versiones de tu secuencia de comandos.
2. Comparte al menos el acceso a 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 encuentra en la página Configuración del proyecto .

Prácticas recomendadas

Estos son algunos lineamientos que debes seguir cuando escribas una biblioteca:

1. Elige un nombre significativo para tu proyecto, ya que se usa como identificador predeterminado cuando otras personas incluyen tu biblioteca.
2. Si deseas que uno o más métodos de tu secuencia de comandos no sean visibles (ni usables) para los usuarios de tu biblioteca, puedes finalizar el nombre del método con una línea baja. Por ejemplo, myPrivateMethod_().
3. Solo los usuarios de la biblioteca pueden ver las propiedades globales enumerables. Esto incluye las declaraciones de función, las variables creadas fuera de una función con var y las propiedades establecidas de forma explícita en el objeto global. Por ejemplo, Object.defineProperty() con enumerable configurado en false crea un símbolo que puedes usar en tu biblioteca, pero los usuarios no pueden acceder a él.

4. Si deseas que los usuarios de tu biblioteca usen la función de autocompletado del editor de secuencia de comandos y la documentación generada automáticamente, debes tener documentación al estilo de 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 los recursos

Cuando trabajas con bibliotecas, existen dos tipos de recursos: compartidos y no compartidos. Un recurso compartido significa que tanto la biblioteca como la secuencia de comandos de inclusión tienen un 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:

Un recurso no compartido significa que tanto la biblioteca como 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. Este es 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:

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

Recurso	Compartido*	No compartidos**	Notas
Bloquear			Todos pueden ver la misma instancia, incluidas las secuencias de comandos, cuando se crean en la biblioteca.
Propiedades de secuencia de comandos			Todos pueden ver la misma instancia, incluidas las secuencias de comandos, cuando se crean en la biblioteca.
Caché			Todos pueden ver la misma instancia, 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
Registrador y transcripción de la ejecución
Sitios, Hojas de cálculo y otros contenedores			Una llamada a getActive() muestra el contenedor de la secuencia de comandos de inclusión.
MailApp y GmailApp
* Esto significa que la biblioteca no tiene su propia instancia de la función o el recurso, sino que 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 a la secuencia de comandos a nivel del editor puede usar la implementación principal.

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

Cómo depurar una biblioteca

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