صفحات اصلی

صفحات اصلی یک ویژگی افزونه‌های Google Workspace هستند که امکان تعریف یک یا چند کارت غیرمتنی را فراهم می‌کنند. کارت‌های غیرمتنی زمانی که کاربر خارج از یک زمینه خاص است، مانند زمانی که صندوق ورودی Gmail خود را بدون پیام یا پیش‌نویس باز مشاهده می‌کند، رابط کاربری را نمایش می‌دهند.

صفحات اصلی به شما امکان می‌دهند محتوای غیرمتنی را نمایش دهید، مشابه برنامه‌های گوگل در پنل دسترسی سریع (Google Keep، Google Calendar و Google Tasks). صفحات اصلی همچنین می‌توانند نقطه شروع اولیه‌ای را برای زمانی که کاربر برای اولین بار افزونه شما را باز می‌کند، فراهم کنند و برای آموزش نحوه تعامل با افزونه شما به کاربران جدید مفید باشند.

با مشخص کردن افزونه خود در مانیفست پروژه و پیاده‌سازی یک یا چند تابع homepageTrigger (به پیکربندی صفحه اصلی مراجعه کنید)، یک صفحه اصلی برای آن تعریف کنید.

شما می‌توانید چندین صفحه اصلی داشته باشید، یکی برای هر برنامه میزبان که افزونه شما آن را توسعه می‌دهد. همچنین می‌توانید یک صفحه اصلی پیش‌فرض مشترک تعریف کنید که در میزبان‌هایی که صفحه اصلی سفارشی برای آنها مشخص نکرده‌اید، استفاده شود.

صفحه اصلی افزونه شما در این موارد نمایش داده می‌شود:

  • وقتی افزونه برای اولین بار در میزبان (پس از مجوز) باز می‌شود.
  • وقتی کاربر در حالی که افزونه باز است، از یک زمینهٔ زمینه‌ای به یک زمینهٔ غیرزمینه‌ای تغییر وضعیت می‌دهد. برای مثال، از ویرایش یک رویداد تقویم به تقویم اصلی.
  • وقتی کاربر به تعداد کافی روی دکمه برگشت کلیک کند تا کارت‌ها یکی در میان از دسته‌های داخلی خارج شوند .
  • وقتی یک تعامل رابط کاربری در یک کارت غیرمتنی منجر به فراخوانی Navigation.popToRoot می‌شود.

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

پیکربندی صفحه اصلی

افزونه‌های Google Workspace از فیلد addOns.common.homepageTrigger برای پیکربندی محتوای افزونه پیش‌فرض (غیرمتنی) صفحه اصلی برای برنامه‌های میزبان در مانیفست افزونه استفاده می‌کنند:

{
  "addOns": {
    "common": {
      "homepageTrigger": {
        "runFunction": "myFunction",
        "enabled": true
      }
    }
  }
}

  • runFunction : نام تابع اسکریپت Google Apps که چارچوب افزونه‌های Google Workspace آن را برای رندر کردن کارت‌های افزونه صفحه اصلی فراخوانی می‌کند. این تابع، تابع تریگر صفحه اصلی است. این تابع باید آرایه‌ای از اشیاء Card که رابط کاربری صفحه اصلی را تشکیل می‌دهند، بسازد و برگرداند. اگر بیش از یک کارت برگردانده شود، برنامه میزبان هدرهای کارت را در لیستی نشان می‌دهد که کاربر می‌تواند از بین آنها انتخاب کند (به بخش برگرداندن چندین کارت مراجعه کنید).

  • enabled : آیا کارت‌های صفحه اصلی باید برای این محدوده فعال شوند یا خیر. این فیلد اختیاری است و مقدار پیش‌فرض آن true است. تنظیم این مقدار روی false باعث می‌شود کارت‌های صفحه اصلی برای همه میزبان‌ها غیرفعال شوند (مگر اینکه برای آن میزبان لغو شوند؛ به پیکربندی خاص میزبان مراجعه کنید).

