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

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

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

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

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

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

يمكنك إنشاء واجهات توسّع نطاق 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

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

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

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

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

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

لإنشاء واجهة اختيار عناصر سياقية في Drive، يجب اتّباع الخطوات التالية:

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

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"
      },
      ...
    ]
  },
  ...
}