Conceptos básicos de Apps Script con Hojas de cálculo de Google #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 te permite automatizar, personalizar y extender tu experiencia de Google Workspace. Con Apps Script, puedes ahorrar tiempo y esfuerzo, ya que optimiza el trabajo complejo o laborioso en 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 tus aplicaciones 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. No es necesario instalar ni ejecutar software de desarrollo de código.
• Puedes diseñar interfaces de usuario para los editores de Google Workspace que te permitan activar secuencias de comandos directamente desde esos editores con elementos de menú, diálogos y barras laterales.

En esta playlist del codelab sobre los conceptos básicos de Apps Script con Hojas de cálculo de Google, se explican los conceptos básicos de Apps Script y cómo usarlo para mejorar tu experiencia con 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

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

• Crear o modificar una hoja de cálculo
• Leer y actualizar los datos, las fórmulas y el formato de las celdas
• Crea botones y menús personalizados.
• Importar y exportar datos de otras aplicaciones de Google o fuentes de terceros
• Comparte hojas de cálculo y controla el acceso a ellas.

Qué aprenderás

En esta playlist, se abordan 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 y rangos
3. Trabaja con datos
4. Formato de datos
5. Crea gráficos y presenta datos en Presentaciones

Los codelabs de esta playlist están diseñados para leerse en orden, así que comienza con este y complétalos en secuencia para obtener la mejor experiencia de aprendizaje.

Pasa 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 playlist. En este codelab, aprenderás los conceptos básicos para usar 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 grabadas en Hojas de cálculo de Google. Una vez que la grabes, podrás activar una macro para repetir esas acciones más adelante con un elemento de menú o una combinación de teclas. Puedes crear y actualizar tus propias macros en Hojas de cálculo de Google y en el editor de código de Apps Script.

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

Sigue leyendo para conocer los conceptos y requisitos que implica 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 tu primera función personalizada de Hojas de cálculo

Requisitos

• Conocimientos básicos de JavaScript
• Conocimientos básicos de Hojas de cálculo de Google
• Capacidad de leer la notación A1 de Hojas de cálculo

Nota: Apps Script se basa en JavaScript. Si es la primera vez que usas JavaScript, Codecademy ofrece un curso introductorio gratuito de JavaScript. Si bien Google no creó este curso, debería abarcar todo lo que necesitas saber.

Terminaste con las presentaciones. Ve 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 trabajas en hojas de cálculo, puedes entrar en un ciclo de acciones repetitivas (copiar valores de celdas, aplicar formato, crear fórmulas, etcétera) que pueden volverse tediosas y generar errores. Para automatizar acciones repetitivas, Hojas de cálculo de Google proporciona macros. Las macros te permiten "grabar" una serie de acciones en una hoja. Con una macro grabada, puedes repetir las mismas acciones en otro lugar de una hoja de cálculo con solo presionar una tecla de acceso rápido.

En esta sección, aprenderás a crear una macro en Hojas de cálculo. En la siguiente sección, verás 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 colocará una copia de la hoja de cálculo de ejemplo para que la uses en tu carpeta de Google Drive con el nombre "Copia de las 10 películas más taquilleras (2018)".

Crea una macro

Ahora que tienes una hoja de cálculo con la que trabajar, puedes grabar una macro en Hojas de cálculo de Google. En este ejemplo, crearás una macro que formatee una fila de encabezado para tus datos. Solo debes seguir estos pasos:

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

Una vez que comiences a grabar, Hojas de cálculo de Google recordará cada acción que realices en la hoja de cálculo: destacar celdas, agregar datos, cambiar a diferentes hojas, aplicar formato, etcétera. Estas acciones se convierten en el "script" que se repite una vez que guardas y activas la macro más adelante.

3. En el diálogo Macro, selecciona Referencia relativa.

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, la celda A5), mientras que las referencias relativas se aplican usando la selección actual del usuario como punto de partida (por ejemplo, la cuarta celda hacia abajo desde la selección actual).

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

