ساخت رابط‌های کاربری گوگل درایو

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

به رابط کاربری افزونه‌ی Google Workspace دسترسی پیدا کنید

اگر نماد افزونه در ستون نمادها در سمت راست رابط کاربری درایو ظاهر شود، می‌توانید آن را در درایو باز کنید. یک افزونه می‌تواند یک رابط صفحه اصلی، یک رابط انتخاب آیتم یا هر دو را تعریف کند:

• اگر کاربر در حالی که در Drive است روی نماد افزونه کلیک کند، افزونه تابع drive.homepageTrigger مربوطه (در صورت وجود) را اجرا می‌کند. این تابع یک کارت صفحه اصلی می‌سازد و برای نمایش به Drive برمی‌گرداند. اگر هیچ تابع drive.homepageTrigger تعریف نشده باشد، به جای آن یک کارت صفحه اصلی عمومی نمایش داده می‌شود.
• اگر کاربر یک یا چند مورد را در Drive انتخاب کند و سپس روی نماد افزونه کلیک کند، یا در حالی که افزونه باز است، مواردی را انتخاب کند، افزونه تابع زمینه‌ای drive.onItemsSelectedTrigger مربوطه را (در صورت وجود) اجرا می‌کند. این تابع رابط زمینه‌ای Drive افزونه با عنوان "items selected" را می‌سازد و آن را برای نمایش به Drive برمی‌گرداند.

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

با دنبال کردن این مراحل کلی، رابط‌هایی بسازید که Drive را گسترش می‌دهند:

1. تصمیم بگیرید که آیا می‌خواهید افزونه شما یک صفحه اصلی مخصوص درایو داشته باشد یا خیر. همچنین تصمیم بگیرید که آیا می‌خواهید یک رابط کاربری متنی برای زمانی که کاربر موارد درایو را انتخاب می‌کند، ارائه دهید یا خیر.
2. فیلدهای addOns.common و addOns.drive مناسب را به مانیفست پروژه اسکریپت افزونه، شامل هرگونه محدوده Drive مورد نیاز، اضافه کنید.
3. اگر یک صفحه اصلی مخصوص Drive ارائه می‌دهید، تابع drive.homepageTrigger را برای ساخت این رابط پیاده‌سازی کنید. همچنین می‌توانید از رابط common.homepageTrigger برای چندین میزبان Google Workspace استفاده کنید.
4. اگر یک رابط انتخاب آیتم متنی Drive ارائه می‌دهید، باید یک تابع محرک متنی drive.onItemsSelectedTrigger را برای ساخت این رابط پیاده‌سازی کنید. برای جزئیات بیشتر به رابط متنی Drive برای آیتم‌های انتخاب شده مراجعه کنید.
5. توابع فراخوانی مرتبط مورد نیاز برای پاسخ به تعاملات رابط کاربری کاربر، مانند کلیک دکمه‌ها، را پیاده‌سازی کنید.

صفحات اصلی درایو

درایو از نمایش صفحات اصلی افزونه پشتیبانی می‌کند. برای نمایش صفحه اصلی مشترک افزونه خود در درایو، مطمئن شوید که فیلد addOns.drive در مانیفست افزونه وجود دارد.

روش دیگر، اضافه کردن یک drive.homepageTrigger به مانیفست افزونه برای ارائه یک صفحه اصلی مخصوص درایو است.

در هر صورت، نام تابع تریگر صفحه اصلی را در پروژه اسکریپت افزونه خود وارد کنید. این تابع به طور خودکار برای ساخت صفحه اصلی Drive در صورت نیاز فراخوانی می‌شود. این تابع را برای ساخت و بازگرداندن یک Card یا آرایه‌ای از اشیاء Card که صفحه اصلی را تشکیل می‌دهند، پیاده‌سازی کنید. به تابع تریگر صفحه اصلی، یک شیء رویداد به عنوان پارامتر ارسال می‌شود که حاوی اطلاعات کلی مانند پلتفرم کلاینت است. از داده‌های شیء رویداد برای ساخت صفحه اصلی استفاده کنید.

رابط متنی را برای موارد انتخاب شده هدایت کنید