برای اینکه یک میزبان از صفحه اصلی مشترک استفاده کند، هم addOns.common.homepageTrigger و هم منبع سطح بالای میزبان باید در مانیفست افزونه وجود داشته باشند. برای مثال، اگر addOns.gmail در مانیفست وجود نداشته باشد، افزونه برای Gmail غیرفعال است و صفحه اصلی یا سایر قابلیت‌ها را در آن میزبان نشان نمی‌دهد.

علاوه بر پیکربندی رایج، لغوهای یکسان با ساختار یکسان برای هر میزبان در پیکربندی هر برنامه میزبان، در addOns.gmail.homepageTrigger ، addOns.calendar.homepageTrigger و سایر تریگرهای مخصوص میزبان موجود است.

مثال زیر یک مانیفست را نشان می‌دهد که در آن یک تریگر صفحه اصلی مشترک تعریف شده است اما با توابع سفارشی برای تقویم و درایو لغو شده و برای جیمیل غیرفعال است. در این پیکربندی، تابع buildHomePage مشترک هرگز اجرا نمی‌شود زیرا یا لغو شده است یا میزبان غیرفعال است.

{
  ...
  "addOns": {
    ...
    "common": {
      "homepageTrigger": { "runFunction": "buildHomePage" }
    },
    "calendar": {
      "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "buildDriveHomepage" }
    },
    "gmail": {
      "homepageTrigger": { "enabled": false }
    },
    ...
  }
}

گزیده‌ی مانیفست زیر معادل مثال قبلی است، حتی اگر homepageTrigger پیش‌فرض و پیکربندی Gmail حذف شده باشند:

{
  "addOns": {
    "common": {},
    "calendar": {
      "homepageTrigger": { "runFunction": "myCalendarFunction" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "myDriveFunction" }
    },
    "gmail": {},
    ...
  }
}

هیچ یک از بخش‌های homepageTrigger مورد نیاز نیستند. رابط کاربری نمایش داده شده برای یک افزونه در یک محصول میزبان به وجود فیلد مانیفست مربوطه و وجود یا عدم وجود یک homepageTrigger مرتبط بستگی دارد. مثال زیر نشان می‌دهد که کدام توابع ماشه افزونه برای ایجاد یک رابط کاربری صفحه اصلی برای پیکربندی‌های مختلف مانیفست اجرا می‌شوند:

نموداری که جریان اجرای تابع تریگر صفحه اصلی افزونه را نشان می‌دهد

اشیاء رویداد صفحه اصلی

هنگام فراخوانی، تابع تریگر صفحه اصلی ( runFunction ) که قبلاً توضیح داده شد، یک شیء رویداد حاوی داده‌هایی از زمینه فراخوانی ارسال می‌کند.

اشیاء رویداد صفحه اصلی شامل ویجت یا اطلاعات زمینه‌ای نمی‌شوند. اطلاعات ارسالی به فیلدهای شیء رویداد رایج زیر محدود می‌شود:

برای جزئیات بیشتر به شیء رویداد مراجعه کنید.

سایر کارت‌های غیرمرتبط

رابط کاربری افزونه شما می‌تواند شامل کارت‌های غیرمتنی اضافی باشد که صفحه اصلی نیستند. برای مثال، صفحه اصلی شما ممکن است دکمه‌ای داشته باشد که کارت «تنظیمات» را برای تنظیم تنظیمات افزونه باز می‌کند (چنین تنظیماتی معمولاً مستقل از زمینه هستند).

کارت‌های غیرمتنی مانند هر کارت دیگری ساخته می‌شوند؛ تنها تفاوت در این است که چه عمل یا رویدادی کارت را تولید و نمایش می‌دهد. برای جزئیات بیشتر در مورد نحوه ایجاد انتقال بین کارت‌ها، به روش‌های ناوبری مراجعه کنید.