4. Selecciona la fila 1.

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

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

7. Para poner el texto en negrita, presiona Ctrl + B (o Cmd + B en macOS).
8. Para inmovilizar la primera fila, selecciona Ver > Inmovilizar > 1 fila.

9. Haz clic en Guardar en el diálogo de la macro. Aparecerá un diálogo nuevo en el que se te pedirá que le asignes un nombre a la macro. Ingresa el nombre "Encabezado" y haz clic en Guardar.

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

Cómo activar tu macro

Para aplicar tu nueva macro en Hojas de cálculo, sigue estas instrucciones:

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

2. En la hoja nueva, agrega texto a A1:C2. Puedes seguir los ejemplos de entrada que se muestran a continuación:

3. Destaca la primera fila.

4. Para aplicar la macro al área seleccionada, haz clic en Extensiones> Macros> Encabezado.
5. Para autorizar la macro, sigue las instrucciones en pantalla.

Nota: Si usas una cuenta de gmail.com, es posible que también veas un diálogo de app no verificada cuando uses tu secuencia de comandos por primera vez. Google usa esta información para advertir a los usuarios que podrían estar usando código de autores desconocidos o que no son de confianza. Si ves este diálogo, puedes continuar, ya que eres el autor de la secuencia de comandos. Sigue las instrucciones en pantalla para continuar con la autorización de la secuencia de comandos. El proceso para obtener este permiso se denomina autorización.

6. Repite el paso 4 para volver a ejecutar la macro (autorizarla detiene la primera ejecución).

Felicitaciones. Aprendiste a aplicar macros en Hojas de cálculo. Tu hoja de cálculo debería verse así:

Las macros te permiten crear hojas de cálculo de manera eficiente y, en la siguiente parte de este codelab, aprenderás a hacer que tus macros sean aún más potentes. Este es el secreto: cuando grabas una macro, lo que realmente 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 integrado en el navegador de Apps Script.

4. Macros en el editor de secuencias de comandos

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

El editor de secuencias de comandos

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

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

Nota: Las macros y los secuencias de comandos que crearás en este codelab se adjuntan al archivo de la Hoja de cálculo de Google en el que operan y se pueden acceder a ellos en cualquier momento desde el menú Extensiones > Apps Script de Hojas de cálculo. Las secuencias de comandos adjuntas a una Hoja de cálculo de Google como esta se denominan vinculadas al contenedor.

Análisis de macros.gs

Revisa el guion actual. Hojas de cálculo creó el archivo de secuencia de comandos macros.gs cuando grabaste la macro Header y lo completó con una función de Apps Script correspondiente llamada Header. Cuando activas la macro Header, Hojas de cálculo ejecuta esta función.

Observa la siguiente imagen para familiarizarte con la estructura de tu función de macro en Apps Script. Si grabaste los pasos en un orden diferente o hiciste clic en varias partes de la hoja de cálculo mientras grababas, 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 algunos permisos al usuario antes de poder ejecutarse. Estos permisos controlan lo que el usuario permite que haga la secuencia de comandos. 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ía permiso para acceder a todas las hojas de cálculo del usuario y actualizarlas. Siempre es una práctica recomendada incluir esta anotación cuando solo trabajas con un solo archivo. El grabador de macros agrega este comentario automáticamente por ti.

Para comprender cómo Apps Script representa las instrucciones de tu macro, puedes consultar 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. Ten en cuenta que Header() no requiere parámetros, ya que las funciones de macro en Apps Script no necesitan entradas. Las llaves siempre encierran el cuerpo de una función en Apps Script.

En los codelabs posteriores de esta playlist, se explican las clases y los conceptos involucrados en la creación de la macro. Por el momento, puedes consultar las siguientes descripciones del código para obtener una idea general de sus componentes y su función en la construcción de tu macro. Considera la primera línea:

var spreadsheet = SpreadsheetApp.getActive();

