Aspectos básicos de Apps Script con Hojas de cálculo de Google n.o 1: Macros y funciones personalizadas

1. Te damos la bienvenida a Apps Script

¿Qué es Apps Script?

Apps Script es una plataforma de desarrollo de aplicaciones rápida que le permite automatizar, personalizar y extender su experiencia en Google Workspace. Con Apps Script, puede ahorrar tiempo y esfuerzo mediante la optimización de los trabajos pesados o complejos dentro de Google Workspace.

Las funciones de Apps Script incluyen lo siguiente:

• Los servicios integrados de Apps Script te permiten leer, actualizar y manipular los datos de tu aplicación de Google Workspace con secuencias de comandos.
• Puedes crear secuencias de comandos con el editor de código integrado en el navegador de Apps Script, ya que no es necesario instalar ni ejecutar software de desarrollo de código.
• Puedes diseñar interfaces de usuario para editores de Google Workspace que te permiten activar secuencias de comandos directamente desde esos editores mediante elementos de menú, diálogos y barras laterales.

En esta lista de reproducción del Aspectos básicos de Apps Script con Hojas de cálculo de Google, se enseñan los aspectos básicos de Apps Script y cómo se usa para mejorar su experiencia en Hojas de cálculo de Google. Este codelab se enfoca en enseñar los conceptos básicos de Apps Script.

El servicio de hojas de cálculo

Puede usar Apps Script a fin de extender las Hojas de cálculo de Google para ahorrar tiempo y esfuerzo. Apps Script proporciona el servicio de Hojas de cálculo, que permite que las secuencias de comandos interactúen con sus archivos de Hojas de cálculo de Google y los datos que contienen. Puedes usar este servicio para automatizar las siguientes tareas comunes de las hojas de cálculo:

• Crea o modifica una hoja de cálculo.
• Lee y actualiza datos, fórmulas y formatos de celdas.
• Crea botones y menús personalizados.
• Importar y exportar datos desde otras aplicaciones de Google o fuentes de terceros
• Compartir y controlar el acceso a las hojas de cálculo

Qué aprenderás

Esta lista de reproducción abarca todos los temas que necesitarás para comenzar a usar Apps Script con Hojas de cálculo de Google:

1. Macros y funciones personalizadas
2. Hojas de cálculo, hojas de cálculo y rangos
3. Cómo trabajar con datos
4. Formato de datos
5. Cómo representar y presentar datos en Presentaciones

Los codelabs de esta lista de reproducción se deben leer en orden, así que comienza con este y complétalos en secuencia para obtener la mejor experiencia de aprendizaje.

Avanza a la siguiente sección para obtener más información sobre el contenido de este codelab.

2. Introducción

Te damos la bienvenida al primer codelab de esta lista de reproducción. En este codelab, aprenderás los conceptos básicos del uso de Apps Script con Hojas de cálculo de Google. Específicamente, este codelab se enfoca en dos conceptos clave: macros y funciones personalizadas.

Una macro es una serie de acciones registradas dentro de Hojas de cálculo de Google. Una vez grabada, puedes activar una macro para repetir esas acciones más tarde con un elemento de menú o una combinación de teclas. Puede crear y actualizar sus propias macros tanto en Hojas de cálculo de Google como en el editor de código de Apps Script.

En el editor de código de Apps Script, también puede crear funciones personalizadas. Al igual que con las funciones integradas que ofrece Hojas de cálculo (como SUM o AVERAGE), Apps Script le permite escribir sus propias funciones personalizadas para operaciones simples y de nicho (como conversiones o concatenación de strings). Una vez creadas, puede llamar a estas funciones en Hojas de cálculo como lo haría con una función integrada. Las funciones personalizadas también se pueden usar en fórmulas de celdas que escribas y combinarlas con otras funciones según sea necesario.

Sigue leyendo para obtener más información sobre los conceptos y requisitos de este codelab.

Qué aprenderás

• Cómo crear una secuencia de comandos para Hojas de cálculo de Google
• Cómo navegar por el editor de Apps Script
• Cómo crear y actualizar macros
• Cómo crear su primera función personalizada de Hojas de cálculo

Requisitos

• Conocimientos básicos sobre JavaScript
• Conocimientos básicos de Hojas de cálculo de Google
• Capacidad para leer Hojas de cálculo A1 Notation

