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

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

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

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

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

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

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

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

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

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

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

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

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

مثال

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