Aquí, getActive() devuelve 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 obtiene toda la primera fila con el método getRange() y, luego, llama a activate() para activarla. La primera fila se especifica con los números de fila y columna específicos. La llamada a spreadsheet.getCurrentCell().getRow() devuelve el número de la fila actual, mientras que sheet.getMaxColumns() devuelve la cantidad máxima 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 a métodos de manera eficiente con spreadsheet, el código apila tres métodos en getActiveRangeList() para evitar que el código llame de forma redundante a este método spreadsheet más de una vez. A medida que escribas más código con Apps Script, te familiarizarás más con esta convención de llamar a varios métodos en una clase (también conocida como encadenamiento de métodos). Por el momento, puedes leer lo siguiente para obtener explicaciones breves sobre cada método en el bloque de código:

• getActiveRangeList() devuelve el 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 en el rango activo.
• setFontWeight(fontWeight) ajusta el grosor de la fuente para las celdas del rango activo.

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

spreadsheet.getActiveSheet().setFrozenRows(1);

Ese es el script que generaste cuando grabaste tu macro. No te preocupes por los términos o métodos desconocidos que se mencionaron 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 de macro típica y en los temas que se abordan en codelabs futuros.

En la siguiente sección, se explica cómo manipular el código de la función Header() para mostrar cómo puedes usar el editor de secuencias de comandos para personalizar aún más las macros.

Personaliza macros con Apps Script

El editor de Apps Script muestra la macro que creaste 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 que realice acciones diferentes o adicionales. En los siguientes ejercicios, se muestran varias formas de manipular macros con el editor de secuencias de comandos.

Cambia las celdas afectadas

Supongamos que deseas modificar tu macro para que solo afecte las primeras 10 columnas de la primera fila en lugar de toda la fila. Podrías borrar la macro y volver a grabarla. Sin embargo, puedes realizar esos cambios directamente con el editor de Apps Script. Esta es una forma 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 el script, haz clic en Guardar .
3. Para cambiar el nombre del proyecto, ingresa "Macros and Custom Functions" como el nuevo nombre del proyecto 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 la nueva hoja, deberías ver el siguiente resultado:

Si modificas el rango activo o de destino, tu macro ahora solo afectará parte de la primera fila. Muchos métodos de Apps Script toman un rango o una notación A1 como parámetro para especificar en qué celdas se debe actuar.

A continuación, aprenderemos a personalizar los colores de tus macros.

Cómo cambiar los colores de la macro

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

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

1. En Hojas de cálculo, vuelve 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 con la notación de trío 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 el script, haz clic en Guardar .
5. En la lista de funciones, selecciona Header y haz clic en Ejecutar.

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

Si cambias la notación de color hexadecimal en los parámetros de setBackground(color) de #4c1130 (magenta oscuro 3) a #afeeee (turquesa pálido, una opción no accesible en el menú de color predeterminado de Hojas de cálculo), cambiarás el atributo de color del color de fondo de la macro.

Ahora modificaste el conjunto de colores de fondo que estableció tu macro. Si también quieres cambiar el color del texto, cambia el segundo código de color.

1. En Hojas de cálculo, haz clic en la primera fila para asegurarte 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 el script, haz clic en Guardar .
4. En la lista de funciones, selecciona Header y haz clic en Ejecutar.

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

Ahora ya sabes cómo las macros son, en realidad, acciones de Hojas de cálculo grabadas como código de Apps Script. En la siguiente sección, verás otra forma en que Apps Script puede ayudarte a trabajar con Hojas de cálculo de Google: las funciones personalizadas.

5. Codifica tu 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órmulas integradas, como =SUM(), que permiten realizar cálculos rápidos en los datos de la hoja de cálculo. Las funciones personalizadas son simplemente funciones que especificas con Apps Script. Una vez que definas una función personalizada, podrás usarla en cualquier parte 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 realice una conversión monetaria.

Crea un archivo de secuencia de comandos