Nota: Apps Script se basa en JavaScript. Si recién empiezas a usar JavaScript, Codecademy te ofrece un curso gratuito de JavaScript introductorio. Si bien Google no creó este curso, debe cubrir todo lo que debes saber.

Terminaste con las presentaciones. Vaya a la siguiente sección para comenzar a trabajar con macros.

3. Cómo crear una macro en Hojas de cálculo

Por lo general, cuando trabaja en hojas de cálculo, puede ingresar a un bucle de acciones repetitivas (copiar valores de celda, aplicar formato, crear fórmulas, etc.), que pueden volverse tediosas y generar errores. Para automatizar las acciones repetidas, Hojas de cálculo de Google proporciona macros. Las macros te permiten grabar una serie de acciones en una hoja de cálculo. Con una macro grabada, puedes repetir las mismas acciones en otro lugar de la hoja de cálculo con solo presionar una tecla de acceso directo.

En esta sección, aprenderás a crear una macro en Hojas de cálculo. En la siguiente sección, verá cómo se compilan las macros con Apps Script.

Antes de comenzar

Antes de continuar, necesitas una hoja de cálculo con algunos datos. Te proporcionamos una: haz clic en este vínculo para copiar la hoja de datos y, luego, en Crear una copia.

Se guarda una copia de la hoja de cálculo de ejemplo en su carpeta de Google Drive y se le asigna el nombre "Copia de las 10 películas más taquilleras de mayor recaudación" (2018).

Cómo crear una macro

Ahora que tiene una hoja de cálculo para trabajar, puede grabar una macro en Hojas de cálculo de Google. En este ejemplo, creará una macro con el formato de una fila de encabezado para sus datos. Solo debe seguir estos pasos:

1. Haga clic en la celda A1 para colocar el cursor en la fila. Esta es la fila del encabezado.
2. En el menú, seleccione Extensiones > Macros > Grabar macros.

Una vez que comienzas a grabar, Hojas de cálculo de Google recuerda cada acción que realizas dentro de la hoja de cálculo: destacar celdas, agregar datos, cambiar a diferentes hojas, formato, etc. Estas acciones se convierten en la "secuencia de comandos" que se repite una vez que guarda y activa la macro más adelante.

3. En el diálogo Macro, selecciona Relative Reference.

Términos clave: Las macros pueden usar dos tipos de referencias en Hojas de cálculo para hacer referencia a celdas específicas. Las referencias absolutas se fijan en las ubicaciones exactas registradas (por ejemplo, celda A5), mientras que las referencias relativas se aplican utilizando la selección actual del usuario como punto de partida (por ejemplo, la cuarta celda hacia abajo de la selección actual).

En este codelab, se te pedirá que uses referencias relativas para tus macros.

4. Selecciona la fila 1.

5. Cambia el color de la fila superior Color de relleno de blanco a magenta oscuro 3.

6. Cambia el Color de texto de la fila superior de negro a blanco.

7. Para aplicar negrita al texto, presiona Ctrl+B (o Cmd+B en macOS).
8. Para inmovilizar la fila superior, selecciona Ver > inmovilizar > 1 fila.

9. En el diálogo de la macro, haga clic en Guardar. Un nuevo diálogo te pedirá que le asignes un nombre a la macro. Ingresa el nombre (Encabezado) y haz clic en Guardar (Save).

Con la interfaz de usuario de Hojas de cálculo, creaste una macro especializada para dar formato a los encabezados.

Activa la macro

Para aplicar su nueva macro en Hojas de cálculo, siga estas instrucciones:

1. Para crear una hoja, haz clic en Agregar hoja .

2. En la hoja nueva, agrega texto a A1:C2. No dudes en seguir estos ejemplos:

3. Destaque la primera fila.

4. Para aplicar la macro al área seleccionada, haga clic en Extensiones y Macros en Encabezado.
5. Sigue las instrucciones en pantalla para autorizar la macro.

Nota: Si usas una cuenta de gmail.com, es posible que también veas un diálogo de app sin verificar la primera vez que uses la secuencia de comandos. Google utiliza esta información para advertir a los usuarios que podrían utilizar código de autores desconocidos o no confiables. Si ves este diálogo, te recomendamos continuar, ya que eres el autor de la secuencia de comandos. Sigue las indicaciones en pantalla para seguir autorizando la secuencia de comandos. El proceso para obtener este permiso se denomina autorización.

6. Repita el Paso 4 para volver a ejecutar la macro (si se autoriza, se detendrá la primera ejecución).

