مربّعات الحوار والأشرطة الجانبية في "إضافة المحرّر"
تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
بالنسبة إلى معظم إضافات المحرّر، تُعدّ نوافذ مربّعات الحوار ولوحات الشريط الجانبي هي واجهات المستخدم الأساسية للإضافة. يمكن تخصيص كليهما بالكامل باستخدام HTML وCSS العاديين، ويمكنك استخدام نموذج الاتصال بين العميل والخادم في "برمجة تطبيقات Google" لتشغيل دوال "برمجة تطبيقات Google" عندما يتفاعل المستخدم مع الشريط الجانبي أو مربّع الحوار. يمكن أن تحدّد الإضافة أشرطة جانبية ومربّعات حوار متعدّدة، ولكن يمكن أن تعرض الإضافة شريطًا جانبيًا أو مربّع حوار واحدًا فقط في كل مرة.
عندما تريد منع المستخدم من التفاعل مع المحرّر إلى أن يتّخذ خيارًا في واجهة الإضافة، استخدِم مربّع حوار، وإلا استخدِم شريطًا جانبيًا.
مربّعات حوار
مربّعات الحوار هي لوحات نوافذ تتراكب مع محتوى المحرّر الأساسي. مربّعات الحوار في Apps Script هي مربّعات مشروطة، أي أنّه لا يمكن للمستخدم التفاعل مع العناصر الأخرى في واجهة المحرّر أثناء فتحها. يمكنك تخصيص محتوى وحجم مربّعات الحوار.
يمكنك إنشاء مربّعات حوار الإضافات بالطريقة نفسها التي تنشئ بها مربّعات الحوار المخصّصة في "برمجة تطبيقات Google"، والإجراء العام المقترَح هو كما يلي:
أنشئ ملف مشروع نص برمجي يحدّد بنية HTML الخاصة بمربع الحوار وCSS وسلوك JavaScript من جهة العميل. عند تحديد مربّع الحوار، يُرجى الرجوع إلى إرشادات الأسلوب الخاصة بـ "إضافة المحرّر".
لا توقِف مربّعات الحوار النص البرمجي من جهة الخادم أثناء فتحها. يمكن أن تنفّذ جافا سكريبت من جهة العميل طلبات غير متزامنة إلى جهة الخادم باستخدام google.script.run() ودوال المعالجة المرتبطة بها. لمزيد من التفاصيل، يُرجى الاطّلاع على الاتصال بين العميل والخادم.
مربّعات حوار فتح الملفات
مربّعات حوار فتح الملفات هي مربّعات حوار مُعدّة مسبقًا تتيح للمستخدمين اختيار الملفات من Google Drive. يمكنك إضافة مربّع حوار لفتح الملفات إلى الإضافة بدون الحاجة إلى تصميمه، ولكن يتطلّب ذلك بعض الإعدادات الإضافية. يجب أيضًا أن يكون لديك إذن بالوصول إلى مشروع Cloud Platform الخاص بالإضافة من أجل تفعيل Google Picker API.
الأشرطة الجانبية هي لوحات تظهر على يسار واجهة المحرّر، وهي النوع الأكثر شيوعًا من واجهات الإضافات. على عكس مربّعات الحوار، يمكنك مواصلة التفاعل مع العناصر الأخرى لواجهة المحرّر أثناء فتح شريط جانبي. تتميّز الأشرطة الجانبية بعرض ثابت، ولكن يمكنك تخصيص محتواها.
يمكنك إنشاء أشرطة جانبية للإضافات بالطريقة نفسها التي تنشئ بها الأشرطة الجانبية المخصّصة في "برمجة تطبيقات Google"، والإجراء العام المقترَح هو كما يلي:
أنشئ ملف مشروع نص برمجي يحدّد بنية HTML لشريطك الجانبي وCSS وسلوك JavaScript من جهة العميل. عند تحديد الشريط الجانبي، يُرجى الرجوع إلى إرشادات الأنماط الخاصة بإضافة المحرِّر.
لا توقِف الأشرطة الجانبية النص البرمجي من جهة الخادم مؤقتًا أثناء فتحها. يمكن أن تنفّذ جافا سكريبت من جهة العميل طلبات غير متزامنة إلى جهة الخادم باستخدام google.script.run() ودوال المعالجة المرتبطة بها. لمزيد من التفاصيل، يُرجى الاطّلاع على الاتصال بين العميل والخادم.
تاريخ التعديل الأخير: 2025-08-21 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 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,["For 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*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\nFile-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*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)."]]
