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 imágenes y texto
• Posibilidades de 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 tarjetas definen la estructura general en la IU del complemento. Los widgets Tienen el mismo aspecto y función tanto en la Web como en los dispositivos móviles. El documentación de referencia se describen varios métodos para crear 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 demás widgets. que se usa en la IU.

• Conjunto de botones: A colección de uno o más botones de texto o imagen, agrupados en una fila horizontal.
• Tarjeta: Un solo contexto tarjeta que contiene una o más secciones de tarjetas. Tú defines cómo los usuarios pueden entre las tarjetas mediante la configuración navegación de tarjetas.
• Encabezado de la tarjeta: El encabezado de una tarjeta determinada. Los encabezados de las tarjetas pueden tener títulos, subtítulos y una imagen. Acciones de la tarjeta y las acciones universales aparecen en el el encabezado de la tarjeta si el complemento los usa.
• Sección de tarjeta: A recopilado un grupo de widgets, dividido de las demás secciones de la tarjeta por una horizontal y, opcionalmente, un encabezado de sección. Cada tarjeta debe tener al menos una sección de tarjeta. No puedes agregar tarjetas o encabezados a una tarjeta sección.

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

Pie de página fijo

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.

Lo siguiente el extracto de código 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("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

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

Para mostrar una tarjeta de vista previa cuando hay nuevo contenido contextual disponible, en lugar de mostrar inmediatamente el nuevo contenido contextual, agrega .setDisplayStyle(CardService.DisplayStyle.PEEK) a tu CardBuilder . Una tarjeta de vista previa solo aparece si se devuelve un único objeto de tarjeta con tu activador contextual; De lo contrario, las tarjetas mostradas reemplazarán inmediatamente el tarjeta actual.

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

El siguiente código, basado en el Guía de inicio rápido sobre el complemento de Google Workspace para gatos, notifica a los usuarios sobre contenido contextual nuevo con una tarjeta de presentación y personaliza el encabezado de la tarjeta de vista previa para que se muestre el mensaje de Gmail seleccionado asunto de la conversación.

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: Una imagen indicada mediante una URL alojada y con acceso público que usted proporcione.
• DecoratedText: A texto cadena de contenido que se puede vincular con otros elementos, como los de la parte superior e inferior etiquetas de texto y una imagen o ícono. Los widgets DecoratedText también pueden incluir una Botón o Widget Switch. Se agregaron interruptores pueden ser un botón de activación o una casilla de verificación. El texto del contenido del widget DecoratedText puede usar Formato HTML; los mejores y las etiquetas de la parte inferior deben usar texto sin formato.
• Párrafo de texto: A párrafo de texto, que puede incluir Elementos con formato HTML

Widgets de interacción del usuario

Los widgets de interacción del usuario permiten que el complemento responda a las acciones realizadas por el usuarios. Puedes configurar estos widgets con respuestas a acciones para mostrar tarjetas diferentes, abrir URLs, mostrar notificaciones, redactar borradores de correos electrónicos o ejecutar otras funciones de Apps Script. Consulta la Cómo crear tarjetas interactivas de más detalles.

• Acción de la tarjeta: Menú elemento colocado en el menú de la barra de encabezado del complemento. El menú de la barra del encabezado también contener elementos definidos como acciones universales, que aparecen en todas las tarjetas 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: A que usa una imagen en lugar de texto. Puedes usar uno de varios íconos predefinidos o una imagen alojada de forma pública indicada por su URL.
• Entrada de selección: Un campo de entrada que representa un conjunto de opciones. Widgets de entrada de selección presentarse como casillas de verificación, botones de selección o cuadros de selección desplegables.
• Interruptor: un botón de activación widget. Solo puedes usar interruptores junto con un 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: A botón con una etiqueta de texto. Puedes especificar un relleno de color de fondo para el texto. (el predeterminado es transparente). También puedes deshabilitar el botón como según tus necesidades.
• Entrada de texto: Texto campo de entrada. 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: una columna de varias columnas de diseño que representa una colección de elementos. Puedes representar elementos con una imagen, título y subtítulo, y una variedad de opciones de personalización, como el borde y recortes.

DecoratedText casillas de verificación

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

En el siguiente extracto de código, se muestra cómo definir una casilla de verificación DecoratedText que podrás 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 permitan a los usuarios seleccionar una hora, una fecha o ambas. Puedes usar setOnChangeAction() para asignar una función de controlador de widget a ejecutar cuando cambie el valor del selector.

En el siguiente extracto de código, se muestra cómo definir un selector de solo fecha, un selector 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 del controlador del widget del selector de fecha y hora. Esta da formato y registra una cadena que representa la fecha y hora elegida por el usuario en un widget de selector de fecha y hora con el ID “myDateTime PickerWidgetID”:

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/workspace/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 y dispositivos móviles dispositivos. Cuando se selecciona, el selector de fecha abre una IU de calendario mensual para permitir al usuario seleccionar rápidamente una nueva fecha.

Cuando el usuario elige 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 de la imagen de la que se originó. El usuario también puede ingresar un horario específico. En dispositivos móviles, seleccionar un el selector de hora abre el “reloj” integrado en el dispositivo móvil selector de hora.

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 establece la posición del texto en relación 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. a la acción definida en la 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 el formato HTML de texto simple. Al establecer el contenido de texto de estos widgets, incluye solo las etiquetas HTML correspondientes.

A continuación, se muestran las etiquetas admitidas y su propósito. tabla: