الإجراءات العامة

والإجراءات العامة هي عناصر عناصر في القائمة تسمح للمستخدم بفتح صفحة ويب جديدة أو عرض بطاقات جديدة لواجهة المستخدم أو تشغيل وظيفة برمجة تطبيقات محددة عند تحديدها. وهي تشبه إلى حد كبير إجراءات البطاقة، باستثناء أنه يتم وضع الإجراءات العامة دائمًا على كل بطاقة في الإضافة، بغض النظر عن سياق الإضافة الحالي.

وباستخدام الإجراءات العامة، يمكنك التأكّد من أنّ المستخدم يستطيع دائمًا الوصول إلى وظائف معيّنة، بغض النظر عن الجزء الذي يتفاعل معه من الإضافة. في ما يلي بعض الأمثلة لحالات الاستخدام للإجراءات الشاملة:

• افتح صفحة إعدادات ويب (أو اعرض بطاقة إعدادات).
• عرض معلومات المساعدة للمستخدم.
• ابدأ سير عمل جديدًا، مثل "إضافة عميل جديد".
• عرض بطاقة تتيح للمستخدم إرسال تعليقات حول الإضافة.

عندما يكون لديك إجراء لا يعتمد على السياق الحالي، فمن الأفضل أن تجعله إجراءً عامًا.

استخدام الإجراءات العامة

تم ضبط الإجراءات العامة في بيان مشروع الإضافة. بعد تهيئة إجراء عام، فإنه يكون متاحًا دائمًا لمستخدمي الإضافة. إذا كان المستخدم يعرض بطاقة، فستظهر مجموعة الإجراءات العامة التي حددتها دائمًا في قائمة البطاقة، بعد أي إجراءات بطاقة حددتها لهذه البطاقة. تظهر الإجراءات العامة في قوائم البطاقات بالترتيب نفسه الذي يتم تحديدها به في بيان الإضافة.

تهيئة الإجراءات العامة

ويمكنك ضبط الإجراءات العامة في بيان الإضافة، ويمكنك الاطّلاع على البيانات للحصول على مزيد من التفاصيل.

بالنسبة إلى كل إجراء، يمكنك تحديد النص الذي يجب أن يظهر في القائمة لهذا الإجراء. يمكنك بعد ذلك تحديد الحقل openLink الذي يشير إلى أنه ينبغي على الإجراء فتح صفحة ويب مباشرة في علامة تبويب جديدة. يمكنك بدلاً من ذلك تحديد حقل runFunction يحدد وظيفة رد اتصال برمجة التطبيقات لتنفيذها عند تحديد الإجراء العام.

عند استخدام runFunction، عادةً ما تنفّذ دالة معاودة الاتصال المحدّدة أحد الإجراءات التالية:

• لإنشاء بطاقات واجهة مستخدم لعرضها فورًا عن طريق عرض عنصر UniversalActionResponse مدمج.
• لفتح عنوان URL، ربما بعد إجراء مهام أخرى، عن طريق عرض عنصر UniversalActionResponse مضمّن.
• تنفيذ مهام الخلفية التي لا تؤدي إلى استخدام بطاقة جديدة أو فتح عنوان URL في هذه الحالة، لا تعرض دالة رد الاتصال أي شيء.

عند استدعائها، يتم تمرير دالة رد الاتصال كائن حدث يحتوي على معلومات حول البطاقة المفتوحة وسياق الإضافة.

تحذير: للإبقاء على استجابة الإضافات، ستقيّد خدمة البطاقة وظائف استدعاء الإجراء الشامل بـ 30 ثانية كحد أقصى من وقت التنفيذ. إذا استغرق التنفيذ وقتًا أطول من ذلك، قد لا تعمل واجهة مستخدم الإضافة على تحديث عرضها بشكلٍ صحيح.

مثال

يعرض مقتطف الرمز التالي مثالاً على مقتطف بيان لإحدى إضافات 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.
}