صفحات رئيسية

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

تتيح لك الصفحات الرئيسية عرض محتوى غير سياقي، تمامًا مثل تطبيقات Google في اللوحة الجانبية للوصول السريع (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) الموضّحة أعلاه.

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

يُرجى الاطّلاع على كائن الحدث لمعرفة مزيد من التفاصيل.

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

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

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