Ações do editor

Use objetos Action para criar comportamento interativo em complementos do Google Workspace.

Os objetos de ação definem o que acontece quando um usuário interage com um widget (por exemplo, um botão) na interface do complemento.

Adicionar uma ação a um widget

Para anexar uma ação a um widget, use uma função de gerenciador de widgets, que também define a condição que aciona a ação. Quando acionada, a ação executa uma função de callback designada. A função de callback recebe um objeto de evento que carrega informações sobre as interações do usuário no lado do cliente. É necessário implementar a função de callback e fazer com que ela retorne um objeto de resposta específico.

Exemplo: mostrar um novo card quando um botão é clicado

Se você quiser adicionar um botão ao complemento que cria e mostra um novo card quando clicado, siga as etapas abaixo:

  1. Crie um widget de botão.
  2. Para definir uma ação de criação de card, adicione a função de gerenciador de widgets de botão setOnClickAction(action).
  3. Crie uma função de callback do Apps Script para executar e especifique-a como (action) na função do gerenciador de widgets. Nesse caso, a função de callback precisa criar o card que você quer e retornar um objeto ActionResponse. O objeto de resposta informa ao complemento que ele precisa mostrar o card criado pela função de callback.

O exemplo a seguir mostra a criação de um widget de botão. A ação solicita o escopo drive.file do arquivo atual em nome do 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();

Interações de acesso a arquivos para APIs REST

Os complementos do Google Workspace que estendem os editores e usam APIs REST podem incluir uma ação de widget extra para solicitar acesso a arquivos. Essa ação exige que a função de callback de ação associada retorne um objeto de resposta especializado:

Tentativa de ação A função de callback precisa retornar
Solicitar acesso a arquivos para current_document EditorFileScopeActionResponse

Para usar essa ação e objeto de resposta do widget, todos os seguintes requisitos precisam ser atendidos:

  • O complemento usa APIs REST.
  • O complemento apresenta a caixa de diálogo de escopo do arquivo de solicitação usando o método CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build();.
  • O complemento inclui o escopo do editor https://www.googleapis.com/auth/drive.file e o acionador onFileScopeGranted no manifesto.

Solicitar acesso ao arquivo para o documento atual

Para solicitar acesso ao arquivo do documento atual, siga estas etapas:

  1. Crie um card da página inicial que verifique se o complemento tem escopo drive.file.
  2. Para casos em que o complemento não recebeu o escopo drive.file, crie uma maneira de solicitar que os usuários concedam o escopo drive.file para o documento atual.

Exemplo: receber acesso ao documento atual nos Documentos Google

O exemplo a seguir cria uma interface para o Google Docs que mostra o tamanho do documento atual. Se o complemento não tiver autorização drive.file, um botão será exibido para iniciar a autorização de escopo do arquivo.

/**
 * 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();
}