Con el mismo proyecto de hoja de cálculo y secuencia de comandos de la sección Macros, sigue estas instrucciones para aprender a crear una secuencia de comandos nueva (que, con el tiempo, podrás usar para crear tu primera función personalizada):

1. Para crear un archivo de Apps Script, regresa al editor de secuencias de comandos.
2. Junto a Files, haz clic en Add a file > Script.
3. Asigna el nombre customFunctions al nuevo archivo de secuencia de comandos y presiona Intro. (Apps Script agrega automáticamente una extensión .gs al nombre del archivo de secuencia de comandos).

En el editor, aparecerá una pestaña nueva llamada customFunctions.gs.

Ahora que creaste una secuencia de comandos específicamente para las funciones personalizadas, puedes completarla con código.

Convertir dólares estadounidenses a francos suizos

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

Antes de escribir tu primera función personalizada, modifica tu conjunto de datos para permitir que la función muestre un resultado adecuado. Para ello, sigue estos pasos:

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

3. Etiqueta la columna como "Worldwide_Gross (francos suizos)" en la celda I1.

Ahora tienes una columna que puede almacenar los resultados de tu función personalizada de conversión. A continuación, 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 el 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á dólares estadounidenses a francos suizos. Sigue las instrucciones que se indican a continuación y descubre cómo ejecutar una función personalizada en Hojas de cálculo.

5. Para guardar el script, haz clic en Guardar .
6. En Hojas de cálculo, selecciona 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, haz lo siguiente:

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

En la columna I, ahora se enumeran las conversiones de los valores en dólares estadounidenses de la columna H a francos suizos.

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

Análisis de USDTOCHF()

Los comentarios iniciales detallan 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 usan 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 a francos) y las anotaciones que describen los parámetros y el tipo de datos que devuelve la función.

Con las anotaciones, Apps Script utiliza JSDoc para ayudarte a documentar y crear sugerencias de autocompletado para tu código. A continuación, puedes leer cómo cada anotación que se usa 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 devuelve la función.
• @customfunction: Siempre debes agregar @customfunction en el comentario del documento de cualquier función personalizada. Esta anotación notifica a Hojas de cálculo que autocomplete tu función personalizada de la misma manera que Hojas de cálculo autocompleta las funciones integradas cuando ingresas un nombre de función en una celda, como se muestra a continuación:

Observa que el texto que aparece en la ventana emergente de autocompletado coincide exactamente con el texto de la descripción que colocaste en el bloque de comentarios. Puedes facilitar el uso de tus funciones personalizadas si te aseguras de que las descripciones que crees estén bien escritas y sean completas.

A continuación, 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 la variable numérica dólares, la multiplica por un tipo de cambio fijo y devuelve un valor convertido a francos suizos en la variable numérica swissFrancs. El parámetro de entrada es el valor que se incluye en la celda especificada cuando se agrega la función personalizada a una celda. En este ejemplo, los importes de entrada en dólares provienen de la columna H. El valor de salida swissFrancs se coloca en la celda de la función (columna I en este ejemplo).

Las funciones personalizadas pueden trabajar con valores numéricos o de cadena, como verás en la siguiente sección.

Cómo concatenar un prefijo de cadena

Supongamos que deseas que el resultado numérico de la función USDTOCHF() incluya el prefijo de franco suizo 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 que devuelva una cadena en lugar de un número.
2. Cambia return swissFrancs por return 'CHF' + swissFrancs.

El operador + agrega la cadena 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 el script, haz clic en Guardar .

La cadena de francos suizos ahora antepone los valores de la columna I:

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

Avanzado: Recupera datos externos

Este es un buen comienzo para una función personalizada básica, pero este ejemplo supone que el tipo de cambio de dólares a francos suizos es constante. Supongamos que, en cambio, deseas usar el tipo de cambio actual, de modo que, cada vez que se vuelva a cargar la hoja, se vuelvan a calcular los valores para representar la conversión actual. Para ello, necesitarías un medio para descubrir cuál es el tipo de cambio actual. Esa información no está disponible de inmediato en Hojas de cálculo de Google, pero, afortunadamente, puedes usar Apps Script para obtenerla.