¡Felicitaciones! Aprendiste a aplicar macros en Hojas de cálculo. La hoja de cálculo debería verse de la siguiente manera:

Las macros te permiten crear hojas de cálculo de forma eficiente y, en la próxima parte de este codelab, aprenderás a potenciar tus macros. Este es el secreto: cuando grabas una macro, lo que en realidad haces es escribir código de Apps Script. En segundo plano, Hojas de cálculo construye el código que coincide con las acciones de la macro. En la siguiente sección, aprenderás a modificar el código directamente con el editor en el navegador de Apps Script.

4. Macros en el editor de secuencias de comandos

A medida que crea una macro, Hojas de cálculo de Google guarda sus acciones como una función de Apps Script. Cuando activa la macro, Hojas de cálculo de Google llama a la función de Apps Script para aplicar esas acciones en el mismo orden.

Editor de secuencias de comandos

Ahora que creaste una macro, puedes ver su código. Para ver la secuencia de comandos de macros, haga clic en Extensiones > Apps Script a fin de abrir el editor de código del navegador para Apps Script.

El editor de secuencias de comandos le permite escribir código en Apps Script y ejecutar esa secuencia de comandos en los servidores de Google.

Nota: Las macros y secuencias de comandos que creas en este codelab se adjuntan al archivo de Hojas de cálculo de Google en el que operan y se puede acceder a ellas en cualquier momento desde el menú de Extensiones de Hojas de cálculo de Google. Las secuencias de comandos adjuntas a una hoja de cálculo de Google como esta se denominan vinculación de contenedores.

Análisis de macro.gs

Revise la secuencia de comandos actual. Hojas de cálculo creó el archivo de secuencia de comandos macros.gs cuando registró la macro Header y la llenó con una función de Apps Script llamada Header. Cuando activa la macro Header, Hojas de cálculo ejecuta esta función.

Observe la siguiente imagen para familiarizarse con la estructura de su función de macro en Apps Script. Si grabaste los pasos en un orden diferente o hiciste clic en la hoja de cálculo mientras grabaste, es posible que tu código se vea un poco diferente.

La primera línea es un comentario de anotación que afecta la autorización:

/** @OnlyCurrentDoc */

La mayoría de las secuencias de comandos solicitan al usuario algunos permisos para poder ejecutarse. Estos permisos controlan lo que el usuario permite que la secuencia de comandos haga. Cuando el comentario @OnlyCurrentDoc está presente en un proyecto de secuencia de comandos, Apps Script solo solicita permiso para acceder a la hoja de cálculo actual y actualizarla. Sin este comentario, Apps Script solicitará permiso para acceder y actualizar todas las hojas de cálculo del usuario. Siempre es recomendable incluir esta anotación cuando trabajas con un solo archivo. La grabadora de macros agrega este comentario automáticamente.

Para comprender cómo Apps Script representa las instrucciones de tu macro, consulta la función:

function Header(){
  var spreadsheet = SpreadsheetApp.getActive();
  var sheet = spreadsheet.getActiveSheet();
  sheet.getRange(
    spreadsheet.getCurrentCell().getRow(),
    1, 1, sheet.getMaxColumns()).activate();
  spreadsheet.getActiveRangeList().setBackground('#4c1130')
  .setFontColor('#ffffff')
  .setFontWeight('bold');
  spreadsheet.getActiveSheet().setFrozenRows(1);
};

Este código se ejecuta cuando activas la macro Header. Después de function, la etiqueta Header() define el nombre de la función y sus parámetros. Reconocer que Header() no requiere parámetros, ya que las funciones macro de Apps Script no necesitan entradas. Las llaves siempre encierran el cuerpo de una función en Apps Script.

Más adelante, en los codelabs de esta lista de reproducción, se explican las clases y los conceptos necesarios para crear la macro. Por ahora, puede consultar las siguientes descripciones de código para tener una idea general de sus componentes y su función en la construcción de la macro. Considera la primera línea:

var spreadsheet = SpreadsheetApp.getActive();

Aquí, getActive() muestra un objeto que representa el archivo de hoja de cálculo activo actual en Hojas de cálculo y lo establece en la nueva variable spreadsheet.

var sheet = spreadsheet.getActiveSheet();
sheet.getRange(
    spreadsheet.getCurrentCell().getRow(),
    1, 1, sheet.getMaxColumns()).activate();

