باستخدام إضافات 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 للخدمة.
إنشاء واجهات لإضافات المحرِّر
إنشاء واجهات إضافات المحرِّرين للمحرِّرين باتّباع الخطوات التالية:
- أضِف الحقول المناسبة
addOns.common
وaddOns.docs
وaddOns.sheets
وaddOns.slides
إلى بيان مشروع النص البرمجي للإضافة . - أضِف أي نطاقات المحرر المطلوبة إلى بيان مشروع النص البرمجي.
- إذا كنت توفر صفحة رئيسية مخصصة للمحرّر،
نفِّذ الوظيفة
EDITOR_NAME.homepageTrigger
لإنشاء الواجهة. وإذا لم يكن الأمر كذلك، استخدِم واجهةcommon.homepageTrigger
لإنشاء صفحة رئيسية مشتركة للتطبيقات المضيفة. - في حال استخدام واجهات برمجة تطبيقات REST، نفِّذ خطوات عملية تفويض النطاق
drive.file
ودالة المشغِّلEDITOR_NAME.onFileScopeGrantedTrigger
لعرض واجهة خاصة بالملف المفتوح. لمزيد من المعلومات، يُرجى الاطّلاع على واجهات برمجة تطبيقات RST. - في حال ضبط معاينات الروابط من خدمة تابعة لجهة خارجية، نفِّذ
خطوات تفويض نطاق
https://www.googleapis.com/auth/workspace.linkpreview
ودالةlinkPreviewTriggers
. للمزيد من المعلومات، اطّلِع على واجهات معاينة الروابط. - نفِّذ وظائف معاودة الاتصال المرتبطة واللازمة للاستجابة لتفاعلات واجهة المستخدم، مثل النقرات على الأزرار.
الصفحات الرئيسية للمحرّر
يجب توفير دالة تشغيل الصفحة الرئيسية في مشروع النص البرمجي للإضافة
الذي ينشئ ويعرض 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
.
- ضمِّن
EDITOR_NAME.onFileScopeGrantedTrigger
في قسم المحرر المناسب في البيان. على سبيل المثال، إذا أردت إنشاء هذه الواجهة في "جداول بيانات Google"، أضِف العامل المشغِّل إلى قسم"sheets"
. - نفِّذ الدالة المُسمّاة في قسم
EDITOR_NAME.onFileScopeGrantedTrigger
. تقبل هذه الدالة كائن حدث كوسيطة ويجب أن تعرض إما كائنCard
واحد أو صفيفًا من كائناتCard
. - كما هو الحال مع أي بطاقة، يجب تنفيذ دوال رد الاتصال المستخدمة لتوفير تفاعل الأدوات للواجهة. على سبيل المثال، إذا أدرجت زرًا في الواجهة، يجب أن يحتوي على إجراء مرفق ووظيفة استدعاء منفَّذة تعمل عند النقر على الزر.
يعرض المثال التالي الجزء 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" }, ... }