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

يمكن أن تقدّم إضافات Google Workspace واجهات customized عند استخدام المستخدم 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.selectedItems في عنصر الحدث لتحديدها جميعًا.

عندما يجب تطبيق سلوك الإضافة على عنصر واحد تم اختياره فقط، استخدِم المعلومات المقدّمة في حقل drive.activeCursorItem لعنصر الحدث لتحديد العنصر من بين الاختيار الكامل. لا تحاول استنتاج العنصر الذي تريد استخدامه من صفيف drive.selectedItems.

يعرض المثال التالي عنصر حدث 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"
          },
          ...
        ]
      },
      ...
    }