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

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

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