Estas líneas corresponden a la acción de hacer clic en la primera fila para destacarla. Esto se denomina activación. La primera línea almacena la hoja actual en la variable sheet, mientras que la segunda línea obtiene la primera fila completa usando el método getRange() y, luego, llama a activate() para activarla. La primera fila se especifica con los números específicos de filas y columnas. La llamada spreadsheet.getCurrentCell().getRow() muestra el número de la fila actual, mientras que sheet.getMaxColumns() muestra el número máximo de columnas en la hoja.

spreadsheet.getActiveRangeList().setBackground('#4c1130')
.setFontColor('#ffffff')
.setFontWeight('bold');

Este fragmento de código se vuelve más complejo. Para llamar eficazmente a los métodos con spreadsheet, el código apila tres métodos en getActiveRangeList() para evitar que el código llame de manera redundante a este método spreadsheet más de una vez. A medida que codifiques más con Apps Script, te familiarizarás más con esta convención de llamar a varios métodos de una clase (lo que también se conoce como encadenamiento de métodos). Por ahora, puedes leer lo siguiente para obtener explicaciones breves sobre cada método en el bloque de código:

• getActiveRangeList() muestra el elemento RangeList activo actual en spreadsheet. En este caso, es simplemente la primera fila que activó la línea anterior.
• Los métodos setBackground(color) y setFontColor(color) cambian los atributos de color de las celdas del rango activo.
• setFontWeight(fontWeight) ajusta el grosor de la fuente de las celdas del rango activo.

Por último, la línea final congela la primera fila de la macro:

spreadsheet.getActiveSheet().setFrozenRows(1);

Esa es la secuencia de comandos que generó cuando grabó la macro. No te preocupes por ningún método o término desconocido que se mencionó anteriormente. La descripción tiene como objetivo que pienses en algunas de las ideas en las que se enfoca Apps Script en una función macro común, además de los temas que se abordan en los codelabs futuros.

La siguiente sección se centra en la manipulación del código de la función Header() para mostrar cómo puedes usar el editor de secuencias de comandos a fin de personalizar aún más las macros.

Personalice macros con Apps Script

El editor de Apps Script muestra la macro que creó anteriormente en Hojas de cálculo de Google. Si ajustas el contenido del cuerpo de la función, puedes personalizar aún más las instrucciones de tu macro para realizar acciones diferentes o adicionales. En los siguientes ejercicios, se demuestran varias formas de manipular macros con el editor de secuencias de comandos.

Cambiar las celdas afectadas

Supongamos que quiere modificar su macro de modo que solo afecte a las primeras 10 columnas de la primera fila en lugar de afectar a toda la fila. Puedes borrar la macro y volver a grabarla. Sin embargo, si usas el editor de Apps Script, podrás realizar esos cambios directamente. A continuación, le mostramos una manera de hacerlo:

1. En el editor de secuencias de comandos, reemplaza sheet.getMaxColumns() por 10. Esta edición cambia el rango de celdas que afecta la macro en la hoja de cálculo.

/** @OnlyCurrentDoc */

function Header(){
  var spreadsheet = SpreadsheetApp.getActive();
  var sheet = spreadsheet.getActiveSheet();
  sheet.getRange(
    spreadsheet.getCurrentCell().getRow(),
    1, 1, 10).activate();
    /* sheet.getMaxColumns() replaced with 10.*/
  spreadsheet.getActiveRangeList().setBackground('#4c1130')
  .setFontColor('#ffffff')
  .setFontWeight('bold');
  spreadsheet.getActiveSheet().setFrozenRows(1);
}

2. Para guardar la secuencia de comandos, haz clic en Guardar .
3. Para cambiar el nombre de tu proyecto, ingresa "Macros y funciones personalizadas" como nombre del proyecto nuevo y haz clic en Cambiar nombre.
4. Para crear una hoja, en Hojas de cálculo, haz clic en Agregar hoja .

5. En el editor de secuencias de comandos, en la lista de funciones, selecciona Header y haz clic en Ejecutar.

En su nueva hoja, debería ver el siguiente resultado:

Al modificar el rango activo o de destino, la macro ahora solo afectará a una parte de la primera fila. Muchos métodos de Apps Script toman un rango o una notación A1 como parámetro para especificar sobre qué celdas.

A continuación, aprenderemos sobre cómo personalizar los colores de las macros.

Cómo cambiar los colores de su macro

