دیالوگ ها و نوارهای جانبی برای افزودنی ویرایشگر

برای اکثر افزونه‌های ویرایشگر ، پنجره‌های محاوره‌ای و پنل‌های نوار کناری، رابط‌های کاربری اصلی افزونه هستند. هر دو با استفاده از HTML و CSS استاندارد کاملاً قابل تنظیم هستند و می‌توانید از مدل ارتباطی کلاینت-سرور Google Apps Script برای اجرای توابع Apps Script هنگام تعامل کاربر با نوار کناری یا پنجره محاوره‌ای استفاده کنید. افزونه شما می‌تواند چندین نوار کناری و پنجره محاوره‌ای تعریف کند، اما افزونه می‌تواند فقط یکی را در یک زمان نمایش دهد.

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

دیالوگ‌ها

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

شما دیالوگ‌های افزونه را به همان روش دیالوگ‌های سفارشی Apps Script می‌سازید. روال کلی به شرح زیر است:

  1. یک فایل پروژه اسکریپت ایجاد کنید که ساختار HTML، CSS و رفتار جاوا اسکریپت سمت کلاینت دیالوگ شما را تعریف کند. به دستورالعمل‌های سبک افزونه ویرایشگر مراجعه کنید.
  2. در کد سمت سرور خود که می‌خواهید کادر محاوره‌ای در آن باز شود، HtmlService.createHtmlOutputFromFile را برای ایجاد یک شیء HtmlOutput که نمایانگر کادر محاوره‌ای است، فراخوانی کنید. به طور جایگزین، اگر از HTML قالب‌بندی شده استفاده می‌کنید، می‌توانید HtmlService.createTemplateFromFile را برای تولید یک الگو فراخوانی کنید و سپس HtmlTemplate.evaluate را برای تبدیل آن به یک شیء HtmlOutput فراخوانی کنید.
  3. برای نمایش کادر محاوره‌ای با استفاده از HtmlOutput Ui.showModalDialog را فراخوانی کنید.

دیالوگ‌ها (dialogs) تا زمانی که باز هستند، اسکریپت سمت سرور را به حالت تعلیق در نمی‌آورند. جاوا اسکریپت سمت کلاینت می‌تواند با استفاده از google.script.run و توابع هندلر مرتبط، فراخوانی‌های غیرهمزمان (asynchronous) به سمت سرور انجام دهد. برای جزئیات بیشتر، به بخش ارتباط کلاینت با سرور مراجعه کنید.

پنجره‌های محاوره‌ای باز کردن فایل

پنجره‌های محاوره‌ای باز کردن فایل، پنجره‌های محاوره‌ای از پیش ساخته شده‌ای هستند که به کاربران شما اجازه می‌دهند فایل‌ها را از گوگل درایو خود انتخاب کنند. شما می‌توانید یک پنجره محاوره‌ای باز کردن فایل را بدون نیاز به طراحی به افزونه خود اضافه کنید، اما به پیکربندی‌های اضافی نیاز دارد. همچنین برای فعال کردن Google Picker API به دسترسی به پروژه پلتفرم ابری افزونه نیاز دارید.

برای اطلاعات بیشتر، به پنجره‌های محاوره‌ای باز کردن فایل مراجعه کنید.

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

شما سایدبارهای افزونه را به همان روشی که سایدبارهای سفارشی Apps Script را می‌سازید، می‌سازید. روال کلی به شرح زیر است:

  1. یک فایل پروژه اسکریپت ایجاد کنید که ساختار HTML، CSS و رفتار جاوا اسکریپت سمت کلاینت نوار کناری شما را تعریف کند. هنگام تعریف نوار کناری، به دستورالعمل‌های سبک افزونه ویرایشگر مراجعه کنید.

  2. در کد سمت سرور خود، جایی که می‌خواهید نوار کناری باز شود، HtmlService.createHtmlOutputFromFile را فراخوانی کنید تا یک شیء HtmlOutput که نمایانگر نوار کناری است، ایجاد شود. به طور جایگزین، اگر از HTML قالب‌بندی شده استفاده می‌کنید، می‌توانید HtmlService.createTemplateFromFile را برای تولید یک الگو فراخوانی کنید و سپس HtmlTemplate.evaluate را برای تبدیل آن به یک شیء HtmlOutput فراخوانی کنید.

    نوارهای کناری افزونه‌ها دارای عرض ثابت ۳۰۰ پیکسل هستند که نمی‌توانید با فراخوانی HtmlOutput.setWidth آن را تغییر دهید.

  3. برای نمایش سایدبار با استفاده از HtmlOutput تابع Ui.showSidebar فراخوانی کنید.

سایدبارها در حین باز بودن، اسکریپت سمت سرور را به حالت تعلیق در نمی‌آورند. جاوا اسکریپت سمت کلاینت می‌تواند با استفاده از google.script.run و توابع هندلر مرتبط، فراخوانی‌های غیرهمزمان به سمت سرور انجام دهد. برای جزئیات بیشتر، به ارتباط کلاینت به سرور مراجعه کنید.