Widgets

Un widget es un elemento de la IU que proporciona uno o más de los siguientes elementos:

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

Los conjuntos de widgets agregados a las secciones de tarjetas definen la IU general del complemento. Los widgets tienen el mismo aspecto y la misma 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.

Tipos de widgets

Por lo general, los widgets de complementos 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 IU.

  • Conjunto de botones: Es una colección de uno o más botones de texto o imagen, agrupados en una fila horizontal.
  • Tarjeta: Es una tarjeta de contexto única que contiene una o más secciones de tarjetas. Tú defines la manera en que los usuarios pueden moverse entre tarjetas mediante la configuración de la navegación por 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 tarjetas 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, divididos de las otras secciones de tarjetas por una regla horizontal y, opcionalmente, con un encabezado de sección. Cada tarjeta debe tener al menos una sección de tarjetas. No puedes agregar tarjetas ni encabezados de tarjetas a una sección de tarjetas.

Widgets estructurales

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

Puedes agregar una fila fija de botones en la parte inferior de la tarjeta. Esta fila no se mueve ni se desplaza con el resto del contenido de la tarjeta.

Se corrigió el ejemplo de widget de pie de página.

En el siguiente extracto de código, se muestra cómo definir un ejemplo de pie de página fijo y agregarlo a una tarjeta:

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

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

Mostrar tarjeta

Ejemplo de tarjeta de presentación

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

Para mostrar una tarjeta de vista previa cuando haya nuevo contenido contextual 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 tu activador contextual; de lo contrario, las tarjetas que se muestran reemplazan de inmediato a 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 crees tu tarjeta contextual. De forma predeterminada, el encabezado de una tarjeta Peek contiene solo el nombre de tu complemento.

Ejemplo de tarjeta de vista personalizada

El siguiente código, que se basa en la guía de inicio rápido del complemento de Google Workspace de gatos, notifica a los usuarios sobre el contenido contextual nuevo con una tarjeta de vista previa y personaliza el encabezado de la tarjeta de vista previa para mostrar el asunto de la conversación de mensajes de Gmail seleccionada.

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);

Widgets informativos

Los widgets informativos presentan información al usuario.

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

Widgets informativos

Widgets de interacción del usuario

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 URLs, mostrar notificaciones, redactar borradores de correos electrónicos o ejecutar otras funciones de Apps Script. Consulta la guía Cómo crear tarjetas interactivas para obtener más detalles.

  • Acción de tarjeta: Es un elemento de menú ubicado en el menú de la barra de encabezado de complementos. 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: Son 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 de forma pública que indique su URL.
  • Entrada de selección: Es 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: Es un widget de activación. Solo puedes usar interruptores junto con un widget DecoratedText. De forma predeterminada, se muestran como un interruptor, pero puedes establecer que aparezcan 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 (el valor predeterminado 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 de sugerencia y texto de varias líneas. El widget puede activar acciones cuando cambia el valor del texto.
  • Cuadrícula: Es 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 una variedad de opciones de personalización, como estilos de borde y recorte.
Widget de acción de la tarjeta Widgets de interacción del usuario

DecoratedText casillas de verificación

Puedes definir un widget DecoratedText que tenga una casilla de verificación adjunta, en lugar de un botón o un interruptor 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 el método setOnClickAction(action) pasa al Action adjunto a este DecoratedText.

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

En el siguiente extracto de código, se muestra cómo definir un widget DecoratedText con casilla de verificación, 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));

Selectores de fecha y hora

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

Ejemplo de tarjeta de vista personalizada

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

var dateOnlyPicker = CardService.newDatePicker()
    .setTitle("Enter a 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 a 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 a date and 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"));

El siguiente es un ejemplo de una función de controlador del widget del selector de fecha y hora. Este controlador formatea 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 IUs 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 horas separadas en incrementos de 30 minutos entre las que el usuario puede seleccionar. El usuario también puede escribir una hora específica. En dispositivos móviles, cuando seleccionas un selector de hora, se abre el selector de hora integrado del reloj.

Computadoras Dispositivos móviles
ejemplo de selección del selector de fecha ejemplo de selección del selector de fecha para dispositivos móviles
ejemplo de selección del selector de hora ejemplo de selección del selector de hora del dispositivo móvil

Cuadrícula

Muestra los 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 el posicionamiento del texto relativo a la imagen en un elemento de la cuadrícula.

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

Ejemplo de widget de cuadrícula

var gridItem = CardService.newGridItem()
  .setIdentifier("item_001")
  .setTitle("Lucian R.")
  .setSubtitle("Chief Information Officer")
  .setImage(imageComponent);

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

var imageComponent = CardService.newImageComponent()
  .setImageUrl("https://developers.google.com/workspace/
      images/cymbal/people/person1.jpeg")
  .setCropStyle(cropStyle)

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

Formato del texto

Algunos widgets basados en texto pueden admitir formato HTML de texto simple. Cuando configures el contenido de texto de estos widgets, solo incluye las etiquetas HTML correspondientes.

Las etiquetas compatibles y su propósito se muestran en la siguiente tabla:

Formato Ejemplo Resultado procesado
Negrita "This is <b>bold</b>." Está en negrita.
Cursiva "This is <i>italics</i>." Es cursiva.
Subrayado "This is <u>underline</u>." Es subrayado.
Tachado "This is <s>strikethrough</s>." Este mensaje está tachado.
Color de la fuente "This is <font color=\"#FF0000\">red font</font>." Es una fuente roja.
Hipervínculo "This is a <a href=\"https://www.google.com\">hyperlink</a>." Este es un hipervínculo.
Tiempo "This is a time format: <time>2023-02-16 15:00</time>." Debe ser un formato de hora: .
Nueva línea "This is the first line. <br> This is a new line." Esta es la primera línea.
Esta es una línea nueva.