إنشاء واجهات "محرّر إعلانات Google"

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

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

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

يمكن أن تقدِّم إضافة Google Workspace الواجهات التالية:

  • واجهات الصفحة الرئيسية: إذا كان بيان الإضافة يتضمن المشغّل EDITOR_NAME.homepageTrigger الخاص بـ "محرّر إعلانات Google" الذي يفتح المستخدم الإضافة فيه، تُنشئ الإضافة بطاقة الصفحة الرئيسية تحديدًا لهذا "محرّر إعلانات Google" وتعرضها. إذا لم يتضمّن بيان الإضافة EDITOR_NAME.homepageTrigger في "محرّر إعلانات Google" الذي يفتحه المستخدم، سيتم عرض بطاقة صفحة رئيسية عامة بدلاً من ذلك.

  • واجهات برمجة تطبيقات REST: إذا كانت الإضافة تستخدم واجهات برمجة تطبيقات REST، يمكنك تضمين المشغلات التي تطلب الوصول لكل ملف إلى مستند واحد باستخدام نطاق drive.file. وبعد منحه، يوجد مشغل آخر يسمى EDITOR_NAME.onFileScopeGrantedTrigger ينفذ ويعرض واجهة خاصة بالملف.

  • واجهات معاينة الرابط: إذا كانت إضافتك تتكامل مع خدمة تابعة لجهة خارجية، يمكنك إنشاء بطاقات تعرض المحتوى من عناوين URL للخدمة.

إنشاء واجهات لإضافات المحرِّر

إنشاء واجهات إضافات المحرِّرين للمحرِّرين باتّباع الخطوات التالية:

  1. أضِف الحقول المناسبة addOns.common وaddOns.docs وaddOns.sheets وaddOns.slides إلى بيان مشروع النص البرمجي للإضافة .
  2. أضِف أي نطاقات المحرر المطلوبة إلى بيان مشروع النص البرمجي.
  3. إذا كنت توفر صفحة رئيسية مخصصة للمحرّر، نفِّذ الوظيفة EDITOR_NAME.homepageTrigger لإنشاء الواجهة. وإذا لم يكن الأمر كذلك، استخدِم واجهة common.homepageTrigger لإنشاء صفحة رئيسية مشتركة للتطبيقات المضيفة.
  4. في حال استخدام واجهات برمجة تطبيقات REST، نفِّذ خطوات عملية تفويض النطاق drive.file ودالة المشغِّل EDITOR_NAME.onFileScopeGrantedTrigger لعرض واجهة خاصة بالملف المفتوح. لمزيد من المعلومات، يُرجى الاطّلاع على واجهات برمجة تطبيقات RST.
  5. في حال ضبط معاينات الروابط من خدمة تابعة لجهة خارجية، نفِّذ خطوات تفويض نطاق https://www.googleapis.com/auth/workspace.linkpreview ودالة linkPreviewTriggers. للمزيد من المعلومات، اطّلِع على واجهات معاينة الروابط.
  6. نفِّذ وظائف معاودة الاتصال المرتبطة واللازمة للاستجابة لتفاعلات واجهة المستخدم، مثل النقرات على الأزرار.

الصفحات الرئيسية للمحرّر

يجب توفير دالة تشغيل الصفحة الرئيسية في مشروع النص البرمجي للإضافة الذي ينشئ ويعرض Card واحدًا أو مصفوفة من كائنات Card التي يتألف منها الصفحة الرئيسية للإضافة.

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

يمكنك تقديم صفحة رئيسية شائعة أو صفحة رئيسية خاصة بالمحرر الذي يفتح المستخدم الإضافة فيه.

عرض الصفحة الرئيسية الشائعة

لعرض الصفحة الرئيسية الشائعة لإضافتك في أدوات التحرير، عليك تضمين حقول المحرّر المناسبة، مثل addOns.docs أو addOns.sheets أو addOns.slides في بيان الإضافة.

يوضِّح المثال التالي الجزء addons من بيان إضافة Google Workspace. تعمل الإضافة على توسيع نطاق "مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google"، وتعرض الصفحة الرئيسية الشائعة في كل تطبيق مضيف.

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "sheets": {},
    "slides": {}
  }
}

عرض صفحة رئيسية خاصة بالمحرّر

لتقديم صفحة رئيسية خاصة بمحرِّر، أضِف EDITOR_NAME.homepageTrigger إلى بيان الإضافة.

يعرض المثال التالي الجزء addons من بيان إضافة Google Workspace. تم تفعيل الإضافة في "مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google". إنه يعرض الصفحة الرئيسية الشائعة في المستندات والعروض التقديمية، وصفحة رئيسية فريدة في جداول البيانات. تنشئ دالة معاودة الاتصال onSheetsHomepage بطاقة الصفحة الرئيسية الخاصة بـ "جداول بيانات Google".

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "slides": {},
    "sheets": {
     "homepageTrigger": {
       "runFunction": "onSheetsHomepage"
     },
  }
}

