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

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

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

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

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

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

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

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

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

بالنسبة إلى كل إجراء، يمكنك تحديد النص الذي يجب أن يظهر في القائمة لهذا الإجراء. ويمكنك بعد ذلك تحديد حقل 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.
}