اقدامات ویرایشگر

از اشیاء Action برای ایجاد رفتار تعاملی در افزونه‌های Google Workspace استفاده کنید.

اشیاء عمل تعریف می کنند که وقتی کاربر با یک ویجت (مثلاً یک دکمه) در رابط کاربری افزونه تعامل می کند چه اتفاقی می افتد.

یک اقدام به ویجت اضافه کنید

برای پیوست کردن یک کنش به یک ویجت، از یک تابع کنترل کننده ویجت استفاده کنید، که همچنین شرایطی را که اقدام را راه‌اندازی می‌کند، تعریف می‌کند. وقتی فعال می‌شود، عملکرد یک تابع بازخوانی تعیین‌شده را اجرا می‌کند. تابع callback به یک شی رویداد ارسال می شود که اطلاعات مربوط به تعاملات سمت مشتری کاربر را حمل می کند. شما باید تابع callback را پیاده سازی کنید و از آن بخواهید یک شی پاسخ خاص را برگرداند.

مثال: با کلیک روی یک دکمه، یک کارت جدید را نمایش دهید

اگر می خواهید دکمه ای را به افزونه خود اضافه کنید که با کلیک روی آن یک کارت جدید ساخته و نمایش داده شود، مراحل زیر را دنبال کنید:

1. یک ویجت دکمه ایجاد کنید.
2. برای تنظیم یک اقدام ساخت کارت، تابع کنترل کننده ویجت دکمه setOnClickAction(action) را اضافه کنید.
3. یک تابع فراخوانی Apps Script ایجاد کنید تا اجرا شود و آن را به عنوان (action) در تابع کنترل کننده ویجت مشخص کنید. در این حالت، تابع callback باید کارت مورد نظر را بسازد و یک شی ActionResponse را برگرداند. شیء پاسخ به افزونه می‌گوید که کارتی را که تابع پاسخ به تماس ساخته شده است نمایش دهد.

مثال زیر ایجاد یک ویجت دکمه را نشان می دهد. این عمل از طرف افزونه، محدوده drive.file را برای فایل فعلی درخواست می کند.

/**
 * 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

افزونه‌های Google Workspace که ویرایشگرها را گسترش می‌دهند و از APIهای REST استفاده می‌کنند، می‌توانند یک اقدام ویجت اضافی برای درخواست دسترسی به فایل داشته باشند. این عمل به تابع مربوط به تماس پاسخ نیاز دارد تا یک شی پاسخ تخصصی را برگرداند:

اقدامی انجام شد	تابع Callback باید برگردد
درخواست دسترسی فایل برای current_document	EditorFileScopeActionResponse

برای استفاده از این شیء اقدام و پاسخ ویجت، تمام موارد زیر باید درست باشد:

• این افزونه از REST API استفاده می کند.
• افزونه گفتگوی دامنه فایل درخواست را با استفاده از CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build(); روش
• این افزونه شامل https://www.googleapis.com/auth/drive.file دامنه ویرایشگر و فعال کننده onFileScopeGranted در مانیفست خود است.

درخواست دسترسی به فایل برای سند فعلی

برای درخواست دسترسی به فایل برای سند فعلی، این مراحل را دنبال کنید:

1. یک کارت صفحه اصلی بسازید که بررسی می کند که آیا افزونه دارای محدوده drive.file است یا خیر.
2. برای مواردی که به افزونه دامنه drive.file اعطا نشده است، راهی بسازید تا از کاربران درخواست کنید که محدوده drive.file برای سند فعلی اعطا کنند.

مثال: دسترسی به سند فعلی را در Google Docs دریافت کنید

مثال زیر یک رابط برای Google Docs می سازد که اندازه سند فعلی را نمایش می دهد. اگر افزونه دارای مجوز drive.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(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();
}