إنشاء واجهات 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 في بيان الإضافة manifest.

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

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

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

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

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

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

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

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

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

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

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

يعرض المثال التالي كائن حدث Drive object يتم تمريره إلى دالة 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"
      },
      ...
    ]
  },
  ...
}