Para ayudarte a diseñar el esquema de colores de macros u otros elementos de Hojas de cálculo, Apps Script puede modificar el color de relleno o texto de un rango. Siga las instrucciones que aparecen a continuación para aprender a personalizar los colores de su macro.

Estas instrucciones se enfocan en cambiar el color de fondo de la macro:

1. En Hojas de cálculo, vuelva a la hoja que contiene los datos originales (Hoja 1).
2. Haz clic en la primera fila para destacarla.
3. En el editor de secuencias de comandos, reemplaza el color de fondo #4c1130 por #afeeee. Estos valores representan diferentes colores mediante la notación triple hexadecimal.

/** @OnlyCurrentDoc */

function Header(){
  var spreadsheet = SpreadsheetApp.getActive();
  var sheet = spreadsheet.getActiveSheet();
  sheet.getRange(
    spreadsheet.getCurrentCell().getRow(),
    1, 1, 10).activate();
  spreadsheet.getActiveRangeList().setBackground('#afeeee')
    /* #4c1130 replaced with #afeeee.*/
  .setFontColor('#ffffff')
  .setFontWeight('bold');
  spreadsheet.getActiveSheet().setFrozenRows(1);
}

4. Para guardar la secuencia de comandos, haz clic en Guardar .
5. En la lista de funciones, selecciona Header y haz clic en Ejecutar.

En Hojas de cálculo, el relleno del fondo de las primeras 10 columnas de la primera fila cambia de color a color turquesa personalizado:

Si cambias la notación de colores hexadecimales en los parámetros de setBackground(color) de #4c1130 (magenta oscuro 3) a #afeeee (turquesa claro, una opción a la que no se puede acceder en Hojas de cálculo, cambia el atributo de color del color de fondo de la macro).

Modificaste el color de fondo que estableció la macro. Si también quieres cambiar el color del texto, modifica el segundo código de color.

1. En Hojas de cálculo, haga clic en la primera fila para asegurarse de que siga destacada.
2. En el editor de secuencias de comandos, reemplaza el color de la fuente #ffffff por #191970. Esto hace que la macro establezca un color de fuente azul marino.

/** @OnlyCurrentDoc */

function Header(){
  var spreadsheet = SpreadsheetApp.getActive();
  var sheet = spreadsheet.getActiveSheet();
  sheet.getRange(
    spreadsheet.getCurrentCell().getRow(),
    1, 1, 10).activate();
  spreadsheet.getActiveRangeList().setBackground('#afeeee')
  .setFontColor('#191970')/* #ffffff replaced with #191970.*/
  .setFontWeight('bold');
  spreadsheet.getActiveSheet().setFrozenRows(1);
}

3. Para guardar la secuencia de comandos, haz clic en Guardar .
4. En la lista de funciones, selecciona Header y haz clic en Ejecutar.

Regrese a Hojas de cálculo para ver que el color del texto de la fila de encabezado ahora es azul marino.

Ya vio cómo las macros en realidad son acciones de Hojas de cálculo registradas como código de Apps Script. En la siguiente sección, puede ver otra forma en que Apps Script puede ayudarlo a trabajar con Hojas de cálculo de Google: funciones personalizadas.

5. Codifica la primera secuencia de comandos: funciones personalizadas

Al igual que la mayoría de las aplicaciones de hojas de cálculo, Hojas de cálculo de Google tiene varias funciones de fórmula integradas, como =SUM(), que permiten realizar cálculos rápidos en los datos correspondientes. Las funciones personalizadas son simplemente funciones que usted especifica mediante Apps Script. Una vez que hayas definido una función personalizada, puedes usarla en cualquier lugar de la hoja de cálculo, al igual que una función integrada.

En esta sección, se muestra cómo crear una función personalizada en Apps Script que genere una conversión monetaria.

Cree un archivo de secuencia de comandos

Con el mismo proyecto de hoja de cálculo y de secuencias de comandos de la sección Macros, siga estas instrucciones para crear una nueva secuencia de comandos (que finalmente puede usar para crear su primera función personalizada):

1. Para crear un archivo de Apps Script, vuelva al editor de secuencias de comandos.
2. Junto a Archivos, haz clic en Agregar un archivo > Script.
3. Asígnale el nombre customFunctions al archivo de secuencia de comandos nuevo y presiona Intro. (Apps Script agrega automáticamente una extensión .gs al nombre del archivo de secuencia de comandos).

