اقدامات جهانی

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

با استفاده از کنش‌های جهانی، می‌توانید مطمئن شوید که کاربر همیشه به عملکردهای خاصی دسترسی دارد، صرف نظر از اینکه با کدام قسمت از افزونه شما تعامل دارد. در اینجا چند نمونه از موارد استفاده برای اقدامات جهانی آورده شده است:

  • یک صفحه وب تنظیمات را باز کنید (یا یک کارت تنظیمات را نمایش دهید).
  • اطلاعات راهنما را به کاربر نشان دهید.
  • یک گردش کار جدید مانند «افزودن مشتری جدید» را شروع کنید.
  • کارتی را نمایش دهید که به کاربر امکان می‌دهد درباره افزونه بازخورد ارسال کند.

هر زمان که اقدامی دارید که به شرایط فعلی بستگی ندارد، باید در نظر داشته باشید که آن را به یک اقدام جهانی تبدیل کنید.

استفاده از اقدامات جهانی

کنش‌های جهانی در مانیفست پروژه افزونه شما پیکربندی می‌شوند. هنگامی که یک کنش جهانی را پیکربندی کردید، همیشه برای کاربران افزونه شما در دسترس است. اگر کاربر در حال مشاهده یک کارت است، مجموعه اقدامات جهانی که تعریف کرده‌اید همیشه در منوی کارت ظاهر می‌شود، پس از هر اقدام کارتی که برای آن کارت تعریف کرده‌اید. کنش‌های جهانی به همان ترتیبی که در مانیفست افزونه تعریف شده‌اند، در منوهای کارت ظاهر می‌شوند.

پیکربندی اقدامات جهانی

شما اقدامات جهانی را در مانیفست افزونه خود پیکربندی می کنید. برای جزئیات بیشتر به Manifests مراجعه کنید.

برای هر عمل، متنی را مشخص می‌کنید که باید در منوی آن عمل ظاهر شود. سپس می توانید یک فیلد openLink را مشخص کنید که نشان می دهد این عمل باید مستقیماً یک صفحه وب را در یک برگه جدید باز کند. همچنین، می‌توانید یک فیلد runFunction را مشخص کنید که یک تابع فراخوانی Apps Script را مشخص می‌کند تا هنگام انتخاب کنش جهانی اجرا شود.

وقتی از runFunction استفاده می شود، تابع callback مشخص شده معمولاً یکی از کارهای زیر را انجام می دهد:

  • کارت‌های UI را می‌سازد تا با برگرداندن یک شی UniversalActionResponse ساخته شده، فوراً نمایش داده شوند.
  • با برگرداندن یک شی UniversalActionResponse ساخته شده، URL را باز می کند، شاید پس از انجام کارهای دیگر.
  • کارهای پس‌زمینه‌ای را انجام می‌دهد که به کارت جدید تغییر نمی‌کنند یا URL را باز نمی‌کنند. در این حالت تابع callback هیچ چیزی را بر نمی گرداند.

هنگام فراخوانی، تابع callback به یک شی رویداد ارسال می شود که حاوی اطلاعات مربوط به کارت باز و زمینه افزودنی است.

مثال

قطعه کد زیر نمونه ای از گزیده مانیفست را برای یک افزونه Google Workspace نشان می دهد که از اقدامات جهانی در حین گسترش Gmail استفاده می کند. کد به صراحت یک محدوده ابرداده را تنظیم می کند تا افزونه بتواند تعیین کند که چه کسی پیام باز را ارسال کرده است.

  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata"
  ],
  "addOns": {
    "common": {
      "name": "Universal Actions Only Addon",
      "logoUrl": "https://www.example.com/hosted/images/2x/my-icon.png",
      "openLinkUrlPrefixes": [
        "https://www.google.com",
        "https://www.example.com/urlbase"
      ],
      "universalActions": [{
          "label": "Open google.com",
          "openLink": "https://www.google.com"
        }, {
          "label": "Open contact URL",
          "runFunction": "openContactURL"
        }, {
          "label": "Open settings",
          "runFunction": "createSettingsResponse"
        }, {
          "label": "Run background sync",
          "runFunction": "runBackgroundSync"
      }],
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "getContextualAddOn"
        }
      ]
    },
    ...
  },
  ...

