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

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

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

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

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

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

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

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

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

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

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