Düzenleyici işlemleri

Google Workspace eklentilerine etkileşimli davranışlar eklemek için İşlem nesnelerini kullanın.

İşlem nesneleri, kullanıcı eklenti kullanıcı arayüzündeki bir widget'la (ör. düğme) etkileşimde bulunduğunda ne olacağını tanımlar.

Widget'a işlem ekleme

Bir widget'a işlem eklemek için widget işleyici işlevi kullanın. Bu işlev, işlemi tetikleyen koşulu da tanımlar. İşlem tetiklendiğinde, belirlenen bir geri çağırma işlevi yürütülür. Geri çağırma işlevine, kullanıcının istemci tarafındaki etkileşimleriyle ilgili bilgileri taşıyan bir etkinlik nesnesi iletilir. Geri arama işlevini uygulamanız ve belirli bir yanıt nesnesini döndürmesi gerekir.

Örnek: Bir düğmeye tıklandığında yeni bir kart görüntüleme

Eklentinize, tıklandığında yeni bir kart oluşturan ve görüntüleyen bir düğme eklemek istiyorsanız aşağıdaki adımları uygulayın:

  1. Bir düğme widget'ı oluşturun.
  2. Kart oluşturma işlemi ayarlamak için düğme widget'ı işleyici işlevini setOnClickAction(action) ekleyin.
  3. Çalıştırmak için bir Apps Komut Dosyası geri çağırma işlevi oluşturun ve widget işleyici işlevi içinde (action) olarak belirtin. Bu durumda geri çağırma işlevi, istediğiniz kartı oluşturmalı ve bir ActionResponse nesnesi döndürmelidir. Yanıt nesnesi, eklentiye geri çağırma işlevinin oluşturduğu kartı göstermesini söyler.

Aşağıdaki örnekte bir düğme widget'ının oluşturulması gösterilmektedir. İşlem, eklenti adına mevcut dosya için drive.file kapsamını ister.

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

REST API'ler için dosya erişim etkileşimleri

Düzenleyiciler'i genişleten ve REST API'leri kullanan Google Workspace eklentileri, dosya erişimi isteğinde bulunmak için ek bir widget işlemi içerebilir. Bu işlem için ilişkili işlem geri çağırma işlevinin özel bir yanıt nesnesi döndürmesi gerekir:

İşlem deneniyor Geri çağırma işlevi şunu döndürmelidir:
current_document için dosya erişimi isteğinde bulun EditorFileScopeActionResponse

Bu widget işlemi ve yanıt nesnesinden yararlanmak için aşağıdakilerin tümü doğru olmalıdır:

  • Eklenti, REST API'lerini kullanır.
  • Eklenti, CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build(); yöntemini kullanarak istek dosyası kapsamı iletişim kutusunu gösterir.
  • Eklenti, manifest dosyasında https://www.googleapis.com/auth/drive.file düzenleyici kapsamını ve onFileScopeGranted tetikleyicisini içeriyor.

Geçerli doküman için dosya erişimi isteğinde bulunma

Mevcut doküman için dosya erişimi isteğinde bulunmak üzere aşağıdaki adımları uygulayın:

  1. Eklentinin drive.file kapsamına sahip olup olmadığını kontrol eden bir ana sayfa kartı oluşturun.
  2. Eklenti için drive.file kapsamı verilmemişse kullanıcılardan mevcut doküman için drive.file kapsamı vermelerini istemenin bir yolunu oluşturun.

Örnek: Google Dokümanlar'da geçerli dokümana erişim izni alma

Aşağıdaki örnekte, Google Dokümanlar için geçerli dokümanın boyutunu gösteren bir arayüz oluşturulmaktadır. Eklentide drive.file yetkilendirmesi yoksa dosya kapsamı yetkilendirmesini başlatmak için bir düğme gösterilir.

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