إنشاء واجهات 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 scope

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