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

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

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

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

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

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

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

ضبط الإجراءات العامة

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

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

عند استخدام 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.
}