Use objetos Action para criar um comportamento interativo 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 IU 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 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 lado do cliente do usuário. Implemente a função de callback e faça com que ela retorne um objeto de resposta específico.
Exemplo: mostrar um novo cartão ao clicar em um botão
Se você quiser adicionar um botão para seu complemento que cria e exibe um novo cartão quando clicado, siga as etapas abaixo:
- Crie um botão widget.
- Para definir uma ação de criação de card, adicione a função gerenciadora de widget de botão
setOnClickAction(action)
. - Crie uma função de callback do Apps Script para ser executada e especifique-a como
(action)
na função do gerenciador de widgets. Nesse caso, a função de callback precisa criar o cartão desejado e retornar um objetoActionResponse
. O objeto de resposta instrui o complemento a exibir o card que a função de callback criou.
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 adicional de widget para solicitar acesso ao arquivo. Esta ação exige que a função de callback de ação associada retorne um objeto de resposta especializado:
Ação realizada | A função de callback vai retornar |
---|---|
Solicitar acesso ao arquivo current_document | EditorFileScopeActionResponse |
Para usar esse objeto de ação e resposta de widget, todas as condições a seguir precisam ser atendidas:
- O complemento usa APIs REST.
- O complemento apresenta a caixa de diálogo do escopo do arquivo de solicitação
usando o método
CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build();
. - O complemento inclui o
escopo de editor
https://www.googleapis.com/auth/drive.file
e o acionadoronFileScopeGranted
no manifesto.
Solicitar acesso ao arquivo do documento atual
Para solicitar acesso de documento atual, siga estas etapas:
- Crie um card da página inicial para verificar se o complemento tem o escopo
drive.file
. - Nos casos em que o complemento não recebeu o escopo
drive.file
, crie uma maneira de solicitar que os usuários concedam o escopodrive.file
ao documento atual.
Exemplo: acessar o documento atual no Documentos Google
O exemplo a seguir cria uma interface para o Documentos Google que exibe o tamanho
do documento atual. Se o complemento não tiver autorização drive.file
,
ele exibirá 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();
}