درایو برای تعیین اینکه چه رابطی (در صورت وجود) را هنگام انتخاب یک یا چند مورد از آیتم‌های درایو توسط کاربر نمایش دهد، به یک تریگر زمینه‌ای متکی است. وقتی تریگر فعال می‌شود، تابع تریگر زمینه‌ای مشخص شده توسط فیلد drive.onItemsSelectedTrigger.runFunction در مانیفست افزونه را اجرا می‌کند.

برای ایجاد یک رابط انتخاب آیتم زمینه‌ای برای Drive، باید موارد زیر را انجام دهید:

1. مطمئن شوید که فایل مانیفست افزونه شامل محدوده‌ی https://www.googleapis.com/auth/drive.addons.metadata.readonly می‌شود.

2. مطمئن شوید که فایل مانیفست شامل بخش drive.onItemsSelectedTrigger باشد.

3. تابعی که در فیلد drive.onItemsSelectedTrigger نامگذاری شده است را پیاده‌سازی کنید. این تابع یک شیء رویداد را به عنوان آرگومان می‌پذیرد و باید یا یک شیء Card واحد یا آرایه‌ای از اشیاء Card را برگرداند.

4. مانند هر کارت دیگری، هر تابع فراخوانی که برای ارائه تعامل ویجت برای رابط کاربری استفاده می‌شود را پیاده‌سازی کنید. برای مثال، اگر یک دکمه را در رابط کاربری قرار می‌دهید، باید یک اکشن (Action) متصل و یک تابع فراخوانی پیاده‌سازی شده داشته باشد که هنگام کلیک روی دکمه اجرا شود.

اشیاء رویداد

یک شیء رویداد ایجاد می‌شود و هنگام فراخوانی توابع trigger مانند drive.homepageTrigger یا drive.onItemsSelectedTrigger به آن ارسال می‌شود. تابع trigger از اطلاعات موجود در این شیء رویداد برای تعیین نحوه ساخت کارت‌های افزونه یا کنترل رفتار افزونه استفاده می‌کند.

ساختار کامل اشیاء رویداد در اشیاء رویداد شرح داده شده است. وقتی Drive برنامه میزبان فعال افزونه است، اشیاء رویداد زمینه‌ای شامل فیلد شیء رویداد Drive می‌شوند که اطلاعات کلاینت مخصوص Drive را حمل می‌کند.

اشیاء رویداد Contextual Drive برای تریگرهای انتخاب آیتم شامل اطلاعاتی در مورد آیتم‌هایی هستند که کاربر هنگام فعال شدن تریگر انتخاب کرده است. هنگامی که کاربر بیش از یک آیتم را در Drive انتخاب می‌کند، یکی از آیتم‌ها به عنوان آیتم مورد علاقه اصلی در نظر گرفته می‌شود؛ این آیتم به عنوان آیتم مکان‌نمای فعال شناخته می‌شود.

اگر قرار است رفتار افزونه روی چندین مورد انتخاب شده اعمال شود، از اطلاعات ارائه شده در آرایه drive.selectedItems در شیء رویداد برای شناسایی همه آنها استفاده کنید.

وقتی رفتار یک افزونه فقط باید روی یک آیتم انتخاب شده اعمال شود، از اطلاعات ارائه شده در فیلد drive.activeCursorItem از شیء رویداد برای شناسایی آیتم از کل انتخاب استفاده کنید. سعی نکنید از آرایه drive.selectedItems حدس بزنید که از کدام آیتم استفاده کنید.

مثال زیر یک شیء رویداد Drive را نشان می‌دهد که به تابع drive.onItemsSelectedTrigger ارسال می‌شود:

{
  "commonEventObject": { ... },
  "drive": {
    "activeCursorItem":{
      "addonHasFileScopePermission": true,
      "id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
      "iconUrl": "https://drive-thirdparty.googleusercontent.com...",
      "mimeType":"application/pdf",
      "title":"How to get started with Drive"
    },
    "selectedItems": [
      {
        "addonHasFileScopePermission": true,
        "id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
        "iconUrl":"https://drive-thirdparty.googleusercontent.com...",
        "mimeType":"application/pdf",
        "title":"How to get started with Drive"
      },
      ...
    ]
  },
  ...
}