صفحات رئيسية

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

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

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

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

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

  • عند فتح الإضافة لأول مرة في المضيف (بعد التفويض).
  • عندما ينتقل المستخدم من سياق سياقي إلى سياق غير سياقي عندما تكون الإضافة مفتوحة. مثلاً، من تعديل حدث في "تقويم Google" إلى "تقويم 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) الموضّحة أعلاه، يتم تمرير كائن الحدث الذي يحتوي على بيانات من سياق الاستدعاء.

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

يمكنك الاطّلاع على كائن الحدث للحصول على مزيد من التفاصيل.

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

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

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