نمونه‌ای از محیط رابط کاربری برای یک برنامه Google که به اسکریپت اجازه می‌دهد ویژگی‌هایی مانند منوها، دیالوگ‌ها و نوارهای جانبی را اضافه کند. یک اسکریپت فقط برای نمونه فعلی یک ویرایشگر باز می‌تواند با UI تعامل داشته باشد، و تنها در صورتی که اسکریپت به ویرایشگر محدود شده باشد.
// Display a dialog box with a title, message, input field, and "Yes" and "No" buttons. The
// user can also close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.prompt('Getting to know you', 'May I know your name?', ui.ButtonSet.YES_NO);
// Process the user's response.
if (response.getSelectedButton() == ui.Button.YES) {
Logger.log('The user\'s name is %s.', response.getResponseText());
} else if (response.getSelectedButton() == ui.Button.NO) {
Logger.log('The user didn\'t want to provide a name.');
} else {
Logger.log('The user clicked the close button in the dialog\'s title bar.');
}خواص
| ویژگی | تایپ کنید | شرح |
|---|---|---|
Button | Button | یک عدد که نشان دهنده دکمه‌های محاوره‌ای از پیش تعیین‌شده و محلی است که توسط یک هشدار یا PromptResponse.getSelectedButton() بازگردانده می‌شود تا نشان دهد کاربر روی کدام دکمه در گفتگو کلیک کرده است. |
ButtonSet | ButtonSet | یک عدد که مجموعه‌های از پیش تعیین‌شده و بومی‌سازی شده‌ای از یک یا چند دکمه گفتگو را نشان می‌دهد که می‌توانند به یک هشدار یا یک درخواست اضافه شوند. |
مواد و روش ها
| روش | نوع برگشت | توضیح مختصر |
|---|---|---|
alert(prompt) | Button | کادر محاوره ای را با پیام داده شده و دکمه "OK" در ویرایشگر کاربر باز می کند. |
alert(prompt, buttons) | Button | کادر محاوره ای را در ویرایشگر کاربر با پیام داده شده و مجموعه دکمه ها باز می کند. |
alert(title, prompt, buttons) | Button | کادر محاوره ای را در ویرایشگر کاربر با عنوان، پیام و مجموعه دکمه های داده شده باز می کند. |
createAddonMenu() | Menu | سازنده ای ایجاد می کند که می تواند برای درج یک منوی فرعی در منوی افزونه های ویرایشگر استفاده شود. |
createMenu(caption) | Menu | سازنده ای ایجاد می کند که می تواند برای افزودن یک منو به رابط کاربری ویرایشگر استفاده شود. |
prompt(prompt) | PromptResponse | کادر محاوره ای ورودی را با پیام داده شده و دکمه "OK" در ویرایشگر کاربر باز می کند. |
prompt(prompt, buttons) | PromptResponse | یک کادر محاوره ای ورودی را با پیام داده شده و مجموعه دکمه ها در ویرایشگر کاربر باز می کند. |
prompt(title, prompt, buttons) | PromptResponse | کادر محاوره ای ورودی را با عنوان، پیام و مجموعه دکمه های داده شده در ویرایشگر کاربر باز می کند. |
showModalDialog(userInterface, title) | void | یک کادر محاوره ای مدال را در ویرایشگر کاربر با محتوای سمت مشتری سفارشی باز می کند. |
showModelessDialog(userInterface, title) | void | یک کادر محاوره‌ای بدون حالت را در ویرایشگر کاربر با محتوای سمت مشتری سفارشی باز می‌کند. |
showSidebar(userInterface) | void | نوار کناری را در ویرایشگر کاربر با محتوای سمت مشتری سفارشی باز می کند. |
مستندات دقیق
alert(prompt)
کادر محاوره ای را با پیام داده شده و دکمه "OK" در ویرایشگر کاربر باز می کند. این روش اسکریپت سمت سرور را در حالی که گفتگو باز است به حالت تعلیق در می آورد. اسکریپت پس از رد گفتگو توسط کاربر از سر گرفته می شود، اما اتصالات Jdbc و قفل های LockService در سراسر تعلیق باقی نمی مانند. برای اطلاعات بیشتر، راهنمای گفتگوها و نوارهای کناری را ببینید.
// Display "Hello, world" in a dialog box with an "OK" button. The user can also close the
// dialog by clicking the close button in its title bar.
SpreadsheetApp.getUi().alert('Hello, world');مولفه های
| نام | تایپ کنید | شرح |
|---|---|---|
prompt | String | پیامی که در کادر محاوره ای نمایش داده می شود. |
برگشت
Button - دکمه ای که کاربر روی آن کلیک کرده است.
alert(prompt, buttons)
کادر محاوره ای را در ویرایشگر کاربر با پیام داده شده و مجموعه دکمه ها باز می کند. این روش اسکریپت سمت سرور را در حالی که گفتگو باز است به حالت تعلیق در می آورد. اسکریپت پس از رد گفتگو توسط کاربر از سر گرفته می شود، اما اتصالات Jdbc و قفل های LockService در سراسر تعلیق باقی نمی مانند. برای اطلاعات بیشتر، راهنمای گفتگوها و نوارهای کناری را ببینید.
// Display a dialog box with a message and "Yes" and "No" buttons. The user can also close the
// dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.alert('Are you sure you want to continue?', ui.ButtonSet.YES_NO);
// Process the user's response.
if (response == ui.Button.YES) {
Logger.log('The user clicked "Yes."');
} else {
Logger.log('The user clicked "No" or the close button in the dialog\'s title bar.');
}مولفه های
| نام | تایپ کنید | شرح |
|---|---|---|
prompt | String | پیامی که در کادر محاوره ای نمایش داده می شود. |
buttons | ButtonSet | دکمه تنظیم شده برای نمایش در کادر محاوره ای. |
برگشت
Button - دکمه ای که کاربر روی آن کلیک کرده است.
alert(title, prompt, buttons)
کادر محاوره ای را در ویرایشگر کاربر با عنوان، پیام و مجموعه دکمه های داده شده باز می کند. این روش اسکریپت سمت سرور را در حالی که گفتگو باز است به حالت تعلیق در می آورد. اسکریپت پس از رد گفتگو توسط کاربر از سر گرفته می شود، اما اتصالات Jdbc و قفل های LockService در سراسر تعلیق باقی نمی مانند. برای اطلاعات بیشتر، راهنمای گفتگوها و نوارهای کناری را ببینید.
// Display a dialog box with a title, message, and "Yes" and "No" buttons. The user can also
// close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.alert('Confirm', 'Are you sure you want to continue?', ui.ButtonSet.YES_NO);
// Process the user's response.
if (response == ui.Button.YES) {
Logger.log('The user clicked "Yes."');
} else {
Logger.log('The user clicked "No" or the close button in the dialog\'s title bar.');
}مولفه های
| نام | تایپ کنید | شرح |
|---|---|---|
title | String | عنوانی که در بالای کادر محاوره ای نمایش داده می شود. |
prompt | String | پیامی که در کادر محاوره ای نمایش داده می شود. |
buttons | ButtonSet | دکمه تنظیم شده برای نمایش در کادر محاوره ای. |
برگشت
Button - دکمه ای که کاربر روی آن کلیک کرده است.
createAddonMenu()
سازنده ای ایجاد می کند که می تواند برای درج یک منوی فرعی در منوی افزونه های ویرایشگر استفاده شود. تا زمانی که Menu.addToUi() فراخوانی نشود، منو در واقع به روز نمی شود. اگر اسکریپت به عنوان یک افزونه اجرا می شود، نام زیر منو با نام افزونه در فروشگاه وب مطابقت دارد. اگر اسکریپت مستقیماً به سند متصل شود، نام زیر منو با نام اسکریپت مطابقت دارد. برای اطلاعات بیشتر، راهنمای منوها را ببینید.
// Add an item to the Add-on menu, under a sub-menu whose name is set automatically.
function onOpen(e) {
SpreadsheetApp.getUi()
.createAddonMenu()
.addItem('Show', 'showSidebar')
.addToUi();
}برگشت
Menu - سازنده منوی جدید.
createMenu(caption)
سازنده ای ایجاد می کند که می تواند برای افزودن یک منو به رابط کاربری ویرایشگر استفاده شود. تا زمانی که Menu.addToUi() فراخوانی نشود، منو در واقع اضافه نمی شود. برای اطلاعات بیشتر، راهنمای منوها را ببینید. برچسب یک منوی سطح بالا باید با حروف سرفصل باشد (همه کلمات اصلی با حروف بزرگ نوشته شده باشند)، اگرچه برچسب یک منوی فرعی باید با حروف جمله باشد (فقط اولین کلمه با حروف بزرگ). اگر اسکریپت به عنوان یک افزونه منتشر شود، پارامتر caption نادیده گرفته می‌شود و منو به عنوان زیر منوی منوی Extensions، معادل createAddonMenu() اضافه می‌شود.
// Add a custom menu to the active document, including a separator and a sub-menu.
function onOpen(e) {
SpreadsheetApp.getUi()
.createMenu('My Menu')
.addItem('My menu item', 'myFunction')
.addSeparator()
.addSubMenu(SpreadsheetApp.getUi().createMenu('My sub-menu')
.addItem('One sub-menu item', 'mySecondFunction')
.addItem('Another sub-menu item', 'myThirdFunction'))
.addToUi();
}مولفه های
| نام | تایپ کنید | شرح |
|---|---|---|
caption | String | برچسب منو، با تمام کلمات اصلی با حروف بزرگ برای یک منوی سطح بالا، یا فقط اولین کلمه با حروف بزرگ برای یک منوی فرعی. |
برگشت
Menu - سازنده منوی جدید.
prompt(prompt)
کادر محاوره ای ورودی را با پیام داده شده و دکمه "OK" در ویرایشگر کاربر باز می کند. این روش اسکریپت سمت سرور را در حالی که گفتگو باز است به حالت تعلیق در می آورد. اسکریپت پس از رد گفتگو توسط کاربر از سر گرفته می شود، اما اتصالات Jdbc و قفل های LockService در سراسر تعلیق باقی نمی مانند. برای اطلاعات بیشتر، راهنمای گفتگوها و نوارهای کناری را ببینید.
// Display a dialog box with a message, input field, and an "OK" button. The user can also
// close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.prompt('Enter your name:');
// Process the user's response.
if (response.getSelectedButton() == ui.Button.OK) {
Logger.log('The user\'s name is %s.', response.getResponseText());
} else {
Logger.log('The user clicked the close button in the dialog\'s title bar.');
}مولفه های
| نام | تایپ کنید | شرح |
|---|---|---|
prompt | String | پیامی که در کادر محاوره ای نمایش داده می شود. |
برگشت
PromptResponse - نمایشی از پاسخ کاربر.
prompt(prompt, buttons)
یک کادر محاوره ای ورودی را با پیام داده شده و مجموعه دکمه ها در ویرایشگر کاربر باز می کند. این روش اسکریپت سمت سرور را در حالی که گفتگو باز است به حالت تعلیق در می آورد. اسکریپت پس از رد گفتگو توسط کاربر از سر گرفته می شود، اما اتصالات Jdbc و قفل های LockService در سراسر تعلیق باقی نمی مانند. برای اطلاعات بیشتر، راهنمای گفتگوها و نوارهای کناری را ببینید.
// Display a dialog box with a message, input field, and "Yes" and "No" buttons. The user can
// also close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.prompt('May I know your name?', ui.ButtonSet.YES_NO);
// Process the user's response.
if (response.getSelectedButton() == ui.Button.YES) {
Logger.log('The user\'s name is %s.', response.getResponseText());
} else if (response.getSelectedButton() == ui.Button.NO) {
Logger.log('The user didn\'t want to provide a name.');
} else {
Logger.log('The user clicked the close button in the dialog\'s title bar.');
}مولفه های
| نام | تایپ کنید | شرح |
|---|---|---|
prompt | String | پیامی که در کادر محاوره ای نمایش داده می شود. |
buttons | ButtonSet | دکمه تنظیم شده برای نمایش در کادر محاوره ای. |
برگشت
PromptResponse - نمایشی از پاسخ کاربر.
prompt(title, prompt, buttons)
کادر محاوره ای ورودی را با عنوان، پیام و مجموعه دکمه های داده شده در ویرایشگر کاربر باز می کند. این روش اسکریپت سمت سرور را در حالی که گفتگو باز است به حالت تعلیق در می آورد. اسکریپت پس از رد گفتگو توسط کاربر از سر گرفته می شود، اما اتصالات Jdbc و قفل های LockService در سراسر تعلیق باقی نمی مانند. برای اطلاعات بیشتر، راهنمای گفتگوها و نوارهای کناری را ببینید.
// Display a dialog box with a title, message, input field, and "Yes" and "No" buttons. The
// user can also close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.prompt('Getting to know you', 'May I know your name?', ui.ButtonSet.YES_NO);
// Process the user's response.
if (response.getSelectedButton() == ui.Button.YES) {
Logger.log('The user\'s name is %s.', response.getResponseText());
} else if (response.getSelectedButton() == ui.Button.NO) {
Logger.log('The user didn\'t want to provide a name.');
} else {
Logger.log('The user clicked the close button in the dialog\'s title bar.');
}مولفه های
| نام | تایپ کنید | شرح |
|---|---|---|
title | String | عنوانی که در بالای کادر محاوره ای نمایش داده می شود. |
prompt | String | پیامی که در کادر محاوره ای نمایش داده می شود. |
buttons | ButtonSet | دکمه تنظیم شده برای نمایش در کادر محاوره ای. |
برگشت
PromptResponse - نمایشی از پاسخ کاربر.
showModalDialog(userInterface, title)
یک کادر محاوره ای مدال را در ویرایشگر کاربر با محتوای سمت مشتری سفارشی باز می کند. این روش اسکریپت سمت سرور را در حالی که گفتگو باز است معلق نمی کند. برای برقراری ارتباط با اسکریپت سمت سرور، مؤلفه سمت سرویس گیرنده باید با استفاده از google.script API برای HtmlService تماس‌های غیرهمزمان برقرار کند. برای بستن محاوره به صورت برنامه‌ریزی، google.script.host.close() در سمت سرویس گیرنده یک برنامه وب HtmlService فراخوانی کنید. برای اطلاعات بیشتر، راهنمای گفتگوها و نوارهای کناری را ببینید.
دیالوگ های مدال از تعامل کاربر با هر چیزی غیر از گفتگو جلوگیری می کند. در مقابل، دیالوگ ها و نوارهای فرعی بدون حالت به کاربر اجازه می دهند با ویرایشگر تعامل داشته باشند. تقریباً در همه موارد، یک دیالوگ مودال یا نوار کناری انتخاب بهتری نسبت به یک گفتگوی بدون مدل است.
// Display a modal dialog box with custom HtmlService content.
var htmlOutput = HtmlService
.createHtmlOutput('<p>A change of speed, a change of style...</p>')
.setWidth(250)
.setHeight(300);
SpreadsheetApp.getUi().showModalDialog(htmlOutput, 'My add-on');مولفه های
| نام | تایپ کنید | شرح |
|---|---|---|
userInterface | Object | یک HtmlOutput که نمایانگر رابط برای نمایش است. |
title | String | عنوان گفتگو؛ با فراخوانی setTitle() روی شی userInterface ، هر عنوانی را که تنظیم شده است لغو می کند. |
مجوز
اسکریپت هایی که از این روش استفاده می کنند نیاز به مجوز با یک یا چند مورد از حوزه های زیر دارند:
-
https://www.googleapis.com/auth/script.container.ui
showModelessDialog(userInterface, title)
یک کادر محاوره‌ای بدون حالت را در ویرایشگر کاربر با محتوای سمت مشتری سفارشی باز می‌کند. این روش اسکریپت سمت سرور را در حالی که گفتگو باز است معلق نمی کند. برای برقراری ارتباط با اسکریپت سمت سرور، مؤلفه سمت سرویس گیرنده باید با استفاده از google.script API برای HtmlService تماس‌های غیرهمزمان برقرار کند. برای بستن محاوره به صورت برنامه‌ریزی، google.script.host.close() در سمت سرویس گیرنده یک برنامه وب HtmlService فراخوانی کنید. برای اطلاعات بیشتر، راهنمای گفتگوها و نوارهای کناری را ببینید.
دیالوگ های بدون مدل به کاربر اجازه می دهند با ویرایشگر پشت گفتگو تعامل داشته باشند. در مقابل، دیالوگ های مودال این کار را نمی کنند. تقریباً در همه موارد، یک دیالوگ مودال یا نوار کناری انتخاب بهتری نسبت به یک گفتگوی بدون مدل است.
// Display a modeless dialog box with custom HtmlService content.
var htmlOutput = HtmlService
.createHtmlOutput('<p>A change of speed, a change of style...</p>')
.setWidth(250)
.setHeight(300);
SpreadsheetApp.getUi().showModelessDialog(htmlOutput, 'My add-on');مولفه های
| نام | تایپ کنید | شرح |
|---|---|---|
userInterface | Object | یک HtmlOutput که نمایانگر رابط برای نمایش است. |
title | String | عنوان گفتگو؛ با فراخوانی setTitle() روی شی userInterface ، هر عنوانی را که تنظیم شده است لغو می کند. |
مجوز
اسکریپت هایی که از این روش استفاده می کنند نیاز به مجوز با یک یا چند مورد از حوزه های زیر دارند:
-
https://www.googleapis.com/auth/script.container.ui
showSidebar(userInterface)
نوار کناری را در ویرایشگر کاربر با محتوای سمت مشتری سفارشی باز می کند. این روش اسکریپت سمت سرور را در حالی که نوار کناری باز است به حالت تعلیق در نمی آورد. برای برقراری ارتباط با اسکریپت سمت سرور، مؤلفه سمت سرویس گیرنده باید با استفاده از google.script API برای HtmlService تماس‌های غیرهمزمان برقرار کند. برای بستن نوار کناری به صورت برنامه‌نویسی، google.script.host.close() در سمت مشتری یک برنامه وب HtmlService فراخوانی کنید. برای اطلاعات بیشتر، راهنمای گفتگوها و نوارهای کناری را ببینید.
نوار کناری در سمت راست ویرایشگر برای کاربرانی که محیط آنها از زبان چپ به راست استفاده می کند و در سمت چپ ویرایشگر برای زبان های راست به چپ نمایش داده می شود. همه نوارهای کناری نشان داده شده توسط اسکریپت ها 300 پیکسل عرض دارند.
// Display a sidebar with custom HtmlService content.
var htmlOutput = HtmlService
.createHtmlOutput('<p>A change of speed, a change of style...</p>')
.setTitle('My add-on');
SpreadsheetApp.getUi().showSidebar(htmlOutput);مولفه های
| نام | تایپ کنید | شرح |
|---|---|---|
userInterface | Object | یک HtmlOutput که نمایانگر رابط برای نمایش است. |
مجوز
اسکریپت هایی که از این روش استفاده می کنند نیاز به مجوز با یک یا چند مورد از حوزه های زیر دارند:
-
https://www.googleapis.com/auth/script.container.ui