Aparecerá una nueva pestaña llamada customFunctions.gs.

Ahora que creaste una secuencia de comandos específica para funciones personalizadas, puedes llenarla de código.

Convertir dólares estadounidenses a francos suizos

Supongamos que deseas modificar los datos de "Las 10 mejores películas más taquilleras de 2018" para mostrar no solo los valores brutos a nivel mundial en dólares estadounidenses, sino también en francos suizos. Con las funciones personalizadas, puedes hacerlo fácilmente. En el siguiente ejercicio, se demuestra cómo crear una función personalizada para convertir de forma matemática tus valores en dólares en valores de francos.

Antes de poder escribir su primera función personalizada, modifique su conjunto de datos para permitir que la función demuestre un resultado adecuado. Para ello, siga estos pasos:

1. En Hojas de cálculo, haga clic con el botón derecho en la columna H.
2. En el menú resultante, haz clic en Insertar 1 a la derecha.

3. Etiquete la columna "Worldwide_Gross (Suiss francs)" en la celda I1.

Ahora tiene una columna que puede almacenar los resultados de su función personalizada de conversión. Luego, puedes usar el editor de secuencias de comandos para crear tu primera función personalizada.

4. En customFunctions.gs, reemplaza el código de myFunction() por lo siguiente:

/**
 * Converts US dollars to Swiss francs.
 *
 * @param {number} dollars The total number of dollars.
 * @return {number} swissFrancs The converted total of Swiss francs.
 * @customfunction
 */
function USDTOCHF(dollars){
  var swissFrancs = dollars * .99; 
  return swissFrancs;
}

Este es el código que convertirá los dólares estadounidenses a francos suizos. Pruebe las siguientes instrucciones y observe cómo puede ejecutar una función personalizada en las hojas.

5. Para guardar la secuencia de comandos, haz clic en Guardar .
6. En Hojas de cálculo, seleccione la celda I2.
7. En la barra de funciones, ingresa =USDTOCHF(H2).

Para aplicar la fórmula al resto de las celdas de la columna, sigue estos pasos:

8. Mueva el cursor a la esquina inferior derecha de la celda I2 y seleccione el pequeño cuadro azul (el cursor debería transformarse en cuando apunte al cuadro azul).
9. Arrastre el cuadro azul hacia abajo para destacar el rango I3:I11.

La columna I ahora muestra las conversiones en francos suizos de los valores en dólares estadounidenses en la columna H.

¡Felicitaciones! Creaste tu primera función personalizada. En la siguiente sección, se explica el código que comprende USDTOCHF().

Análisis de USDTOCHF()

En los comentarios iniciales, se detalla el propósito del código:

/**
 * Converts US dollars to Swiss francs.
 *
 * @param {number} dollars The total number of dollars.
 * @return {number} swissFrancs The provided value in Swiss francs.
 * @customfunction
 */

Los bloques de comentarios como este se utilizan con frecuencia en la programación para explicar qué hacen las funciones.

En este comentario, puedes identificar dos partes: la descripción de la función (para convertir dólares en francos) y las anotaciones que describen los parámetros y el tipo de datos que se muestra.

Con las anotaciones, Apps Script utiliza JSDoc para ayudarlo a documentar y crear sugerencias de autocompletado para su código. A continuación, puedes ver cómo cada anotación utilizada en USDTOCHF() te ayuda con el desarrollo de Apps Script:

• @param: Puedes usar la anotación @param para describir cada parámetro que se pasa a la función.
• @return: Puedes usar la anotación @return para describir lo que muestra la función.
• @customfunction: Siempre debes agregar @customfunction en cualquier comentario del documento de funciones personalizadas. Esta anotación notifica a Hojas de cálculo para que autocomplete su función personalizada de la misma manera que Hojas de cálculo completa automáticamente las funciones integradas cuando ingresa el nombre de una función en una celda, como se muestra a continuación:

Observa que el texto que aparece en la ventana emergente de autocompletar coincide exactamente con el texto de descripción que colocaste en el bloque de comentarios. Para que sus funciones personalizadas sean más fáciles de usar, asegúrese de que las descripciones que crea estén bien escritas y completas.

Luego, enfócate en el código de la función USDTOCHF():

function USDTOCHF(dollars){
  var swissFrancs = dollars * .99; 
  return swissFrancs;
}

