صفحات رئيسية

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

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

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

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

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

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

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

ضبط الصفحة الرئيسية

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

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

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

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

بالإضافة إلى التكوين الشائع، هناك أيضًا بنية متطابقة لكل مضيف متوفرة في عناوين URL الإعداد، على 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) الموضحة أعلاه هي تم تمرير كائن حدث يتضمن بيانات من سياق الاستدعاء.

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

راجِع كائن الحدث للحصول على مزيد من التفاصيل.

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

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

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