توسيع واجهة مستخدم الرسالة

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

Google Workspace يمكن أن تؤدي الإضافات التي توسِّع Gmail إلى توفير واجهة مستخدم أثناء قراءة المستخدم للرسائل. يسمح هذا الإجراء Google Workspace الإضافات ببرمجة المهام التي تستجيب لمحتوى الرسالة، مثل عرض معلومات إضافية حول الرسالة أو استردادها أو إرسالها.

الوصول إلى واجهة مستخدم رسائل الإضافة

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

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

إنشاء إضافة رسائل

يمكنك إضافة وظائف الرسائل إلى إحدى الإضافات باتباع الخطوات العامة التالية:

  1. أضِف الحقول المناسبة إلى بيان النص البرمجي للإضافة، بما في ذلك النطاقات المطلوبة لوظائف الرسالة. احرص على إضافة حقل عامل تشغيل شرطي في البيان، مع تضمين القيمة unconditional في {}.
  2. نفِّذ دالة مشغِّل السياق التي تنشئ واجهة مستخدم لرسالة عندما يختار المستخدم الإضافة في الرسالة.
  3. نفِّذ الدوال المرتبطة اللازمة للتفاعل مع تفاعلات واجهة المستخدم.

عوامل تشغيل السياق

لتقديم مساعدة للمستخدمين عند قراءة الرسائل، يمكنGoogle Workspace للإضافات أن تحدّد مشغّل سياقيًا في البيانات. عندما يفتح المستخدم رسالة Gmail (مع فتح الإضافة) التي تستوفي معايير المشغِّل * يتم تنشيط المشغِّل. ينفِّذ مشغِّل نارٍ وظيفة مشغِّل سياقي تُنشئ واجهة مستخدم الإضافة وتعرضها لخدمة Gmail لعرضها. وفي هذه المرحلة، يمكن للمستخدم بدء التفاعل معها.

يتم تحديد العوامل المشغِّلة للمحتوى في ملف البيان في مشروع الإضافات. يحدّد تعريف المشغّل Gmail عامل التشغيل الذي يجب تنشيطه وفقًا للشروط. على سبيل المثال، يضبط مقتطف البيان هذا مشغِّل غير مشروط يستدعي دالة المشغِّل onGmailMessageOpen() عند فتح الرسالة:

{
  ...
  "addOns": {

    "common": {
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onGmailMessageOpen"
        }
      ],
      ...
    },
    ...
  }
  ...
}

دالة التشغيل السياقي

يجب أن يكون لكل عامل تشغيل سياقي وظيفة مشغِّل مشغِّلة تُنشئ واجهة مستخدم الإضافة. ويمكنك تحديد هذه الدالة في الحقل manifest's onTriggerFunction. يمكنك تنفيذ هذه الدالة لقبول كائن حدث إجراء وعرض إما كائن واحد Card أو مصفوفة من Card كائنات.

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

  // Activate temporary Gmail scopes, in this case to allow
  // the add-on to read message metadata and content.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  // Read message metadata and content. This requires the Gmail scope
  // https://www.googleapis.com/auth/gmail.addons.current.message.readonly.
  var messageId = e.gmail.messageId;
  var message = GmailApp.getMessageById(messageId);
  var subject = message.getSubject();
  var sender = message.getFrom();
  var body = message.getPlainBody();
  var messageDate = message.getDate();

  // Setting the access token with a gmail.addons.current.message.readonly
  // scope also allows read access to the other messages in the thread.
  var thread = message.getThread();
  var threadMessages = thread.getMessages();

  // Using this link can avoid the need to copy message or thread content
  var threadLink = thread.getPermalink();

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

يجب أن تنشئ دالة المشغِّل مصفوفة من كائنات Card المُصمَّمة وتعرضها. على سبيل المثال، ينشئ ما يلي إضافة مع بطاقة واحدة تسرد فقط موضوع الرسالة والمرسِل:

  function onGmailMessageOpen(e) {
    // Activate temporary Gmail scopes, in this case to allow
    // message metadata to be read.
    var accessToken = e.gmail.accessToken;
    GmailApp.setCurrentMessageAccessToken(accessToken);

    var messageId = e.gmail.messageId;
    var message = GmailApp.getMessageById(messageId);
    var subject = message.getSubject();
    var sender = message.getFrom();

    // Create a card with a single card section and two widgets.
    // Be sure to execute build() to finalize the card construction.
    var exampleCard = CardService.newCardBuilder()
        .setHeader(CardService.newCardHeader()
            .setTitle('Example card'))
        .addSection(CardService.newCardSection()
            .addWidget(CardService.newKeyValue()
                .setTopLabel('Subject')
                .setContent(subject))
            .addWidget(CardService.newKeyValue()
                .setTopLabel('From')
                .setContent(sender)))
        .build();   // Don't forget to build the Card!
    return [exampleCard];
  }