Se usó la API de Cloud Translation para traducir esta página.

Widgets

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 al usuario, como imágenes y texto, o
Ventajas de la acción, como botones, campos de entrada de texto o casillas de verificación.

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

Usa el kit de diseño para complementos de Google Workspace

Para ahorrar tiempo en el diseño de los widgets de un complemento, los diseñadores pueden usar el kit de diseño de IU de complementos para 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 las plantillas integradas para crear y visualizar widgets.

Obtener el kit de diseño

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 usados en la IA.

Widgets estructurales

Conjunto de botones: colección de uno o más botones de imagen o texto agrupados en una fila horizontal.
Tarjeta: Una sola tarjeta de contexto que contiene una o más secciones de tarjeta. Define la forma en que los usuarios pueden moverse entre tarjetas mediante la configuración de la navegación de tarjetas.
Encabezado de la tarjeta: Es el encabezado para 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 de widgets que se recopila, dividido desde las otras secciones de tarjetas por una regla horizontal y, de forma opcional, con 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 de Card para crear estructuras que se superpongan con la tarjeta actual: pies de página fijos y tarjetas de visualización:

Pie de página fijo

Ahora puedes agregar una fila fija de botones en la parte inferior de tu tarjeta. Esta fila no se mueve ni se 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();

Mostrar tarjeta

Ejemplo de tarjeta de vista

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

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, el encabezado de la tarjeta de consulta contiene solo el nombre del complemento.

El siguiente código, que se basa en la guía de inicio rápido sobre los complementos de Google Workspace para Cats, notifica a los usuarios sobre el contenido contextual nuevo con una tarjeta Peek y personaliza el encabezado de la tarjeta para mostrar el asunto de la conversación 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

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 inferiores y superiores, y una imagen o un ícono. Los widgets de DecoratedText también pueden incluir un widget Button o Switch. Los botones agregados pueden ser botones de activación o casillas de verificación simples. El texto del 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 en 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 en 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 los varios íconos predefinidos o una imagen alojada de forma pública que se indica mediante la 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: Widget de activación o desactivación. Solo puedes usar botones junto con un widget DecoratedText. De forma predeterminada, se muestran como un interruptor, pero puedes hacer que se muestren como una casilla de verificación en su lugar.
Botón de texto: 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 de sugerencia y texto de varias líneas. El widget puede activar acciones cuando cambia el valor de texto.
Cuadrícula: un diseño de varias columnas que representa una colección de elementos. Puedes representar los 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 con 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 DecoratedText de 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));

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

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 que eligió 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 de 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 al usuario seleccionar 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 que el usuario puede seleccionar. El usuario también puede escribir en una hora específica. En los dispositivos móviles, cuando se selecciona un selector de hora, se abre el selector de hora del reloj móvil integrado.

Computadora de escritorio	Dispositivos móviles

Cuadrícula

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 relacionado con la imagen en un elemento de 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.

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

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