إنشاء واجهات Google Drive

يمكن أن توفر إضافات Google Workspace واجهات مخصصة عندما يستخدم المستخدم Google Drive. يتيح لك ذلك تزويد المستخدم بمعلومات إضافية ذات صلة، وتشغيل المهام آليًا، وربط أنظمة الجهات الخارجية بـ Google Drive.

الوصول إلى واجهة مستخدم الإضافة

يمكنك فتح إضافة Google Workspace في Google Drive إذا ظهر رمزها في عمود الرمز على الجانب الأيسر من واجهة مستخدم Drive. يمكن يمكن لإضافة Google Workspace تحديد واجهة الصفحة الرئيسية أو واجهة اختيار العنصر أو كليهما:

• إذا نقر المستخدم على رمز الإضافة أثناء تصفّح Google Drive، ستنفّذ الإضافة دالة drive.homepageTrigger المقابلة (في حال توفّرها). تنشئ هذه الدالة بطاقة صفحة رئيسية وتعرضها في Google Drive للعرض. إذا لم يتم تحديد الدالة drive.homepageTrigger، سيتم عرض بطاقة صفحة رئيسية عامة بدلاً من ذلك.
• إذا اختار المستخدم عنصرًا واحدًا أو أكثر في Google Drive ثم نقر على رمز الإضافة أو اختار عناصر أثناء فتح الإضافة، تنفّذ الإضافة الدالة السياقية المقابلة في drive.onItemsSelectedTrigger (في حال توفّرها). تُنشئ هذه الدالة واجهة "العناصر المحدّدة" السياقية للإضافة في Google Drive وتعيدها إلى Google Drive لعرضها.

إنشاء واجهة Drive للإضافة

يمكنك إنشاء واجهات تعمل على توسيع نطاق Google Drive باتّباع الخطوات العامة التالية:

1. حدد ما إذا كنت تريد أن يكون للإضافتك صفحة رئيسية خاصة بخدمة Drive. يمكنك أيضًا تحديد ما إذا كنت تريد توفير واجهة سياقية لاستخدامها عندما يختار المستخدم عناصر Drive.
2. أضِف حقلَي addOns.common و addOns.drive المناسبَين إلى بيان النصوص البرمجية للإضافة، بما في ذلك أي نطاقات على Drive مطلوبة.
3. إذا كنت توفّر صفحة رئيسية خاصة بخدمة Drive، يمكنك تنفيذ وظيفة drive.homepageTrigger لإنشاء هذه الواجهة. يمكنك أيضًا اختيار استخدام واجهة common.homepageTrigger لمضيفي Google Workspace متعددين.
4. إذا كنت توفر واجهة اختيار عناصر Drive السياقية، عليك تنفيذ وظيفة مشغِّل سياقي في drive.onItemsSelectedTrigger لإنشاء هذه الواجهة. يُرجى الاطّلاع على واجهة Drive السياقية للعناصر المحدّدة) للحصول على التفاصيل.
5. نفِّذ وظائف معاودة الاتصال المرتبطة واللازمة للاستجابة لتفاعلات واجهة المستخدم، مثل النقرات على الأزرار.

الصفحات الرئيسية في Drive

يتيح Google Drive عرض الصفحات الرئيسية في إضافة Google Workspace. لعرض الصفحة الرئيسية الشائعة للإضافة في Google Drive، ما عليك سوى التأكّد من توفّر حقل addOns.drive في ملف بيان الإضافة.

ويمكنك بدلاً من ذلك إضافة drive.homepageTrigger إلى بيان الإضافة لتوفير صفحة رئيسية خاصة بخدمة Drive.

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

واجهة Drive السياقية للعناصر المحدّدة

يعتمد Google Drive على مشغِّل سياقي لتحديد الواجهة (إن وجدت) التي يتم عرضها عندما يختار المستخدم عنصرًا واحدًا أو أكثر من Google Drive. عند تنشيط العامل المشغِّل، يتم تنفيذ دالة المشغّل السياقي التي يحدّدها الحقل drive.onItemsSelectedTrigger.runFunction في بيان الإضافة.

لإنشاء واجهة اختيار عناصر سياقية في Drive، عليك تنفيذ ما يلي:

1. التأكّد من أنّ بيان الإضافة يتضمّن https://www.googleapis.com/auth/drive.addons.metadata.readonly النطاق

2. تأكد من أن البيان يتضمن قسم drive.onItemsSelectedTrigger.

3. نفِّذ الدالة المُسمّاة في حقل drive.onItemsSelectedTrigger. تقبل هذه الدالة كائن حدث كوسيطة ويجب أن تعرض إما كائن Card واحد أو مصفوفة من كائنات Card.

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

كائنات الأحداث

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

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

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

يوضّح المثال التالي كائن حدث Drive الذي يتم تمريره إلى دالة drive.onItemsSelectedTrigger:

    {
      "commonEventObject": { ... },
      "drive": {
        "activeCursorItem":{
          "addonHasFileScopePermission": true,
          "id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
          "iconUrl": "https://drive-thirdparty.googleusercontent.com...",
          "mimeType":"application/pdf",
          "title":"How to get started with Drive"
        },
        "selectedItems": [
          {
            "addonHasFileScopePermission": true,
            "id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
            "iconUrl":"https://drive-thirdparty.googleusercontent.com...",
            "mimeType":"application/pdf",
            "title":"How to get started with Drive"
          },
          ...
        ]
      },
      ...
    }