Puedes usar un código como el que se muestra a continuación para obtener el tipo de cambio 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 el tipo de cambio actual de un servidor de información financiera con una API de tipo de cambio de terceros. Esto se hace con servicios de Apps Script, como UrlFetchApp y CacheService. Estos 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 para funciones personalizadas

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

• No crees funciones personalizadas que requieran autorización del usuario. En cambio, crea tus funciones personalizadas para realizar tareas más simples, como cálculos de datos de muestra, edición de texto, etcétera. Consulta Cómo usar los servicios de Apps Script.
• No le asignes a una función personalizada el mismo nombre que otra función integrada ni termines el nombre con un guion bajo. Revisa los lineamientos para asignar nombres.
• No pases argumentos variables a las funciones personalizadas. Solo puedes pasar valores determinísticos (fijos) a las funciones personalizadas como argumentos. Si pasas argumentos variables, como el resultado de =RAND(), la función personalizada dejará de funcionar. Consulta los lineamientos sobre los argumentos.
• No crees funciones que tarden más de 30 segundos en completarse. Si tarda más, se producirá un error, por lo que el código de la función debe ser simple y de alcance limitado. Lo mejor es que los cálculos que se realizan en las funciones personalizadas sean lo más sencillos posible. Consulta los lineamientos sobre los valores de devolución.

Ahora puedes mejorar tus hojas de cálculo usando 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 scripting.

6. Conclusión

Completaste el primer codelab de los conceptos 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: Es un parámetro de configuración de grabación de macros que especifica que las acciones de la macro grabada se aplican a las celdas exactas que se usaron 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 destacando actualmente.
• Apps Script: Es una plataforma de desarrollo de aplicaciones rápida basada en JavaScript que agiliza y facilita la extensión de las aplicaciones de Google Workspace y la automatización del trabajo.
• Autorización: Es el proceso por el que el usuario otorga permisos para permitir que Apps Script acceda a los datos del usuario en los servicios de Google pertinentes o realice acciones en nombre del usuario.
• Secuencia de comandos vinculada a un contenedor: Es cualquier secuencia de comandos que esté vinculada a un documento de Google Workspace, como una Hoja de cálculo o un documento de Google, y que se haya creado a partir de él.
• Funciones personalizadas: Son fórmulas definidas por el usuario en Apps Script que se usan en hojas de cálculo para operaciones simples.
• JSDoc: Es un lenguaje de marcado que se usa para escribir notas explicativas en archivos de origen basados en JavaScript.
• Macro: Abreviatura de "macroinstrucción". Es una serie grabada de acciones de Hojas de cálculo de Google que puedes repetir con un elemento de menú o una combinación de teclas.
• Encadenamiento de métodos: Es una expresión idiomática de programación para invocar varias llamadas a métodos en un objeto, que se basa en el hecho de que cada llamada a un método devuelve el objeto.
• Rango: Es un grupo de una o más celdas adyacentes dentro de una hoja.
• Referencia relativa: Es un parámetro de configuración de grabación de macros que especifica que las acciones de la macro grabada se aplican a las celdas relativas a 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 sola página de una hoja de cálculo (similar a los libros de trabajo de Microsoft Excel). A veces, se usa para hacer referencia a un archivo de Hojas de cálculo de Google dentro de Google Drive.
• SpreadsheetApp: Esta clase sirve como clase principal para el 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: Es un servicio de Apps Script que permite que las secuencias de comandos creen, modifiquen y accedan a archivos de Hojas de cálculo de Google.

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

¿Qué sigue?

El siguiente codelab de esta playlist presenta las clases y la terminología principales del servicio de Hojas de cálculo de Apps Script. Este servicio te 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 Spreadsheets, Sheets, and Ranges.