با افزودنی‌های Google Workspace، می‌توانید رابط‌های سفارشی‌شده را در ویرایشگرها، از جمله Google Docs، Sheets و Slides ارائه دهید. این به شما امکان می دهد اطلاعات مرتبط را در اختیار کاربر قرار دهید، وظایف را خودکار کنید و سیستم های شخص ثالث را به ویرایشگرها متصل کنید.
دسترسی به رابط کاربری افزونه
اگر نماد Google Workspace در پانل کناری دسترسی سریع Google Workspace در سمت راست رابط کاربری Docs، Sheets و Slides ظاهر شود، می‌توانید یک افزونه Google Workspace را در ویرایشگرها باز کنید.
یک افزونه Google Workspace می‌تواند رابط‌های زیر را ارائه دهد:
رابط‌های صفحه اصلی : اگر مانیفست افزونه شامل راه‌انداز
EDITOR_NAME .homepageTriggerبرای ویرایشگر باشد، کاربر افزونه را در آن باز می‌کند، افزونه یک کارت صفحه اصلی را به‌طور خاص برای آن ویرایشگر ایجاد می‌کند و برمی‌گرداند. اگر مانیفست افزونه شاملEDITOR_NAME .homepageTriggerبرای ویرایشگر نباشد که کاربر آن را در آن باز می کند، به جای آن یک کارت صفحه اصلی عمومی نمایش داده می شود.رابط‌های REST API : اگر افزونه از REST API استفاده می‌کند، می‌توانید راه‌اندازهایی را اضافه کنید که با استفاده از محدوده
drive.file، دسترسی هر فایل به یک سند را درخواست می‌کنند. پس از دریافت، یک راه‌انداز دیگر به نامEDITOR_NAME .onFileScopeGrantedTriggerیک رابط خاص برای فایل را اجرا و نمایش می‌دهد.رابط‌های پیش‌نمایش پیوند : اگر افزونه شما با یک سرویس شخص ثالث ادغام می‌شود، می‌توانید کارت‌هایی بسازید که محتوا را از URLهای سرویستان پیش‌نمایش می‌کنند.
ساخت رابط برای افزونه های ویرایشگر
با دنبال کردن مراحل زیر، رابط های افزودنی ویرایشگر را برای ویرایشگرها بسازید:
- فیلدهای
addOns.common،addOns.docs،addOns.sheetsوaddOns.slidesمناسب را به مانیفست پروژه اسکریپت افزودنی اضافه کنید. - هر حوزه ویرایشگر مورد نیاز را به مانیفست پروژه اسکریپت خود اضافه کنید.
- اگر یک صفحه اصلی مخصوص ویرایشگر ارائه می‌دهید، تابع
EDITOR_NAME .homepageTriggerرا برای ساخت رابط پیاده‌سازی کنید. اگر نه، از رابطcommon.homepageTriggerبرای ایجاد یک صفحه اصلی مشترک برای برنامه های میزبان خود استفاده کنید. - اگر از APIهای REST استفاده می‌کنید، جریان مجوز دامنه
drive.fileو عملکرد راه‌اندازیEDITOR_NAME .onFileScopeGrantedTriggerبرای نمایش یک رابط خاص برای فایل باز اجرا کنید. برای اطلاعات بیشتر، رابط های REST API را ببینید. - اگر پیش‌نمایش پیوندها را از یک سرویس شخص ثالث پیکربندی می‌کنید،
https://www.googleapis.com/auth/workspace.linkpreviewجریان مجوز دامنه و عملکردlinkPreviewTriggersرا اجرا کنید. برای اطلاعات بیشتر، رابط های پیش نمایش پیوند را ببینید. - توابع مربوط به پاسخ به تماس مورد نیاز برای پاسخگویی به تعاملات رابط کاربری کاربر، مانند کلیک روی دکمه، را اجرا کنید.
صفحات اصلی ویرایشگر
شما باید در پروژه اسکریپت افزونه خود یک تابع راه‌اندازی صفحه اصلی ارائه دهید که یک Card واحد یا آرایه‌ای از اشیاء Card که صفحه اصلی افزونه را تشکیل می‌دهند، می‌سازد و برمی‌گرداند.
تابع ماشه صفحه اصلی یک شی رویداد به عنوان پارامتری ارسال می شود که حاوی اطلاعاتی مانند پلت فرم مشتری است. می‌توانید از داده‌های شی رویداد برای تنظیم ساخت صفحه اصلی استفاده کنید.
می توانید یک صفحه اصلی مشترک یا یک صفحه اصلی را ارائه دهید که مخصوص ویرایشگری است که کاربر افزونه شما را در آن باز می کند.
نمایش صفحه اصلی مشترک
برای نمایش صفحه اصلی مشترک افزونه خود در ویرایشگرها، فیلدهای ویرایشگر مناسب، مانند addOns.docs ، addOns.sheets یا addOns.slides در مانیفست افزونه اضافه کنید.
مثال زیر بخش addons مانیفست افزونه Google Workspace را نشان می‌دهد. این افزونه اسناد، برگه‌ها و اسلایدها را گسترش می‌دهد و صفحه اصلی مشترک در هر برنامه میزبان را نشان می‌دهد.
"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 را نشان می‌دهد. این افزونه برای Docs، Sheets و Slides فعال است. صفحه اصلی مشترک را در Docs و Slides و یک صفحه اصلی منحصر به فرد را در Sheets نمایش می دهد. تابع callback onSheetsHomepage کارت صفحه اصلی Sheets را می سازد.
"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
اگر افزونه شما از APIهای REST، مانند Google Sheets API استفاده می‌کند، می‌توانید از تابع onFileScopeGrantedTrigger برای نمایش یک رابط جدید مخصوص فایلی که در برنامه میزبان ویرایشگر باز است، استفاده کنید.
برای استفاده از تابع onFileScopeGrantedTrigger باید جریان مجوز دامنه drive.file را وارد کنید. برای یادگیری نحوه درخواست دامنه drive.file ، به درخواست دسترسی فایل برای سند فعلی مراجعه کنید.
هنگامی که کاربر محدوده drive.file را اعطا می کند، EDITOR_NAME .onFileScopeGrantedTrigger.runFunction فعال می شود. هنگامی که تریگر فعال می شود، تابع ماشه متنی مشخص شده توسط EDITOR_NAME .onFileScopeGrantedTrigger.runFunction را در مانیفست افزودنی اجرا می کند.
برای ایجاد یک رابط REST API برای یکی از ویرایشگرها، مراحل زیر را دنبال کنید. EDITOR_NAME با برنامه میزبان ویرایشگر که برای استفاده انتخاب می‌کنید جایگزین کنید، برای مثال sheets.onFileScopeGrantedTrigger .
-
EDITOR_NAME .onFileScopeGrantedTriggerرا در بخش ویرایشگر مناسب مانیفست خود قرار دهید. به عنوان مثال، اگر می خواهید این رابط را در Google Sheets ایجاد کنید، ماشه را به بخش"sheets"اضافه کنید. - تابع نامگذاری شده در بخش
EDITOR_NAME .onFileScopeGrantedTriggerرا پیاده سازی کنید. این تابع یک شی رویداد را به عنوان آرگومان می پذیرد و باید یک شیCardیا آرایه ای از اشیاءCardرا برگرداند. - مانند هر کارت دیگری، باید توابع پاسخ به تماس مورد استفاده برای ارائه تعامل ویجت برای رابط را پیاده سازی کنید. برای مثال، اگر دکمه‌ای را در اینترفیس قرار دهید، باید یک Action پیوست و یک تابع callback اجرا شده داشته باشد که با کلیک روی دکمه اجرا می‌شود.
مثال زیر بخش addons مانیفست افزونه Google Workspace را نشان می‌دهد. این افزونه از API های REST استفاده می کند، بنابراین onFileScopeGrantedTrigger برای Google Sheets گنجانده شده است. هنگامی که کاربر محدوده drive.file را اعطا می کند، تابع callback 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 . تابع ماشه از اطلاعات موجود در شی رویداد برای تعیین نحوه ساخت کارت های افزودنی یا کنترل رفتار افزونه استفاده می کند.
ساختار کامل اشیاء رویداد در اشیاء رویداد توضیح داده شده است.
وقتی یک ویرایشگر برنامه میزبان فعال افزونه است، اشیاء رویداد شامل فیلدهای شی رویداد Docs ، Sheets یا Slides هستند که اطلاعات سرویس گیرنده را حمل می کنند.
اگر افزونه مجوز دامنه 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"
},
...
}