سه عمل جهانی تعریف شده در مثال قبل به شرح زیر است:

  • باز کردن google.com https://www.google.com را در یک برگه جدید باز می کند.
  • URL مخاطب باز تابعی را اجرا می کند که تعیین می کند چه URL باید باز شود و سپس آن را با استفاده از یک شی OpenLink در یک برگه جدید باز می کند. کد URL را با استفاده از آدرس ایمیل فرستنده می سازد.
  • تنظیمات باز تابع createSettingsCards() تعریف شده در پروژه اسکریپت الحاقی را اجرا می کند. این تابع یک شیء معتبر UniversalActionResponse حاوی مجموعه‌ای از کارت‌ها با تنظیمات افزودنی و اطلاعات دیگر را برمی‌گرداند. پس از اتمام ساخت این شیء، رابط کاربری لیستی از کارت ها را نمایش می دهد ( به بازگشت چند کارت مراجعه کنید).
  • اجرای همگام‌سازی پس‌زمینه، تابع runBackgroundSync() تعریف شده در پروژه اسکریپت الحاقی را اجرا می‌کند. این تابع کارت نمی سازد. در عوض، برخی از کارهای پس‌زمینه دیگر را انجام می‌دهد که رابط کاربری را تغییر نمی‌دهند. از آنجایی که تابع UniversalActionResponse برنمی‌گرداند، پس از اتمام عملکرد، رابط کاربری کارت جدیدی را نمایش نمی‌دهد. در عوض، رابط کاربری یک چرخنده نشانگر بارگیری را در حالی که عملکرد در حال اجرا است نمایش می دهد.

در اینجا مثالی از نحوه ساخت توابع openContactURL() ، createSettingsResponse() و runBackgroundSync() آورده شده است:

/**
 * Open a contact URL.
 * @param {Object} e an event object
 * @return {UniversalActionResponse}
 */
function openContactURL(e) {
  // Activate temporary Gmail scopes, in this case so that the
  // open message metadata can be read.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  // Build URL to open based on a base URL and the sender's email.
  // This URL must be included in the openLinkUrlPrefixes whitelist.
  var messageId = e.gmail.messageId;
  var message = GmailApp.getMessageById(messageId);
  var sender = message.getFrom();
  var url = "https://www.example.com/urlbase/" + sender;
  return CardService.newUniversalActionResponseBuilder()
      .setOpenLink(CardService.newOpenLink()
          .setUrl(url))
      .build();
}

/**
 * Create a collection of cards to control the add-on settings and
 * present other information. These cards are displayed in a list when
 * the user selects the associated "Open settings" universal action.
 *
 * @param {Object} e an event object
 * @return {UniversalActionResponse}
 */
function createSettingsResponse(e) {
  return CardService.newUniversalActionResponseBuilder()
      .displayAddOnCards(
          [createSettingCard(), createAboutCard()])
      .build();
}

/**
 * Create and return a built settings card.
 * @return {Card}
 */
function createSettingCard() {
  return CardService.newCardBuilder()
      .setHeader(CardService.newCardHeader().setTitle('Settings'))
      .addSection(CardService.newCardSection()
          .addWidget(CardService.newSelectionInput()
              .setType(CardService.SelectionInputType.CHECK_BOX)
              .addItem("Ask before deleting contact", "contact", false)
              .addItem("Ask before deleting cache", "cache", false)
              .addItem("Preserve contact ID after deletion", "contactId", false))
          // ... continue adding widgets or other sections here ...
      ).build();   // Don't forget to build the card!
}

/**
 * Create and return a built 'About' informational card.
 * @return {Card}
 */
function createAboutCard() {
  return CardService.newCardBuilder()
      .setHeader(CardService.newCardHeader().setTitle('About'))
      .addSection(CardService.newCardSection()
          .addWidget(CardService.newTextParagraph()
              .setText('This add-on manages contact information. For more '
                  + 'details see the <a href="https://www.example.com/help">'
                  + 'help page</a>.'))
      // ... add other information widgets or sections here ...
      ).build();  // Don't forget to build the card!
}

/**
 * Run background tasks, none of which should alter the UI.
 * Also records the time of sync in the script properties.
 *
 * @param {Object} e an event object
 */
function runBackgroundSync(e) {
  var props = PropertiesService.getUserProperties();
  props.setProperty("syncTime", new Date().toString());

  syncWithContacts();  // Not shown.
  updateCache();       // Not shown.
  validate();          // Not shown.

  // no return value tells the UI to keep showing the current card.
}