Ações do editor

Usar objetos Action para criar objetos interativos nos 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 widget. que também define a condição que desencadeia a ação. Quando ele é acionado, executa uma função de callback designada. A função de callback recebe um objeto de evento. que transmite informações sobre as interações do usuário no lado do cliente. Você deve 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 seu complemento que crie e exiba um novo cartão quando clicado, siga as etapas abaixo:

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

O exemplo a seguir mostra a criação de um widget de botão. As solicitações de ação o escopo drive.file para o 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 ampliam os editores e usam APIs REST podem incluir uma outra ação de widget para solicitar acesso ao arquivo. Essa ação exige função de callback da ação associada para retornar um objeto de resposta especializado:

Tentativa de ação A função de callback precisa retornar
Solicitar acesso ao arquivo current_document EditorFileScopeActionResponse

Para usar essa ação de widget e o objeto de resposta, todos os itens a seguir precisam ser verdadeiro:

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

Solicitar acesso ao documento atual

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

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

Exemplo: ter acesso aos documentos atuais do app Documentos Google

O exemplo a seguir cria uma interface para o Google Docs que exibe o tamanho do documento atual. Se o complemento não tiver a autorização para drive.file: será exibido um botão para iniciar a autorização do 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();
}