صفحات اصلی

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

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

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

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

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

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

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

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

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

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

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

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

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

    {
      ...
      "addOns": {
        ...
        "common": {
          // By default, call 'buildHomePage' to render homepage content
          // in all hosts. Since calendar.homepageTrigger below overrides
          // this in Calendar and Drive and the homepageTrigger is disabled
          // for Gmail, this homepage function never executes.
          "homepageTrigger": { "runFunction": "buildHomePage" }
        },
        "calendar": {
          // Show customized homepage content for Calendar only.
          "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
        },
        "drive": {
          // Show customized homepage content for Drive only.
          "homepageTrigger": { "runFunction": "buildDriveHomepage" }
        }
        "gmail": {
          // Disable homepage add-on content in Gmail.
          "homepageTrigger": { "enabled": false }
        },
        ...
      }
    }

توجه داشته باشید که این معادل گزیده مانیفست زیر است:

    {
      ...
      "addOns": {
        ...
        "common": { /* ... */ }, // Omitted a default homepageTrigger specification.
        "calendar": {
          // Show customized homepage content for Calendar only.
          "homepageTrigger": { "runFunction": "myCalendarFunction" }
        },
        "drive": {
          // Show customized homepage content for Drive only.
          "homepageTrigger": { "runFunction": "myDriveFunction" }
        }
        "gmail": { /* ... */ },
        ...
      }
    }

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

جریان صفحه اصلی

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

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

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

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

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

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

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