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

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

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

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

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

ساخت رابط کاربری افزونه‌ی Drive

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

1. تصمیم بگیرید که آیا می‌خواهید افزونه شما یک صفحه اصلی مخصوص درایو داشته باشد یا خیر. همچنین تصمیم بگیرید که آیا می‌خواهید یک رابط کاربری متنی برای زمانی که کاربر موارد درایو را انتخاب می‌کند، ارائه دهید یا خیر.
2. فیلدهای addOns.common و addOns.drive مناسب را به مانیفست پروژه اسکریپت افزونه، شامل هرگونه محدوده Drive مورد نیاز، اضافه کنید.
3. اگر یک صفحه اصلی مخصوص Drive ارائه می‌دهید، تابع drive.homepageTrigger را برای ساخت این رابط پیاده‌سازی کنید. همچنین می‌توانید از رابط common.homepageTrigger برای چندین میزبان Google Workspace استفاده کنید.
4. If you are providing a Drive contextual item selection interface, you must implement a drive.onItemsSelectedTrigger contextual trigger function to build this interface. See Drive contextual interface for items selected ) for details.
5. توابع فراخوانی مرتبط مورد نیاز برای پاسخ به تعاملات رابط کاربری کاربر، مانند کلیک دکمه‌ها، را پیاده‌سازی کنید.

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

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

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

In either case, you must provide the name of a homepage trigger function in your add-on's script project. This function is automatically called to build the Drive homepage when it is needed. You must implement this function to build and return a single Card or an array of Card objects that make up the homepage. The homepage trigger function is passed an event object as a parameter that contains some general information such as the client's platform. You can use the event object data to tailor the construction of the homepage.

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

گوگل درایو برای تعیین اینکه چه رابطی (در صورت وجود) هنگام انتخاب یک یا چند مورد از موارد گوگل درایو توسط کاربر نمایش داده شود، به یک تریگر زمینه‌ای متکی است. وقتی تریگر فعال می‌شود، تابع تریگر زمینه‌ای مشخص شده توسط فیلد 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 event objects for item selection triggers include information about the items the user has selected when the trigger fires. When a user selects more than one item in Drive, one of the items is deemed to be one of primary interest; this item is referred to as the active cursor item .

مثال زیر یک شیء رویداد 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"
          },
          ...
        ]
      },
      ...
    }