صفحات رئيسية

الصفحات الرئيسية هي ميزة جديدة في إضافات 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 وما إلى ذلك.

يعرض المثال التالي ملف بيان تم فيه تحديد مشغّل شائع للصفحة الرئيسية، ولكن تم استبداله بوظائف مخصّصة لـ "تقويم Google" وDrive، وتم إيقافه بالكامل في Gmail. في هذا الإعداد، لا يتم تنفيذ الدالة buildHomePage الشائعة أبدًا لأنّه يتم إما إلغاؤها أو إيقاف المضيف.

    {
      ...
      "addOns": {
        ...
        "common": {
          "homepageTrigger": { "runFunction": "buildHomePage" }
        },
        "calendar": {
          "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
        },
        "drive": {
          "homepageTrigger": { "runFunction": "buildDriveHomepage" }
        },
        "gmail": {
          "homepageTrigger": { "enabled": false }
        },
        ...
      }
    }

يُرجى العِلم أنّ مقتطف البيان التالي يعادل المثال السابق، على الرغم من حذف homepageTrigger التلقائي وإعدادات Gmail:

    {
      "addOns": {
        "common": {},
        "calendar": {
          "homepageTrigger": { "runFunction": "myCalendarFunction" }
        },
        "drive": {
          "homepageTrigger": { "runFunction": "myDriveFunction" }
        },
        "gmail": {},
        ...
      }
    }

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

مخطّط يوضّح مسار تنفيذ وظيفة تشغيل الصفحة الرئيسية للإضافة

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

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

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

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

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

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

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