Tindakan editor

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Gunakan objek Action untuk mem-build perilaku interaktif ke dalam Google Workspace Add-on.

Objek tindakan menentukan apa yang terjadi ketika pengguna berinteraksi dengan widget (misalnya, tombol) dalam UI add-on.

Menambahkan tindakan ke widget

Untuk melampirkan tindakan ke widget, gunakan fungsi pengendali widget, yang juga menentukan kondisi yang memicu tindakan. Saat dipicu, tindakan tersebut akan menjalankan fungsi callback yang ditetapkan. Fungsi callback diteruskan objek peristiwa yang membawa informasi tentang interaksi sisi klien pengguna. Anda harus mengimplementasikan fungsi callback dan memintanya menampilkan objek respons tertentu.

Contoh: Menampilkan kartu baru saat tombol diklik

Jika ingin menambahkan tombol ke add-on yang membuat dan menampilkan kartu baru saat diklik, ikuti langkah-langkah di bawah ini:

  1. Buat tombol baru widget.
  2. Untuk menetapkan tindakan pembuatan kartu, tambahkan fungsi pengendali widget tombol setOnClickAction(action).
  3. Buat fungsi callback Apps Script untuk mengeksekusi dan menetapkannya sebagai (action) dalam fungsi pengendali widget. Dalam hal ini, fungsi callback harus membuat kartu yang Anda inginkan dan menampilkan objek ActionResponse. Objek respons memberi tahu add-on untuk menampilkan kartu yang dibuat oleh fungsi callback.

Contoh berikut menunjukkan pembuatan widget tombol. Tindakan ini meminta cakupan drive.file untuk file saat ini atas nama add-on.

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

Interaksi akses file untuk REST API

Google Workspace Add-on yang memperluas Editor dan menggunakan REST API dapat mencakup tindakan widget tambahan untuk meminta akses file. Tindakan ini memerlukan fungsi callback tindakan terkait untuk menampilkan objek respons khusus:

Tindakan dicoba Fungsi callback akan ditampilkan
Meminta akses file untuk current_document EditorFileScopeActionResponse

Untuk memanfaatkan tindakan widget dan objek respons ini, semua hal berikut harus terpenuhi:

  • Add-on menggunakan REST API.
  • Add-on menampilkan dialog cakupan file permintaan menggunakan CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build();.
  • Add-on ini menyertakan cakupan Editor https://www.googleapis.com/auth/drive.file dalam manifesnya.

Minta akses file untuk dokumen saat ini

Untuk meminta akses file bagi dokumen saat ini, ikuti langkah-langkah berikut:

  1. Buat kartu halaman beranda yang memeriksa apakah add-on memiliki cakupan drive.file.
  2. Jika add-on belum diberi cakupan drive.file, buat cara untuk meminta pengguna memberikan cakupan drive.file bagi dokumen saat ini.

Contoh: Mendapatkan akses dokumen saat ini di Google Dokumen

Contoh berikut membuat antarmuka untuk Google Dokumen yang menampilkan ukuran dokumen saat ini. Jika tidak memiliki otorisasi drive.file, add-on akan menampilkan tombol untuk memulai otorisasi cakupan file.

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

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