صفحات رئيسية

الصفحات الرئيسية هي ميزة جديدة في إضافات Google Workspace، تتيح إمكانية تحديد بطاقة واحدة أو أكثر غير مستندة إلى السياق. تُستخدَم البطاقات غير السياقية لعرض واجهة مستخدم عندما يكون المستخدم خارج سياق معيّن، مثل عندما يعرض المستخدم بريد Gmail الوارد ولكنه لم يفتح رسالة أو مسودة.

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

يمكنك تحديد صفحة رئيسية للإضافات من خلال تحديدها في بيان مشروعك وتنفيذ وظيفة homepageTrigger واحدة أو أكثر (راجِع إعداد الصفحة الرئيسية).

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

يتم عرض الصفحة الرئيسية للإضافات عند استيفاء أحد الشروط التالية:

  • عند فتح الإضافة لأول مرة في المضيف (بعد التفويض)
  • عندما ينتقل المستخدم من سياق سياقي إلى سياق غير سياقي عندما تكون الإضافة مفتوحة على سبيل المثال، من تعديل حدث في "تقويم Google" إلى التقويم الرئيسي.
  • عندما ينقر المستخدم على زر الرجوع عددًا كافيًا من المرات لإخراج كل البطاقات الأخرى من الحِزم الداخلية
  • عندما يؤدي تفاعل مع واجهة المستخدم في بطاقة غير سياقية إلى Navigation.popToRoot() طلب

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

إعداد الصفحة الرئيسية

تستخدم إضافات Google Workspace الحقل addOns.common.homepageTrigger لضبط محتوى الصفحة الرئيسية التلقائي (غير السياقي) للإضافات لجميع التطبيقات المستضافة في بيان الإضافة:

    {
      // ...
      "addOns": {
        // ...
        "common": {
          // ...
          "homepageTrigger": {
            "runFunction": "myFunction",
            "enabled": true
          }
        }
      }
    }

  • runFunction: اسم دالة "برمجة تطبيقات Google" التي يستدعيها إطار عمل إضافات Google Workspace لعرض بطاقات إضافات الصفحة الرئيسية. هذه الدالة هي دالة تشغيل الصفحة الرئيسية. يجب أن تنشئ هذه الدالة ملفًا شخصيًا وتُرجع صفيفًا من عناصر Card التي تشكّل واجهة مستخدم الصفحة الرئيسية. إذا تم عرض أكثر من بطاقة واحدة، يعرض التطبيق المضيف رؤوس البطاقات في قائمة يمكن للمستخدم الاختيار منها (راجِع عرض بطاقات متعددة).

  • ‫enabled: ما إذا كان يجب تفعيل بطاقات الصفحة الرئيسية لهذا النطاق هذا الحقل اختياري، ويتم ضبطه تلقائيًا على true. يؤدي ضبط هذا الخيار على false إلى إيقاف بطاقات الصفحة الرئيسية لجميع المضيفين (ما لم يتم إلغاء هذا الإعداد لذلك المضيف، راجِع المعلومات أدناه).

بالإضافة إلى الإعدادات الشائعة، تتوفّر أيضًا إعدادات بديلاً منظَّمة بشكلٍ متطابق لكل مضيف في ملف تكوين كل تطبيق مضيف، في addOns.gmail.homepageTrigger وaddOns.calendar.homepageTrigger وما إلى ذلك:

    {
      ...
      "addOns": {
        ...
        "common": {
          // By default, call 'buildHomePage' to render homepage content
          // in all hosts. Since calendar.homepageTrigger below overrides
          // this in Calendar and Drive and the homepageTrigger is disabled
          // for Gmail, this homepage function never executes.
          "homepageTrigger": { "runFunction": "buildHomePage" }
        },
        "calendar": {
          // Show customized homepage content for Calendar only.
          "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
        },
        "drive": {
          // Show customized homepage content for Drive only.
          "homepageTrigger": { "runFunction": "buildDriveHomepage" }
        }
        "gmail": {
          // Disable homepage add-on content in Gmail.
          "homepageTrigger": { "enabled": false }
        },
        ...
      }
    }

يُرجى العلم أنّ هذا الإجراء يعادل المقتطف التالي من البيان:

    {
      ...
      "addOns": {
        ...
        "common": { /* ... */ }, // Omitted a default homepageTrigger specification.
        "calendar": {
          // Show customized homepage content for Calendar only.
          "homepageTrigger": { "runFunction": "myCalendarFunction" }
        },
        "drive": {
          // Show customized homepage content for Drive only.
          "homepageTrigger": { "runFunction": "myDriveFunction" }
        }
        "gmail": { /* ... */ },
        ...
      }
    }

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

مسار المستخدمين على الصفحة الرئيسية

عناصر أحداث الصفحة الرئيسية

عند استدعاء دالة تنشيط الصفحة الرئيسية (runFunction) الموضّحة أعلاه، يتم تمرير كائن حدث يحتوي على بيانات من سياق الاستدعاء.

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

اطّلِع على عنصر الحدث لمزيد من التفاصيل.

البطاقات الأخرى غير السياقية

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

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