اقدامات را هدایت کنید

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

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

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

این صفحه اقدامات ویجت مخصوص Drive را که می‌توانید در افزونه خود بگنجانید، شرح می‌دهد.

تعاملات را هدایت کنید

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

اقدام انجام شد	تابع فراخوانی باید مقدار بازگشتی را برگرداند
درخواست دسترسی به فایل‌های انتخاب‌شده	DriveItemsSelectedActionResponse

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

• این اقدام زمانی فعال می‌شود که کاربر یک یا چند مورد از درایو را انتخاب کرده باشد.
• این افزونه شامل محدوده‌ی درایو https://www.googleapis.com/auth/drive.file در مانیفست خود است.

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

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

/**
 * 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 contextual information about
 *    the Drive items selected.
 * @return {Card}
 */
function onDriveItemsSelected(e) {
  var builder =  CardService.newCardBuilder();

  // For each item the user has selected in Drive, display either its
  // quota information or a button that allows the user to provide
  // permission to access that file to retrieve its quota details.
  e['drive']['selectedItems'].forEach(
    function(item){
      var cardSection = CardService.newCardSection()
          .setHeader(item['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 (item['addonHasFileScopePermission']) {
        // If the add-on has access permission, read and display its
        // quota.
        cardSection.addWidget(
          CardService.newTextParagraph().setText(
              "This file takes up: " + getQuotaBytesUsed(item['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")
          .setParameters({id: item.id});

        var button = CardService.newTextButton()
          .setText("Request permission")
          .setOnClickAction(buttonAction);

        cardSection.addWidget(button);
      }

      builder.addSection(cardSection);
    });

  return builder.build();
}

/**
 * Callback function for a button action. Instructs Drive to display a
 * permissions dialog to the user, requesting `drive.file` scope for a
 * specific item on behalf of this add-on.
 *
 * @param {Object} e The parameters object that contains the item's
 *   Drive ID.
 * @return {DriveItemsSelectedActionResponse}
 */
function onRequestFileScopeButtonClicked (e) {
  var idToRequest = e.parameters.id;
  return CardService.newDriveItemsSelectedActionResponseBuilder()
      .requestFileScope(idToRequest).build();
}

/**
 * Use the Advanced Drive Service
 * (See https://developers.google.com/apps-script/advanced/drive),
 * with `drive.file` scope permissions to request the quota usage of a
 * specific Drive item.
 *
 * @param {string} itemId The ID of the item to check.
 * @return {string} A description of the item's quota usage, in bytes.
 */
function getQuotaBytesUsed(itemId) {
  try {
    return Drive.Files.get(itemId,{fields: "quotaBytesUsed"})
        .quotaBytesUsed + " bytes";
  } catch (e) {
    return "Error fetching how much quota this item uses. Error: " + e;
  }
}