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

الإجراءات العامة هي عناصر قائمة تتيح للمستخدم فتح صفحة ويب أو عرض بطاقات واجهة مستخدم جديدة أو تشغيل وظيفة "برمجة تطبيقات 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.
}