دیالوگ ها و نوارهای جانبی برای افزودنی ویرایشگر
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
برای اکثر افزونه‌های ویرایشگر ، پنجره‌های محاوره‌ای و پانل‌های نوار کناری رابط‌های کاربر اصلی هستند. هر دو کاملاً با استفاده از HTML و CSS استاندارد قابل تنظیم هستند، و می‌توانید از مدل ارتباطی سرویس گیرنده-سرور Apps Script برای اجرای عملکردهای Apps Script در هنگام تعامل کاربر با نوار کناری یا گفتگو استفاده کنید. برافزای شما می‌تواند چندین نوار کناری و دیالوگ را تعریف کند، اما افزونه می‌تواند هر بار تنها یکی را نمایش دهد.
هنگامی که می خواهید مانع از تعامل کاربر با ویرایشگر شوید تا زمانی که در رابط افزودنی انتخابی انجام دهد، از یک گفتگو استفاده کنید. در غیر این صورت از نوار کناری استفاده کنید.
دیالوگ ها
دیالوگ ها پانل های پنجره ای هستند که محتوای ویرایشگر اصلی را پوشش می دهند. دیالوگ های Apps Script حالتی هستند. در حالی که آنها باز هستند، کاربر نمی تواند با سایر عناصر رابط ویرایشگر تعامل داشته باشد. می توانید محتوا و اندازه دیالوگ ها را سفارشی کنید.
شما دیالوگ های افزودنی را مانند گفتگوهای سفارشی Apps Script می سازید. روش کلی توصیه شده به شرح زیر است:
- یک فایل پروژه اسکریپت ایجاد کنید که ساختار HTML، CSS و رفتار جاوا اسکریپت سمت سرویس گیرنده را تعریف کند. هنگام تعریف گفتگو، به دستورالعمل‌های سبک افزودنی ویرایشگر مراجعه کنید.
- در کد سمت سرور، جایی که می‌خواهید گفتگو باز شود،
HtmlService.createHtmlOutputFromFile(filename) را فراخوانی کنید تا یک شی HtmlOutput که نمایانگر گفتگو است ایجاد کنید. از طرف دیگر، اگر از HTML قالب استفاده می‌کنید، می‌توانید HtmlService.createTemplateFromFile(filename) را برای تولید یک الگو و سپس HtmlTemplate.evaluate() برای تبدیل آن به یک شی HtmlOutput فراخوانی کنید. -
Ui.showModalDialog(htmlOutput, dialogTitle) را فراخوانی کنید تا گفتگو با استفاده از آن HtmlOutput نمایش داده شود.
دیالوگ ها اسکریپت سمت سرور را تا زمانی که باز هستند به حالت تعلیق در نمی آورند. جاوا اسکریپت سمت کلاینت می تواند با استفاده از google.script.run() و توابع مربوط به کنترل کننده، تماس های ناهمزمان با سمت سرور برقرار کند. برای جزئیات بیشتر، ارتباط مشتری به سرور را ببینید.
دیالوگ های باز کردن فایل
دیالوگ های باز کردن فایل دیالوگ های از پیش ساخته شده ای هستند که به کاربران شما امکان می دهد فایل ها را از Google Drive خود انتخاب کنند. می‌توانید بدون نیاز به طراحی، یک دیالوگ باز کردن فایل را به افزونه خود اضافه کنید، اما نیاز به تنظیمات بیشتری دارد. همچنین برای فعال کردن Google Picker API نیاز به دسترسی به پروژه Cloud Platform افزونه دارید.
برای جزئیات کامل، گفتگوهای باز کردن فایل را ببینید.
سایدبارها پنل هایی هستند که در سمت راست رابط ویرایشگر ظاهر می شوند و رایج ترین نوع رابط افزودنی هستند. برخلاف دیالوگ‌ها، می‌توانید در حالی که یک نوار کناری باز است، به تعامل با سایر عناصر رابط ویرایشگر ادامه دهید. سایدبارها دارای عرض ثابت هستند، اما می توانید محتوای آنها را سفارشی کنید.
شما نوارهای جانبی افزودنی را مانند نوارهای فرعی سفارشی Apps Script می سازید. روش کلی توصیه شده به شرح زیر است:
- یک فایل پروژه اسکریپت ایجاد کنید که ساختار HTML، CSS و رفتار جاوا اسکریپت سمت کلاینت نوار کناری شما را تعریف کند. هنگام تعریف نوار کناری، به دستورالعمل‌های سبک افزودنی ویرایشگر مراجعه کنید.
در کد سمت سرور خود، جایی که می‌خواهید نوار کناری باز شود، HtmlService.createHtmlOutputFromFile(filename) را فراخوانی کنید تا یک شی HtmlOutput که نشان دهنده نوار کناری است ایجاد کنید. از طرف دیگر، اگر از HTML قالب استفاده می‌کنید، می‌توانید HtmlService.createTemplateFromFile(filename) را برای تولید یک الگو و سپس HtmlTemplate.evaluate() برای تبدیل آن به یک شی HtmlOutput فراخوانی کنید.
برای نمایش نوار کناری با استفاده از آن HtmlOutput Ui.showSidebar(htmlOutput) را فراخوانی کنید.
سایدبارها اسکریپت سمت سرور را تا زمانی که باز هستند به حالت تعلیق در نمی آورند. جاوا اسکریپت سمت کلاینت می تواند با استفاده از google.script.run() و توابع مربوط به کنترل کننده، تماس های ناهمزمان با سمت سرور برقرار کند. برای جزئیات بیشتر، ارتباط مشتری به سرور را ببینید.
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-08-21 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-08-21 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eEditor add-ons primarily use customizable dialog windows and sidebar panels for user interfaces, built with HTML, CSS, and Apps Script.\u003c/p\u003e\n"],["\u003cp\u003eDialogs are modal windows, overlaying editor content and preventing interaction until a choice is made, while sidebars allow continued editor interaction.\u003c/p\u003e\n"],["\u003cp\u003eBoth dialogs and sidebars are created using HtmlService to define their structure and displayed using Ui methods.\u003c/p\u003e\n"],["\u003cp\u003eFile-open dialogs are pre-built for selecting files from Google Drive but need extra configuration and Cloud Platform project access.\u003c/p\u003e\n"],["\u003cp\u003eAdd-on sidebars have a fixed width of 300 pixels and appear on the right of the editor, enabling user interaction with other editor elements.\u003c/p\u003e\n"]]],["Editor add-ons utilize customizable dialogs and sidebars as user interfaces, built with HTML, CSS, and Apps Script. Dialogs, which overlay the editor, prevent user interaction until closed, created via `HtmlService` and displayed with `Ui.showModalDialog`. Sidebars, residing on the editor's right, allow continued editor interaction and are created and displayed similarly, using `Ui.showSidebar`. Both interfaces facilitate client-server communication through `google.script.run()` for asynchronous interactions. File-open dialogs offer pre-built file selection.\n"],null,["# Dialogs and sidebars for Editor add-on\n\nFor most [Editor add-on](/workspace/add-ons/concepts/types#editor_add-ons),\ndialog windows and sidebar panels are the primary add-on user interfaces.\nBoth are fully customizable using standard HTML and CSS, and you can use\nApps Script's\n[client-server communication model](/apps-script/guides/html/communication)\nto run Apps Script functions when the user interacts with the sidebar or dialog.\nYour add-on can define multiple sidebars and dialogs, but the add-on can display\nonly one at a time.\n\nWhen you want to prevent the user from interacting with the editor until they\nmake some choice in the add-on interface, use a dialog; otherwise use a\nsidebar.\n\nDialogs\n-------\n\n*Dialogs* are window panels that overlay the primary editor content. Apps Script\ndialogs are modal; while they are opened the user can't interact with the\nother elements of the editor interface. You can customize the content and size\nof dialogs.\n\nYou build add-on dialogs the same way as Apps Script\n[custom dialogs](/apps-script/guides/dialogs#custom_dialogs); the general\nrecommended procedure is the following:\n\n1. Create a script project file that defines your dialog's HTML structure, CSS, and client-side JavaScript behavior. When defining the dialog, refer to the [Editor add-on style guidelines](/workspace/add-ons/guides/editor-style#dialogs).\n2. In your server-side code where you want the dialog to open, call [`HtmlService.createHtmlOutputFromFile(filename)`](/apps-script/reference/html/html-service#createhtmloutputfromfilefilename) to create an [`HtmlOutput`](/apps-script/reference/html/html-output) object representing the dialog. Alternatively, if you are using [templated HTML](/apps-script/guides/html/templates) you can call [`HtmlService.createTemplateFromFile(filename)`](/apps-script/reference/html/html-service#createtemplatefromfilefilename) to generate a template and then [`HtmlTemplate.evaluate()`](/apps-script/reference/html/html-template#evaluate()) to convert it to an [`HtmlOutput`](/apps-script/reference/html/html-output) object.\n3. Call [`Ui.showModalDialog(htmlOutput, dialogTitle)`](/apps-script/reference/base/ui#showModalDialog(Object,String)) to display the dialog using that [`HtmlOutput`](/apps-script/reference/html/html-output).\n\nDialogs don't suspend the server-side script while they are open. The\nclient-side JavaScript can make asynchronous calls to the server-side\nusing [`google.script.run()`](/apps-script/guides/html/reference/run) and\nassociated handler functions. For more details, see\n[Client-to-server communication](/apps-script/guides/html/communication).\n\n### File-open dialogs\n\n*File-open dialogs* are pre-built dialogs that let your users select files\nfrom their Google Drive. You can add a file-open dialog to your add-on without\nneeding to design it, but it requires some additional configuration. You also\nrequire access to the add-on's\n[Cloud Platform project](/apps-script/guides/cloud-platform-projects)\nin order to enable the Google Picker API.\n\nFor full details, see [File-open dialogs](/apps-script/guides/dialogs#file-open_dialogs).\n\nSidebars\n--------\n\n*Sidebars* are panels that appear in the right of the editor interface, and\nare the most common type of add-on interface. Unlike dialogs, you can continue\nto interact with the other elements of the editor interface while a sidebar is\nopen. Sidebars have a fixed width, but you can customize their content.\n\nYou build add-on sidebars the same way as Apps Script\n[custom sidebars](/apps-script/guides/dialogs#custom_sidebars); the general\nrecommended procedure is the following:\n\n1. Create a script project file that defines your sidebar's HTML structure, CSS, and client-side JavaScript behavior. When defining the sidebar, refer to the [Editor add-on style guidelines](/workspace/add-ons/guides/editor-style#sidebars).\n2. In your server-side code where you want the sidebar to open, call\n [`HtmlService.createHtmlOutputFromFile(filename)`](/apps-script/reference/html/html-service#createhtmloutputfromfilefilename)\n to create an [`HtmlOutput`](/apps-script/reference/html/html-output)\n object representing the sidebar. Alternatively, if you are using\n [templated HTML](/apps-script/guides/html/templates) you can call\n [`HtmlService.createTemplateFromFile(filename)`](/apps-script/reference/html/html-service#createtemplatefromfilefilename)\n to generate a template and then\n [`HtmlTemplate.evaluate()`](/apps-script/reference/html/html-template#evaluate())\n to convert it to an\n [`HtmlOutput`](/apps-script/reference/html/html-output) object.\n\n | **Note:** Add-on sidebars have a fixed width of 300 pixels that you can't alter by calling [`HtmlOutput.setWidth(width)`](/apps-script/reference/html/html-output#setwidthwidth).\n3. Call [`Ui.showSidebar(htmlOutput)`](/apps-script/reference/base/ui#showSidebar(Object))\n to display the sidebar using that\n [`HtmlOutput`](/apps-script/reference/html/html-output).\n\nSidebars don't suspend the server-side script while they are open. The\nclient-side JavaScript can make asynchronous calls to the server-side\nusing [`google.script.run()`](/apps-script/guides/html/reference/run) and\nassociated handler functions. For more details, see\n[Client-to-server communication](/apps-script/guides/html/communication)."]]
