Acciones del editor

Usa objetos Action para compilar imágenes comportamiento en los complementos de Google Workspace.

Los objetos de acción definen lo que sucede cuando un usuario interactúa con un widget (por ejemplo, un botón) en la IU del complemento.

Cómo agregar una acción a un widget

Para adjuntar una acción a un widget, usa una función de controlador del widget, que también define la condición que activa la acción. Cuando se activa, ejecuta una función de devolución de llamada designada. La función de devolución de llamada recibe un objeto de evento. que transporta información sobre las interacciones del usuario con el cliente. Debes implementar la función de devolución de llamada y hacer que devuelva un objeto de respuesta específico.

Ejemplo: Cómo mostrar una tarjeta nueva cuando se hace clic en un botón

Si quieres agregar un botón a tu complemento que cree y muestre una tarjeta nueva al hacer clic en él, sigue estos pasos:

  1. Crea un widget de botón.
  2. Para configurar una acción de creación de tarjetas, agrega la función del controlador del widget del botón setOnClickAction(action)
  3. Crea una función de devolución de llamada de Apps Script para ejecutarla y especificarla como (action) dentro de la función del controlador del widget. En este caso, la función de devolución de llamada Deberías crear la tarjeta que desees y mostrar un objeto ActionResponse. El objeto de respuesta le indica al complemento que muestre la tarjeta que compiló la función de devolución de llamada.

En el siguiente ejemplo, se muestra la creación de un widget de botón. La acción solicita el alcance drive.file del archivo actual en nombre del complemento.

/**
 * Adds a section to the Card Builder that displays a "REQUEST PERMISSION" button.
 * When it's clicked, the callback triggers file scope permission flow. This is used in
 * the add-on when the home-page displays basic data.
 */
function addRequestFileScopeButtonToBuilder(cardBuilder) {
    var buttonSection = CardService.newCardSection();
    // If the add-on does not have access permission, add a button that
    // allows the user to provide that permission on a per-file basis.
    var buttonAction = CardService.newAction()
      .setFunctionName("onRequestFileScopeButtonClickedInEditor");

    var button = CardService.newTextButton()
      .setText("Request permission")
      .setBackgroundColor("#4285f4")
      .setTextButtonStyle(CardService.TextButtonStyle.FILLED)
      .setOnClickAction(buttonAction);

    buttonSection.addWidget(button);
    cardBuilder.addSection(buttonSection);
}

/**
 * Callback function for a button action. Instructs Docs to display a
 * permissions dialog to the user, requesting `drive.file` scope for the 
 * current file on behalf of this add-on.
 *
 * @param {Object} e The parameters object that contains the document’s ID
 * @return {editorFileScopeActionResponse}
 */
function onRequestFileScopeButtonClickedInEditor(e) {
  return CardService.newEditorFileScopeActionResponseBuilder()
      .requestFileScopeForActiveDocument().build();

Interacciones de acceso a archivos para las APIs de REST

Los complementos de Google Workspace que extienden los editores y usan APIs de REST pueden incluir un acción adicional de widget para solicitar acceso al archivo. Para realizar esta acción, se requiere función de devolución de llamada de acción asociada para mostrar un objeto de respuesta especializado:

Acción realizada La función de devolución de llamada debería mostrar
Solicita acceso al archivo de current_document EditorFileScopeActionResponse

Para usar esta acción de widget y el objeto de respuesta, se deben cumplir todas las siguientes condiciones ser verdadero:

  • El complemento usa las APIs de REST.
  • El complemento presenta el diálogo de la solicitud del alcance del archivo con el método CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build();
  • El complemento incluye la https://www.googleapis.com/auth/drive.file permiso del editor y activador onFileScopeGranted en su manifiesto.

Solicitar acceso a los archivos para el documento actual

Para solicitar acceso a los archivos del documento actual, sigue estos pasos:

  1. Compila una tarjeta en la página principal que verifique si el complemento tiene permiso de drive.file.
  2. En los casos en los que no se haya otorgado el permiso drive.file al complemento, crea un Esta es una forma de solicitar que los usuarios otorguen el permiso drive.file al documento actual.

Ejemplo: Obtén acceso a un documento actual en Documentos de Google

En el siguiente ejemplo, se crea una interfaz para Documentos de Google que muestra el tamaño del documento actual. Si el complemento no tiene autorización de drive.file, ocurrirá lo siguiente: muestra un botón para iniciar la autorización del alcance del archivo.

/**
 * Build a simple card that checks selected items' quota usage. Checking
 * quota usage requires user-permissions, so this add-on provides a button
 * to request `drive.file` scope for items the add-on doesn't yet have
 * permission to access.
 *
 * @param e The event object passed containing information about the
 *   current document.
 * @return {Card}
 */
function onDocsHomepage(e) {
  return createAddOnView(e);
}

function onFileScopeGranted(e) {
  return createAddOnView(e);
}

/**
 * For the current document, display either its quota information or
 * a button that allows the user to provide permission to access that
 * file to retrieve its quota details.
 *
 * @param e The event containing information about the current document
 * @return {Card}
 */
function createAddOnView(e) {
  var docsEventObject = e['docs'];
  var builder =  CardService.newCardBuilder();

  var cardSection = CardService.newCardSection();
  if (docsEventObject['addonHasFileScopePermission']) {
    cardSection.setHeader(docsEventObject['title']);
    // This add-on uses the recommended, limited-permission `drive.file`
    // scope to get granular per-file access permissions.
    // See: https://developers.google.com/drive/api/v2/about-auth
    // If the add-on has access permission, read and display its quota.
    cardSection.addWidget(
      CardService.newTextParagraph().setText(
          "This file takes up: " + getQuotaBytesUsed(docsEventObject['id'])));
  } else {
    // If the add-on does not have access permission, add a button that
    // allows the user to provide that permission on a per-file basis.
    cardSection.addWidget(
      CardService.newTextParagraph().setText(
          "The add-on needs permission to access this file's quota."));

    var buttonAction = CardService.newAction()
      .setFunctionName("onRequestFileScopeButtonClicked");

    var button = CardService.newTextButton()
      .setText("Request permission")
      .setOnClickAction(buttonAction);

    cardSection.addWidget(button);
  }
  return builder.addSection(cardSection).build();
}

/**
 * Callback function for a button action. Instructs Docs to display a
 * permissions dialog to the user, requesting `drive.file` scope for the
 * current file on behalf of this add-on.
 *
 * @param {Object} e The parameters object that contains the document’s ID
 * @return {editorFileScopeActionResponse}
 */
function onRequestFileScopeButtonClicked(e) {
  return CardService.newEditorFileScopeActionResponseBuilder()
      .requestFileScopeForActiveDocument().build();
}