صفحات رئيسية

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

تتيح لك صفحات البداية عرض محتوى غير سياقي، على غرار تطبيقات Google في اللوحة الجانبية للوصول السريع (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.common.homepageTrigger والمورد ذي المستوى الأعلى الخاص بالمضيف. على سبيل المثال، إذا لم يكن addOns.gmail متوفّرًا في ملف البيان، سيتم إيقاف الإضافة في Gmail ولن تعرض صفحة رئيسية أو وظائف أخرى في هذا المضيف.

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

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

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

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

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

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