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

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

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

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

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

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

• واجهات REST API: في حال كانت الإضافة تستخدم 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 تشغيل الدالة لعرض واجهة خاصة بالملف المفتوح. لمزيد من المعلومات، يمكنك الاطّلاع على واجهات برمجة تطبيقات REST.
5. في حال ضبط معاينات روابط من خدمة تابعة لجهة خارجية، يجب تنفيذ تدفق تفويض نطاق https://www.googleapis.com/auth/workspace.linkpreview linkPreviewTriggers الأخرى. لمزيد من المعلومات، يُرجى مراجعة واجهات معاينة الروابط:
6. تنفيذ وظائف معاودة الاتصال المرتبطة اللازمة للاستجابة لطلبات المستخدم تفاعلات واجهة المستخدم، مثل النقرات على الأزرار

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

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

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

يمكنك مشاركة صفحة رئيسية مشتركة أو صفحة رئيسية مخصَّصة لبرنامج "محرّر إعلانات Google" يفتح المستخدم الإضافة.

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

لعرض الصفحة الرئيسية المشتركة للإضافات في "المحررين"، يجب تضمين علامة حقول المحرّر، مثل 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 بطاقة الصفحة الرئيسية الخاصة بجداول البيانات.

 "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، مثل Google Sheets API، يمكنك استخدام الدالة onFileScopeGrantedTrigger لعرض واجهة جديدة الخاصة بالملف المفتوح في تطبيق مضيف المحرر.

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

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

لإنشاء واجهة REST API لأحد المحرّرين، اتّبِع الخطوات أدناه. استبدِل 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"
          },
          ...
        }