Widgets

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Un widget es un elemento simple de la IU que proporciona una o más de las siguientes opciones:

  • Estructura para otros widgets, como tarjetas y secciones
  • Información para el usuario, como texto e imágenes, o
  • Acontecimientos para la acción, como botones, campos de entrada de texto o casillas de verificación.

Los conjuntos de widgets que se agregan a las secciones de tarjeta definen la IU general del complemento. Los widgets tienen el mismo aspecto y función en la Web y en dispositivos móviles. En la documentación de referencia, se describen varios métodos para compilar conjuntos de widgets.

Cómo usar el kit de diseño de complementos de Google Workspace

Para ahorrar tiempo en el diseño de widgets de complementos, los diseñadores pueden usar el kit de diseño de la IU de complementos de Google Workspace disponible en Figma. Puedes crear una cuenta de Figma o solicitar una licencia al administrador de tu organización.

Explora los componentes y usa plantillas integradas para crear y visualizar widgets.

Obtener el kit de diseño

Tipos de widgets

Los widgets complementarios, por lo general, se clasifican en tres grupos: widgets estructurales, widgets informativos y widgets de interacción del usuario.

Widgets estructurales

Los widgets estructurales proporcionan contenedores y organización para los otros widgets que se usan en la IA.

Widgets estructurales

  • Conjunto de botones: Es una colección de uno o más botones de texto o imagen agrupados en una fila horizontal.
  • Tarjeta: Una sola tarjeta de contexto que contiene una o más secciones de tarjeta. Para definir cómo se pueden mover los usuarios entre las tarjetas, configura la navegación de tarjetas.
  • Encabezado de la tarjeta: Es el encabezado de una tarjeta determinada. Los encabezados de las tarjetas pueden tener títulos, subtítulos y una imagen. Las acciones de la tarjeta y las acciones universales aparecen en el encabezado de la tarjeta si el complemento las usa.
  • Sección de tarjetas: Es un grupo recopilado de widgets, dividido de las otras secciones de tarjetas por una regla horizontal y, de forma opcional, que tiene un encabezado de sección. Cada tarjeta debe tener al menos una sección. No puedes agregar tarjetas ni encabezados a una sección de tarjeta.

Además de estos widgets estructurales básicos, en un complemento de Google Workspace puedes usar el servicio Card para crear estructuras que se superpongan con la tarjeta actual: pies de página fijos y tarjetas emergentes:

Ahora puedes agregar una fila fija de botones en la parte inferior de tu tarjeta. Esta fila no se mueve ni desplaza con el resto del contenido de la tarjeta. En el siguiente fragmento de código, se muestra cómo definir un pie de página fijo de ejemplo y agregarlo a una tarjeta:

var fixedFooter = CardService.newFixedFooter()
    .setPrimaryButton(
        CardService.newTextButton()
            .setText("help")
            .setOpenLink(CardService.newOpenLink()
                .setUrl("https://www.google.com")))
    .setSecondaryButton(
        CardService.newTextButton()
            .setText("submit")
            .setOnClickAction(
                CardService.newAction()
                    .setFunctionName(
                        "submitCallback")));

var card = CardService.newCardBuilder()
    // (...)
    .setFixedFooter(fixedFooter)
    .build();
      

 

Ejemplo de widget de pie de página fijo

Mostrar tarjeta

Ejemplo de tarjeta de presentación

Cuando una acción del usuario activa un contenido contextual nuevo, como abrir un mensaje de Gmail, puedes mostrar el contenido contextual nuevo de inmediato (comportamiento predeterminado) o mostrar una notificación con la tarjeta en la parte inferior de la barra lateral. Si un usuario hace clic en Atrás para volver a la página principal mientras un activador contextual está activo, aparecerá una tarjeta de visualización para ayudar a los usuarios a volver a encontrar el contenido contextual.

Para mostrar una tarjeta de vista previa cuando haya contenido contextual nuevo disponible, en lugar de mostrarlo de inmediato, agrega .setDisplayStyle(CardService.DisplayStyle.PEEK) a tu clase CardBuilder. Una tarjeta de vista previa solo aparece si se muestra un solo objeto de tarjeta con el activador contextual; de lo contrario, las tarjetas mostradas reemplazan de inmediato la tarjeta actual.

Para personalizar el encabezado de la tarjeta de vista previa, agrega el método .setPeekCardHeader() con un objeto CardHeader estándar cuando compiles tu tarjeta contextual. De forma predeterminada, un encabezado de tarjeta Peek solo contiene el nombre de tu complemento.

El siguiente código, que se basa en la guía de inicio rápido sobre el complemento de Google Workspace de Cats, notifica a los usuarios sobre el nuevo contenido contextual con una tarjeta de Peek y personaliza el encabezado de la tarjeta de Peek para mostrar el asunto del mensaje de Gmail seleccionado.