Como se mencionó anteriormente, USDTOCHF() toma el valor de la variable numérica, lo multiplica por un tipo de cambio fijo y muestra un valor convertido a francos suizos en la variable numérica swissFrancs. El parámetro de entrada es el valor contenido en la celda especificada cuando se agrega la función personalizada a una celda. En este ejemplo, los importes en dólares de entrada provienen de la columna H. El valor de resultado swissFrancs se coloca en la celda de la función (columna I en este ejemplo).

Las funciones personalizadas pueden funcionar con valores numéricos o de string, como se verá en la siguiente sección.

Concatena un prefijo de string

Supongamos que quieres que el resultado numérico de la función USDTOCHF() incluya el prefijo de francos suizos CHF. Puedes hacerlo con Apps Script usando el operador de concatenación (+),, como se muestra en las siguientes instrucciones:

1. En el editor de secuencias de comandos, actualiza la anotación @return para mostrar la string en lugar del número.
2. Cambia return swissFrancs por return 'CHF' + swissFrancs.

El operador + agrega la string CHF al principio del valor contenido en swissFrancs. Tu código debería verse de la siguiente manera:

/**
 * Converts US dollars to Swiss francs.
 *
 * @param {number} dollars The total number of dollars.
 * @return {string} swissFrancs The provided value in Swiss francs.
 * @customfunction
 */
function USDTOCHF(dollars){
  var swissFrancs = dollars * .99;
  return 'CHF' + swissFrancs;
}

3. Para guardar la secuencia de comandos, haz clic en Guardar .

La string de francos suizos ahora agrega el prefijo de los valores de la columna I:

La función personalizada ahora no solo convierte dólares estadounidenses a francos suizos, sino que también genera la moneda con un prefijo de string.

Avanzado: Recuperar datos externos

Este es un buen comienzo para una función personalizada básica, pero en este ejemplo se supone que el tipo de cambio de dólares a francos suizos es constante. Supongamos que quiere usar el tipo de cambio actual, por lo que cada vez que se vuelve a cargar la hoja, los valores se vuelven a calcular para representar la conversión actual. Para ello, necesitas una forma de descubrir cuál es el tipo de cambio actual. Esa información no está disponible fácilmente en Hojas de cálculo de Google, pero, afortunadamente, puedes usar Apps Script para obtenerla.

Puede usar el siguiente código para obtener el porcentaje de conversiones actual de francos suizos a dólares estadounidenses:

function USDTOCHF(dollars){
  // Gets a cache that is common to all users of the script.
  var cache = CacheService.getScriptCache();

  // Accesses the memory location (rates.CHF) of the script cache.
  var rate = cache.get('rates.CHF');

  // If a cache miss occurs, the program fetches the current
  // CHF rate from an API and stores the rate in the cache
  // for later convenience.
  if (!rate) {
    var response =
UrlFetchApp.fetch('https://api.exchangeratesapi.io/latest?base=USD');
    var result = JSON.parse(response.getContentText());
    rate = result.rates.CHF;
    cache.put('rates.CHF', rate);
  }
  // Converts dollars to CHF according to the latest rate.
  var swissFrancs = dollars * rate;
  // Returns the CHF value.
  return 'CHF' + swissFrancs;
}

Este código recupera la tasa de cambio actual de un servidor de información financiera con una API de tasa de cambio de terceros. Para ello, se usan los servicios de Apps Script, como UrlFetchApp y CacheService. Esos conceptos avanzados están fuera del alcance de este codelab específico, pero puedes comenzar a ver la versatilidad de Apps Script para automatizar tareas complejas en Hojas de cálculo de Google.

Lineamientos sobre funciones personalizadas

Felicitaciones por completar los ejercicios de funciones personalizadas. Cuando usas funciones personalizadas en tus proyectos, es importante que entiendas que tienen ciertas restricciones. En la siguiente lista, se resumen las limitaciones detalladas en la guía Funciones personalizadas en Hojas de cálculo de Google:

