إنشاء واجهات "محرّر إعلانات 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، نفِّذ عملية التفويض على مستوى النطاق 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

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

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

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

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