ساخت رابط های ویرایشگر گوگل

با افزودنی‌های Google Workspace، می‌توانید رابط‌های سفارشی‌شده را در ویرایشگرها، از جمله Google Docs، Sheets و Slides ارائه دهید. این به شما امکان می دهد اطلاعات مرتبط را در اختیار کاربر قرار دهید، وظایف را خودکار کنید و سیستم های شخص ثالث را به ویرایشگرها متصل کنید.

دسترسی به رابط کاربری افزونه

اگر نماد آن در پانل جانبی دسترسی سریع Google در سمت راست اسناد ، برگه ها و رابط های کاربر اسلایدها ظاهر شود ، می توانید یک افزودنی فضای کاری Google را در ویرایشگرها باز کنید.

یک افزونه Google Workspace می‌تواند رابط‌های زیر را ارائه دهد:

• رابط های صفحه اصلی : اگر مانیفست افزودنی شامل Trigger EDITOR_NAME .homepageTrigger برای ویرایشگر باشد ، کاربر افزودنی را باز می کند ، افزودنی می سازد و یک کارت صفحه اصلی را به طور خاص برای آن ویرایشگر باز می گرداند. اگر مانیفست افزودنی شامل EDITOR_NAME .homepageTrigger برای ویرایشگر که کاربر آن را باز می کند ، به جای آن یک کارت صفحه اصلی عمومی نمایش داده می شود.

• رابط های API REST : اگر افزودنی از API های REST استفاده می کند ، می توانید محرک هایی را که درخواست دسترسی هر پرونده به یک سند را با استفاده از drive.file Scope درخواست می کنند ، درج کنید. پس از دریافت، یک راه‌انداز دیگر به نام EDITOR_NAME .onFileScopeGrantedTrigger یک رابط خاص برای فایل را اجرا و نمایش می‌دهد.

• LINK PREVIEW Interfaces : اگر افزودنی شما با یک سرویس شخص ثالث ادغام می شود ، می توانید کارت هایی بسازید که محتوای آن را از URL های سرویس خود پیش نمایش کنید.

ساخت رابط برای افزونه های ویرایشگر

با دنبال کردن مراحل زیر، رابط های افزودنی ویرایشگر را برای ویرایشگرها بسازید:

1. فیلدهای addOns.common ، addOns.docs ، addOns.sheets و addOns.slides مناسب را به مانیفست پروژه اسکریپت افزودنی اضافه کنید.
2. هر حوزه ویرایشگر مورد نیاز را به مانیفست پروژه اسکریپت خود اضافه کنید.
3. اگر یک صفحه اصلی مخصوص ویرایشگر ارائه می‌دهید، تابع EDITOR_NAME .homepageTrigger را برای ساخت رابط پیاده‌سازی کنید. اگر نه، از رابط common.homepageTrigger برای ایجاد یک صفحه اصلی مشترک برای برنامه های میزبان خود استفاده کنید.
4. اگر از API های 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 را نشان می‌دهد. این افزونه اسناد، برگه‌ها و اسلایدها را گسترش می‌دهد و صفحه اصلی مشترک در هر برنامه میزبان را نشان می‌دهد.

 "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 .

1. EDITOR_NAME .onFileScopeGrantedTrigger در بخش ویرایشگر مناسب مانیفست خود قرار دهید. به عنوان مثال، اگر می خواهید این رابط را در Google Sheets ایجاد کنید، ماشه را به بخش "sheets" اضافه کنید.
2. تابع نامگذاری شده در بخش EDITOR_NAME .onFileScopeGrantedTrigger را پیاده سازی کنید. این تابع یک شی رویداد را به عنوان آرگومان می پذیرد و باید یک شی Card یا آرایه ای از اشیاء Card را برگرداند.
3. مانند هر کارت دیگری، باید توابع پاسخ به تماس مورد استفاده برای ارائه تعامل ویجت برای رابط را پیاده سازی کنید. به عنوان مثال ، اگر یک دکمه را در رابط قرار دهید ، باید یک عمل پیوست و یک عملکرد پاسخ به تماس با اجرا داشته باشد که هنگام کلیک بر روی دکمه اجرا می شود.

مثال زیر بخش 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 . تابع Trigger از اطلاعات در شیء رویداد برای تعیین نحوه ساخت کارتهای افزودنی یا کنترل رفتار افزودنی استفاده می کند.

ساختار کامل اشیاء رویداد در اشیاء رویداد توضیح داده شده است.

هنگامی که یک ویرایشگر برنامه میزبان بازیگری افزودنی است ، اشیاء رویداد شامل زمینه های شیء رویداد ، برگه ها یا اسلایدها هستند که اطلاعات مشتری را حمل می کنند.

اگر افزودنی مجوز دامنه 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"
          },
          ...
        }