• No crees funciones personalizadas que requieran autorización del usuario. En su lugar, crea tus funciones personalizadas para completar tareas más sencillas, como cálculos de datos de muestra, edición de texto, etc. Ve a Usa servicios de Apps Script.
• No asignes un nombre personalizado a una función personalizada como lo haces con otra función integrada, o bien debes terminar con un guion bajo como nombre. Revisa los lineamientos para asignar nombres.
• No pases argumentos variables a funciones personalizadas. Solo puedes pasar valores deterministas (fijos) a funciones personalizadas como argumentos. Pasar argumentos variables, como el resultado de =RAND(), interrumpirá la función personalizada. Consulta los lineamientos de argumentos.
• No crees funciones que tarden más de 30 segundos en completarse. Si tardan más, ocurrirá un error, así que mantén el código de la función simple y limitado en el alcance. Lo mejor es mantener los cálculos realizados en funciones personalizadas de la manera más sencilla posible. Consulte los Lineamientos sobre los valores que se muestran.

Ahora puede mejorar sus hojas de cálculo con el editor de secuencias de comandos para trabajar con macros y crear funciones personalizadas. En la siguiente sección, puedes revisar lo que aprendiste y lo que puedes hacer a continuación para mejorar tus habilidades de programación.

6. Conclusión

Completaste el primer codelab de Aspectos básicos de Apps Script con Hojas de cálculo de Google. Al crear y editar macros y funciones personalizadas de Hojas de cálculo, aprendiste los conceptos básicos de Apps Script. Puedes ampliar tus conocimientos sobre Apps Script en el siguiente codelab.

¿Te resultó útil este codelab?

Sí No

Temas abordados

• Conceptos básicos de Apps Script
• Cómo navegar por el editor de secuencias de comandos
• Cómo crear y actualizar macros de Hojas de cálculo
• Cómo crear funciones personalizadas para Hojas de cálculo de Google

Términos clave

• Referencia absoluta: Una configuración de grabación de macro que especifica acciones de macros grabadas, se aplica a las celdas exactas que se usan en la grabación.
• Activa (estado): Indica que la hoja de cálculo, la hoja, el rango o la celda especificados son los que el usuario de la hoja de cálculo está viendo o resaltando actualmente.
• Apps Script: Una plataforma de desarrollo de aplicaciones rápida basada en JavaScript que permite extender las aplicaciones de Google Workspace y automatizar el trabajo con rapidez y facilidad.
• Autorización: Es el proceso del usuario que otorga permisos para permitir que Apps Script acceda a los datos del usuario en los servicios de Google relevantes o realice acciones en nombre del usuario.
• Secuencia de comandos vinculada a un contenedor: Cualquier secuencia de comandos que esté vinculada a un documento de Google Workspace y que se haya creado a partir de él, como una hoja de cálculo o un Documento de Google.
• Funciones personalizadas: Fórmulas definidas por el usuario en Apps Script que se usan en hojas de cálculo para operaciones simples.
• JSDoc: lenguaje de marcación que se usa para escribir notas explicativas en archivos de origen basados en JavaScript.
• Macro: Es la abreviatura de "macroinstruction". Es una serie grabada de acciones de Hojas de cálculo de Google que puedes repetir mediante un elemento de menú o una combinación de teclas.
• Encadenamiento de métodos: Un término simple de programación para invocar varias llamadas de método en un objeto, con la certeza de que cada llamada de método muestra el objeto.
• Rango: Es un grupo de una o más celdas adyacentes dentro de una hoja.
• Referencia relativa: Se aplica una configuración de grabación de macros que especifica las acciones de macros grabadas a las celdas relacionadas con la selección de celdas actual.
• Editor de secuencias de comandos: Es el editor de código en el navegador para Apps Script.
• Hoja: Es una página única de una hoja de cálculo (similar a la hoja de cálculo de Microsoft Excel). En ocasiones, se hace referencia a un archivo de Hojas de cálculo de Google en Google Drive.
• SpreadsheetApp: Esta clase sirve como clase superior del servicio de Hojas de cálculo y proporciona un punto de partida para el código que lee o manipula datos de Hojas de cálculo de Google.
• Hoja de cálculo: Es un archivo de Hojas de cálculo de Google que se encuentra en Google Drive.
• Servicio de hojas de cálculo: Un servicio de Apps Script que permite que las secuencias de comandos creen, accedan y modifiquen archivos de Hojas de cálculo de Google.

Obtenga más información sobre Apps Script en la documentación de Apps Script.

¿Qué sigue?

En el siguiente codelab de esta lista de reproducción, se presentan las clases principales y la terminología del servicio Sheet de Apps Script. Este servicio le permite controlar con precisión los valores y la presentación de los datos en Hojas de cálculo de Google con Apps Script.

Encuentra el siguiente codelab en Hojas de cálculo, Hojas de cálculo y Rangos.