واجهات برمجة تطبيقات REST

إذا كانت إضافتك تستخدم واجهات برمجة تطبيقات REST، مثل Google Sheets API، يمكنك استخدام الدالة onFileScopeGrantedTrigger لعرض واجهة جديدة خاصة بالملف المفتوح في تطبيق مضيف "محرّر إعلانات Google".

عليك تضمين مسار تفويض drive.file لاستخدام الدالة onFileScopeGrantedTrigger. لمعرفة كيفية طلب نطاق drive.file، يُرجى الاطّلاع على طلب الوصول إلى الملف للمستند الحالي.

عندما يمنح المستخدم نطاق drive.file، يتم تنشيط EDITOR_NAME.onFileScopeGrantedTrigger.runFunction. عند تنشيط المشغِل، يتم تنفيذ دالة المشغِّل السياقي التي يحددها الحقل EDITOR_NAME.onFileScopeGrantedTrigger.runFunction في بيان الإضافة.

لإنشاء واجهة واجهة برمجة تطبيقات REST لأحد المحرِّرين، اتّبِع الخطوات التالية. استبدِل EDITOR_NAME بتطبيق مضيف "محرّر إعلانات Google" الذي اخترت استخدامه، على سبيل المثال، sheets.onFileScopeGrantedTrigger.

  1. ضمِّن EDITOR_NAME.onFileScopeGrantedTrigger في قسم المحرر المناسب في البيان. على سبيل المثال، إذا أردت إنشاء هذه الواجهة في "جداول بيانات Google"، أضِف العامل المشغِّل إلى قسم "sheets".
  2. نفِّذ الدالة المُسمّاة في قسم EDITOR_NAME.onFileScopeGrantedTrigger. تقبل هذه الدالة كائن حدث كوسيطة ويجب أن تعرض إما كائن Card واحد أو صفيفًا من كائنات Card.
  3. كما هو الحال مع أي بطاقة، يجب تنفيذ دوال رد الاتصال المستخدمة لتوفير تفاعل الأدوات للواجهة. على سبيل المثال، إذا أدرجت زرًا في الواجهة، يجب أن يحتوي على إجراء مرفق ووظيفة استدعاء منفَّذة تعمل عند النقر على الزر.

يعرض المثال التالي الجزء addons من بيان إضافة Google Workspace. تستخدم الإضافة واجهات برمجة تطبيقات REST، لذلك يتم تضمين onFileScopeGrantedTrigger في "جداول بيانات Google". عندما يمنح المستخدم نطاق drive.file، تنشئ دالة معاودة الاتصال onFileScopeGrantedSheets واجهة خاصة بملف.

"addOns": {
   "common": {
     "name": "Productivity add-on",
     "logoUrl": "https://www.gstatic.com/images/icons/material/system_gm/1x/work_outline_black_18dp.png",
     "layoutProperties": {
       "primaryColor": "#669df6",
       "secondaryColor": "#ee675c"
     }
   },
   "sheets": {
     "homepageTrigger": {
       "runFunction": "onEditorsHomepage"
     },
     "onFileScopeGrantedTrigger": {
       "runFunction": "onFileScopeGrantedSheets"
     }
   }

لتفعيل معاينات الروابط لخدمة تابعة لجهة خارجية، يجب إعداد معاينات الروابط في بيان الإضافة وإنشاء دالة تعرض بطاقة معاينة. بالنسبة إلى الخدمات التي تتطلب إذن المستخدم، يجب أن تستدعي وظيفتك مسار التفويض أيضًا.

لمعرفة خطوات تفعيل معاينات الروابط، يمكنك الاطّلاع على معاينة الروابط باستخدام الشرائح الذكية.

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

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

يتم وصف البنية الكاملة لكائنات الأحداث في كائنات الأحداث.

عندما يكون "محرّر إعلانات Google" هو التطبيق المضيف الحالي للإضافة، تتضمّن كائنات الأحداث حقول عناصر الأحداث مستندات Google أو جداول بيانات Google أو العروض التقديمية من Google التي تتضمن معلومات العميل.

إذا لم تتضمّن الإضافة تفويض نطاق drive.file للمستخدم أو المستند الحالي، سيحتوي كائن الحدث فقط على الحقل docs.addonHasFileScopePermission أو sheets.addonHasFileScopePermission أو slides.addonHasFileScopePermission. إذا كان للإضافة تفويض، سيحتوي كائن الحدث على جميع حقول كائن الحدث في "محرّر إعلانات Google".

يعرض المثال التالي كائن حدث "محرّر إعلانات Google" تم تمريره إلى دالة sheets.onFileScopeGrantedTrigger. هنا، تحتوي الإضافة على تفويض نطاق drive.file للمستند الحالي:

`        {
          "commonEventObject": { ... },
          "sheets": {
            "addonHasFileScopePermission": true,
            "id":"A_24Q3CDA23112312ED52",
            "title":"How to get started with Sheets"
          },
          ...
        }