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

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

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

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

يمكن أن تعرض إضافة Google Workspace الواجهات التالية:

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

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

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

إنشاء واجهات لإضافات "أداة التعديل"

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

  1. أضِف الحقول المناسبة addOns.common وaddOns.docs وaddOns.sheets وaddOns.slides إلى بيان مشروع نص برمجي للإضافة.
  2. أضِف أي نطاقات محرِّر مطلوبة إلى بيان مشروع البرنامج النصي.
  3. إذا كنت توفّر صفحة رئيسية خاصة بالمحرّر، استخدِم الدالة EDITOR_NAME.homepageTrigger لإنشاء الواجهة. إذا لم يكن الأمر كذلك، استخدِم واجهة common.homepageTrigger لإنشاء صفحة رئيسية مشتركة لتطبيقاتك المضيفة.
  4. إذا كنت تستخدم واجهات REST API، عليك تنفيذ عملية تفويض النطاق drive.file ودالة التشغيل EDITOR_NAME.onFileScopeGrantedTrigger لعرض واجهة خاصة بالملف المفتوح. لمزيد من المعلومات، يُرجى الاطّلاع على واجهات REST API.
  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". تعرض الصفحة الرئيسية المشتركة في "مستندات 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 API

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

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

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

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

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

يوضّح المثال التالي الجزء addons من بيان إضافة Google Workspace. تستخدم الإضافة واجهات REST API، لذا يتم تضمين 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 التي تتضمّن معلومات العميل.

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

يعرض المثال التالي عنصر حدث Editor يتم تمريره إلى دالة sheets.onFileScopeGrantedTrigger. في ما يلي، حصلت الإضافة على إذن النطاق drive.file للمستند الحالي:

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