var peekHeader = CardService.newCardHeader()
    .setTitle('Contextual Cat')
    .setImageUrl('https://www.gstatic.com/images/
        icons/material/system/1x/pets_black_48dp.png')
    .setSubtitle(text);

. . .

var card = CardService.newCardBuilder()
    .setDisplayStyle(CardService.DisplayStyle.PEEK)
    .setPeekCardHeader(peekHeader);
      

 

Ejemplo de tarjeta de vista personalizada

Widgets informativos

Widgets informativos

Los widgets informativos presentan información al usuario.

  • Imagen: Una imagen indicada por una URL alojada y de acceso público que proporcionas.
  • DecoratedText: Es una string de contenido de texto que puedes sincronizar con otros elementos, como etiquetas de texto superior e inferior, y una imagen o ícono. Los widgets de DecoratedText también pueden incluir un widget Button o Switch. Los interruptores agregados pueden ser botones de activación o casillas de verificación simples. El texto de contenido del widget DecoratedText puede usar formato HTML; las etiquetas inferior y superior deben usar texto sin formato.
  • Párrafo de texto: Es un párrafo de texto simple que puede incluir elementos con formato HTML.




Widgets de interacción del usuario

Widget de acción de la tarjeta

Los widgets de interacción del usuario permiten que el complemento responda a las acciones que realizan los usuarios. Puedes configurar estos widgets con respuestas de acción para mostrar diferentes tarjetas, abrir URL, mostrar notificaciones, redactar correos electrónicos de borrador o ejecutar otras funciones de Apps Script. Consulta la guía Cómo compilar tarjetas interactivas para obtener más detalles.

Widgets de interacción del usuario

  • Acción de la tarjeta: un elemento de menú que se coloca en el menú de la barra de encabezado del complemento. El menú de la barra de encabezado también puede contener elementos definidos como acciones universales, que aparecen en cada tarjeta que define el complemento.
  • Selectores de fecha y hora: widgets que permiten a los usuarios seleccionar una fecha, una hora o ambas. Consulta Selectores de fecha y hora a continuación para obtener más información.
  • Botón de imagen: Es un botón que usa una imagen en lugar de texto. Puedes usar uno de varios íconos predefinidos o una imagen alojada públicamente que indique su URL.
  • Entrada de selección: un campo de entrada que representa una colección de opciones. Los widgets de entrada de selección se presentan como casillas de verificación, botones de selección o cuadros de selección desplegables.
  • Interruptor: un widget para activar o desactivar. Solo puedes usar interruptores junto con un widget DecoratedText. De forma predeterminada, se muestran como botones de activación, pero puedes hacer que se muestren como una casilla de verificación.
  • Botón de texto: Es un botón con una etiqueta de texto. Puedes especificar un relleno de color de fondo para los botones de texto (la configuración predeterminada es transparente). También puedes inhabilitar el botón según sea necesario.
  • Entrada de texto: Es un campo de entrada de texto. El widget puede tener texto de título, texto indicado y texto de varias líneas. El widget puede activar acciones cuando cambia el valor del texto.
  • Cuadrícula: un diseño de varias columnas que representa una colección de elementos. Puedes representar elementos con una imagen, un título, un subtítulo y un rango de opciones de personalización, como los estilos de borde y recorte.

Casillas de verificación de DecoratedText

Puedes definir un widget DecoratedText que tenga una casilla de verificación adjunta, en lugar de un botón o un botón de activación binario. Al igual que con los interruptores, el valor de la casilla de verificación se incluye en el objeto de evento de acción que se pasa al Action adjunto a este DecoratedText mediante el método setOnClickAction(action).

En el siguiente fragmento de código, se muestra cómo definir un widget de casilla de verificación DecoratedText, que luego puedes agregar a una tarjeta:

var decoratedText = CardService.newDecoratedText()
    // (...)
    .setSwitch(CardService.newSwitch()
        .setFieldName('form_input_switch_key')
        .setValue('switch_is_on')
        .setControlType(
            CardService.SwitchControlType.CHECK_BOX));
      

 

Ejemplo de widget de casilla de verificación de texto decorado

Selectores de fecha y hora

Puedes definir widgets que permitan a los usuarios seleccionar una hora, una fecha o ambas. Puedes usar setOnChangeAction() para asignar una función de controlador de widgets que se ejecutará cuando cambie el valor del selector.

En el siguiente fragmento de código, se muestra cómo definir un selector de solo fecha, un selector de solo hora y un selector de fecha y hora, que luego puedes agregar a una tarjeta:

var dateOnlyPicker = CardService.newDatePicker()
    .setTitle("Enter the date.")
    .setFieldName("date_field")
    // Set default value as May 24 2019. Either a
    // number or string is acceptable.
    .setValueInMsSinceEpoch(1558668600000)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleDateChange"));

var timeOnlyPicker = CardService.newTimePicker()
    .setTitle("Enter the time.")
    .setFieldName("time_field")
    // Set default value as 23:30.
    .setHours(23)
    .setMinutes(30)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleTimeChange"));

var dateTimePicker = CardService.newDateTimePicker()
    .setTitle("Enter the date and time in EDT time.")
    .setFieldName("date_time_field")
    // Set default value as May 24 2019 03:30 AM UTC.
    // Either a number or string is acceptable.
    .setValueInMsSinceEpoch(1558668600000)
    // EDT time is 4 hours behind UTC.
    .setTimeZoneOffsetInMins(-4 * 60)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleDateTimeChange"));
      

 

Ejemplo de tarjeta de vista personalizada

El siguiente es un ejemplo de una función de controlador de widget de selector de fecha y hora. Este controlador simplemente da formato y registra una string que representa la fecha y hora elegida por el usuario en un widget de selector de fecha y hora con el ID "myDateTimePickerWidgetID":

function handleDateTimeChange(event) {
  var dateTimeInput =
    event.commonEventObject.formInputs["myDateTimePickerWidgetID"];
  var msSinceEpoch = dateTimeInput.msSinceEpoch;
  var hasDate = dateTimeInput.hasDate;
  var hasTime = dateTimeInput.hadTime;

  // The following requires you to configure the add-on to read user locale
  // and timezone.
  // See https://developers.google.com/apps-script/add-ons/how-tos/access-user-locale
  var userTimezoneId = event.userTimezone.id;

  // Format and log the date-time selected using the user's timezone.
  var formattedDateTime;
  if (hasDate && hasTime) {
    formattedDateTime = Utilities.formatDate(
      new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd hh:mm:ss");
  } else if (hasDate) {
    formattedDateTime = Utilities.formatDate(
      new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd")
      + ", Time unspecified";
  } else if (hasTime) {
    formattedDateTime = "Date unspecified, "
      + Utilities.formatDate(
          new Date(msSinceEpoch), userTimezoneId, "hh:mm a");
  }

  if (formattedDateTime) {
    console.log(formattedDateTime);
  }
}

 

En la siguiente tabla, se muestran ejemplos de las IU de selección del selector en computadoras de escritorio y dispositivos móviles. Cuando se selecciona, el selector de fecha abre una IU de calendario basada en el mes para permitir que el usuario seleccione rápidamente una fecha nueva.

Cuando el usuario selecciona el selector de hora en dispositivos de escritorio, se abre un menú desplegable con una lista de horarios separados en incrementos de 30 minutos desde los que el usuario puede seleccionar. El usuario también puede escribir en un horario específico. En los dispositivos móviles, cuando seleccionas un selector de hora, se abre el selector de hora de dispositivos móviles integrado.

Computadora de escritorio Dispositivo móvil
ejemplo de selección del selector de fecha ejemplo de selección del selector de fechas para dispositivos móviles
ejemplo de selección del selector de hora ejemplo de selección del selector de hora del dispositivo móvil

Grid

Muestra elementos en un diseño de varias columnas con el widget de cuadrícula. Cada elemento puede mostrar una imagen, un título y un subtítulo. Usa opciones de configuración adicionales para establecer la posición del texto en relación con la imagen en un elemento de cuadrícula.

Puedes configurar un elemento de cuadrícula con un identificador que se muestra como parámetro para la acción definida en la cuadrícula.

var gridItem = CardService.newGridItem()
  .setIdentifier("item_001")
  .setTitle("A grid item")
  .setSubtitle("with a subtitle")
  .setImage(imageComponent);

var cropStyle = CardService.newImageCropStyle()
  .setImageCropType(CardService.ImageCropType.SQUARE);

var borderStyle = CardService.newBorderStyle()
  .setType(CardService.BorderType.STROKE)
  .setCornerRadius(8)
  .setStrokeColor("#00FF00FF");

var imageComponent = CardService.newImageComponent()
  .setImageUrl("https://cataas.com/cat?0.001")
  .setCropStyle(cropStyle)
  .setBorderStyle(borderStyle);

var grid = CardService.newGrid()
  .setTitle("My first grid")
  .addItem(gridItem)
  .setNumColumns(2)
  .setOnClickAction(CardService.newAction()
    .setFunctionName("handleGridItemClick"));
      

 

Ejemplo de widget de cuadrícula

Formato del texto

Algunos widgets basados en texto admiten formato HTML de texto simple. Cuando configures el contenido de texto de estos widgets, solo debes incluir las etiquetas HTML correspondientes. Se admiten los siguientes formatos:

Formato Ejemplo Resultado procesado
Negrita <b>test</b> test
Cursiva <i>test</i> test
Subrayado <u>test</u> test
Tachado <s>test</s> test
Color de la fuente <font color="#ea9999">test</font> test
Hipervínculo <a href="http://www.google.com">google</a> google
Hora <time>2020-02-16 15:00</time> 2020-02-16 15:00
Nueva línea test <br> test prueba
prueba