با افزونههای Google Workspace، میتوانید رابطهای کاربری سفارشیسازیشدهای را در ویرایشگرها، از جمله Google Docs، Sheets و Slides، ارائه دهید. این به شما امکان میدهد اطلاعات مرتبط را در اختیار کاربر قرار دهید، وظایف را خودکار کنید و سیستمهای شخص ثالث را به ویرایشگرها متصل کنید.
دسترسی به رابط کاربری افزونه
اگر نماد افزونهی Google Workspace در پنل دسترسی سریع Google Workspace در سمت راست رابطهای کاربری Docs، Sheets و Slides ظاهر شده باشد، میتوانید آن را در ویرایشگرها باز کنید.
یک افزونهی 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 را نشان میدهد. این افزونه، Docs، Sheets و Slides را توسعه میدهد و صفحه اصلی مشترک را در هر برنامهی میزبان نشان میدهد.
"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 نمایش میدهد. تابع فراخوانی 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 مانند 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) متصل و یک تابع فراخوانی پیادهسازی شده داشته باشد که هنگام کلیک روی دکمه اجرا شود.
مثال زیر بخش addons مانیفست افزونه Google Workspace را نشان میدهد. این افزونه از REST APIs استفاده میکند، بنابراین onFileScopeGrantedTrigger برای Google Sheets گنجانده شده است. هنگامی که کاربر دامنه 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 ارسال میشود. تابع تریگر از اطلاعات موجود در شیء رویداد برای تعیین نحوه ساخت کارتهای افزونه یا کنترل رفتار افزونه استفاده میکند.
ساختار کامل اشیاء رویداد در Event objects شرح داده شده است.
وقتی یک ویرایشگر، برنامهی میزبانِ فعالِ افزونه باشد، اشیاء رویداد شامل فیلدهای اشیاء رویداد Docs ، Sheets یا Slides میشوند که اطلاعات کلاینت را در خود جای دادهاند.
اگر افزونه مجوز دامنه drive.file را برای کاربر یا سند فعلی نداشته باشد، شیء رویداد فقط شامل فیلدهای docs.addonHasFileScopePermission ، sheets.addonHasFileScopePermission یا slides.addonHasFileScopePermission است. اگر افزونه مجوز داشته باشد، شیء رویداد شامل تمام فیلدهای شیء رویداد Editor است.
مثال زیر یک شیء رویداد Editor را نشان میدهد که به تابع sheets.onFileScopeGrantedTrigger ارسال میشود. در اینجا، افزونه دارای مجوز دامنه drive.file برای سند فعلی است:
` {
"commonEventObject": { ... },
"sheets": {
"addonHasFileScopePermission": true,
"id":"A_24Q3CDA23112312ED52",
"title":"How to get started with Sheets"
},
...
}