نمونه‌ای از محیط رابط کاربری برای یک برنامه 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.
const ui = SpreadsheetApp.getUi();
const 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 | یک عدد که نشان دهنده دکمه های گفتگوی از پیش تعیین شده و محلی شده است که توسط یک هشدار یا Prompt Response.getSelectedButton() بازگردانده می شود تا نشان دهد کاربر روی کدام دکمه در یک گفتگو کلیک کرده است. |
Button Set | Button Set | یک عدد که مجموعه‌های از پیش تعیین‌شده و بومی‌سازی شده‌ای از یک یا چند دکمه گفتگو را نشان می‌دهد که می‌توانند به یک هشدار یا یک درخواست اضافه شوند. |
روش ها
| روش | نوع برگشت | شرح مختصر |
|---|---|---|
alert(prompt) | Button | کادر محاوره ای را با پیام داده شده و دکمه "OK" در ویرایشگر کاربر باز می کند. |
alert(prompt, buttons) | Button | کادر محاوره ای را در ویرایشگر کاربر با پیام داده شده و مجموعه دکمه ها باز می کند. |
alert(title, prompt, buttons) | Button | کادر محاوره ای را در ویرایشگر کاربر با عنوان، پیام و مجموعه دکمه های داده شده باز می کند. |
create Addon Menu() | Menu | سازنده ای ایجاد می کند که می تواند برای درج یک منوی فرعی در منوی افزونه های ویرایشگر استفاده شود. |
create Menu(caption) | Menu | سازنده ای ایجاد می کند که می تواند برای افزودن یک منو به رابط کاربری ویرایشگر استفاده شود. |
prompt(prompt) | Prompt Response | کادر محاوره ای ورودی را با پیام داده شده و دکمه "OK" در ویرایشگر کاربر باز می کند. |
prompt(prompt, buttons) | Prompt Response | یک کادر محاوره ای ورودی را با پیام داده شده و مجموعه دکمه ها در ویرایشگر کاربر باز می کند. |
prompt(title, prompt, buttons) | Prompt Response | کادر محاوره ای ورودی را با عنوان، پیام و مجموعه دکمه های داده شده در ویرایشگر کاربر باز می کند. |
show Modal Dialog(userInterface, title) | void | یک کادر محاوره ای مدال را در ویرایشگر کاربر با محتوای سمت مشتری سفارشی باز می کند. |
show Modeless Dialog(userInterface, title) | void | یک کادر محاوره‌ای بدون حالت را در ویرایشگر کاربر با محتوای سمت مشتری سفارشی باز می‌کند. |
show Sidebar(userInterface) | void | نوار کناری را در ویرایشگر کاربر با محتوای سمت مشتری سفارشی باز می کند. |
مستندات دقیق
alert(prompt)
کادر محاوره ای را با پیام داده شده و دکمه "OK" در ویرایشگر کاربر باز می کند. این روش اسکریپت سمت سرور را در حالی که گفتگو باز است به حالت تعلیق در می آورد. اسکریپت پس از رد گفتگو توسط کاربر از سر گرفته می‌شود، اما اتصالات Jdbc و قفل‌های Lock Service در سراسر تعلیق باقی نمی‌مانند. برای اطلاعات بیشتر، راهنمای گفتگوها و نوارهای کناری را ببینید.
// 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 و قفل‌های Lock Service در سراسر تعلیق باقی نمی‌مانند. برای اطلاعات بیشتر، راهنمای گفتگوها و نوارهای کناری را ببینید.
// 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.
const ui = SpreadsheetApp.getUi();
const 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 | Button Set | دکمه تنظیم شده برای نمایش در کادر محاوره ای. |
بازگشت
Button - دکمه ای که کاربر روی آن کلیک کرده است.
alert(title, prompt, buttons)
کادر محاوره ای را در ویرایشگر کاربر با عنوان، پیام و مجموعه دکمه های داده شده باز می کند. این روش اسکریپت سمت سرور را در حالی که گفتگو باز است به حالت تعلیق در می آورد. اسکریپت پس از رد گفتگو توسط کاربر از سر گرفته می‌شود، اما اتصالات Jdbc و قفل‌های Lock Service در سراسر تعلیق باقی نمی‌مانند. برای اطلاعات بیشتر، راهنمای گفتگوها و نوارهای کناری را ببینید.
// 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.
const ui = SpreadsheetApp.getUi();
const 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 | Button Set | دکمه تنظیم شده برای نمایش در کادر محاوره ای. |
بازگشت
Button - دکمه ای که کاربر روی آن کلیک کرده است.
create Addon Menu()
سازنده ای ایجاد می کند که می تواند برای درج یک منوی فرعی در منوی افزونه های ویرایشگر استفاده شود. تا زمانی که 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 - سازنده منوی جدید.
create Menu(caption)
سازنده ای ایجاد می کند که می تواند برای افزودن یک منو به رابط کاربری ویرایشگر استفاده شود. تا زمانی که Menu.addToUi() فراخوانی نشود، منو در واقع اضافه نمی شود. برای اطلاعات بیشتر، به راهنمای منوها مراجعه کنید. برچسب یک منوی سطح بالا باید با حروف سرفصل باشد (همه کلمات اصلی با حروف بزرگ نوشته شده باشند)، اگرچه برچسب یک منوی فرعی باید با حروف جمله باشد (فقط اولین کلمه با حروف بزرگ). اگر اسکریپت به عنوان یک افزونه منتشر شود، پارامتر caption نادیده گرفته می‌شود و منو به عنوان یک منوی فرعی از منوی Extensions اضافه می‌شود که معادل create Addon Menu() است.
// 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 و قفل‌های Lock Service در سراسر تعلیق باقی نمی‌مانند. برای اطلاعات بیشتر، راهنمای گفتگوها و نوارهای کناری را ببینید.
// 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.
const ui = SpreadsheetApp.getUi();
const 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 | پیامی که در کادر محاوره ای نمایش داده می شود. |
بازگشت
Prompt Response - نمایشی از پاسخ کاربر.
prompt(prompt, buttons)
یک کادر محاوره ای ورودی را با پیام داده شده و مجموعه دکمه ها در ویرایشگر کاربر باز می کند. این روش اسکریپت سمت سرور را در حالی که گفتگو باز است به حالت تعلیق در می آورد. اسکریپت پس از رد گفتگو توسط کاربر از سر گرفته می‌شود، اما اتصالات Jdbc و قفل‌های Lock Service در سراسر تعلیق باقی نمی‌مانند. برای اطلاعات بیشتر، راهنمای گفتگوها و نوارهای کناری را ببینید.
// 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.
const ui = SpreadsheetApp.getUi();
const 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 | Button Set | دکمه تنظیم شده برای نمایش در کادر محاوره ای. |
بازگشت
Prompt Response - نمایشی از پاسخ کاربر.
prompt(title, prompt, buttons)
کادر محاوره ای ورودی را با عنوان، پیام و مجموعه دکمه های داده شده در ویرایشگر کاربر باز می کند. این روش اسکریپت سمت سرور را در حالی که گفتگو باز است به حالت تعلیق در می آورد. اسکریپت پس از رد گفتگو توسط کاربر از سر گرفته می‌شود، اما اتصالات Jdbc و قفل‌های Lock Service در سراسر تعلیق باقی نمی‌مانند. برای اطلاعات بیشتر، راهنمای گفتگوها و نوارهای کناری را ببینید.
// 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.
const ui = SpreadsheetApp.getUi();
const 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 | Button Set | دکمه تنظیم شده برای نمایش در کادر محاوره ای. |
بازگشت
Prompt Response - نمایشی از پاسخ کاربر.
show Modal Dialog(userInterface, title)
یک کادر محاوره ای مدال را در ویرایشگر کاربر با محتوای سمت مشتری سفارشی باز می کند. این روش اسکریپت سمت سرور را در حالی که گفتگو باز است معلق نمی کند. برای برقراری ارتباط با اسکریپت سمت سرور، مؤلفه سمت سرویس گیرنده باید با استفاده از google.script API برای Html Service تماس‌های غیرهمزمان برقرار کند. برای بستن دیالوگ به صورت برنامه‌ای، google.script.host.close() را در سمت سرویس گیرنده یک برنامه وب Html Service فراخوانی کنید. برای اطلاعات بیشتر، راهنمای گفتگوها و نوارهای کناری را ببینید.
دیالوگ های مدال از تعامل کاربر با هر چیزی غیر از گفتگو جلوگیری می کند. در مقابل، دیالوگ ها و نوارهای فرعی بدون حالت به کاربر اجازه می دهند با ویرایشگر تعامل داشته باشند. تقریباً در همه موارد، یک دیالوگ مودال یا نوار کناری انتخاب بهتری نسبت به یک گفتگوی بدون مدل است.
// Display a modal dialog box with custom HtmlService content.
const htmlOutput = HtmlService
.createHtmlOutput(
'<p>A change of speed, a change of style...</p>',
)
.setWidth(250)
.setHeight(300);
SpreadsheetApp.getUi().showModalDialog(htmlOutput, 'My add-on');پارامترها
| نام | تایپ کنید | توضیحات |
|---|---|---|
user Interface | Object | یک Html Output که نمایانگر رابط برای نمایش است. |
title | String | عنوان گفتگو؛ با فراخوانی set Title() در شیء user Interface ، هر عنوانی را که تنظیم شده است لغو می کند. |
مجوز
اسکریپت هایی که از این روش استفاده می کنند نیاز به مجوز با یک یا چند مورد از حوزه های زیر دارند:
-
https://www.googleapis.com/auth/script.container.ui
show Modeless Dialog(userInterface, title)
یک کادر محاوره‌ای بدون حالت را در ویرایشگر کاربر با محتوای سمت مشتری سفارشی باز می‌کند. این روش اسکریپت سمت سرور را در حالی که گفتگو باز است معلق نمی کند. برای برقراری ارتباط با اسکریپت سمت سرور، مؤلفه سمت سرویس گیرنده باید با استفاده از google.script API برای Html Service تماس‌های غیرهمزمان برقرار کند. برای بستن دیالوگ به صورت برنامه‌ای، google.script.host.close() را در سمت سرویس گیرنده یک برنامه وب Html Service فراخوانی کنید. برای اطلاعات بیشتر، راهنمای گفتگوها و نوارهای کناری را ببینید.
دیالوگ های بدون مدل به کاربر اجازه می دهند با ویرایشگر پشت گفتگو تعامل داشته باشند. در مقابل، دیالوگ های مودال این کار را نمی کنند. تقریباً در همه موارد، یک دیالوگ مودال یا نوار کناری انتخاب بهتری نسبت به یک گفتگوی بدون مدل است.
// Display a modeless dialog box with custom HtmlService content.
const htmlOutput = HtmlService
.createHtmlOutput(
'<p>A change of speed, a change of style...</p>',
)
.setWidth(250)
.setHeight(300);
SpreadsheetApp.getUi().showModelessDialog(htmlOutput, 'My add-on');پارامترها
| نام | تایپ کنید | توضیحات |
|---|---|---|
user Interface | Object | یک Html Output که نمایانگر رابط برای نمایش است. |
title | String | عنوان گفتگو؛ با فراخوانی set Title() در شیء user Interface ، هر عنوانی را که تنظیم شده است لغو می کند. |
مجوز
اسکریپت هایی که از این روش استفاده می کنند نیاز به مجوز با یک یا چند مورد از حوزه های زیر دارند:
-
https://www.googleapis.com/auth/script.container.ui
show Sidebar(userInterface)
نوار کناری را در ویرایشگر کاربر با محتوای سمت مشتری سفارشی باز می کند. این روش اسکریپت سمت سرور را در حالی که نوار کناری باز است به حالت تعلیق در نمی آورد. برای برقراری ارتباط با اسکریپت سمت سرور، مؤلفه سمت سرویس گیرنده باید با استفاده از google.script API برای Html Service تماس‌های غیرهمزمان برقرار کند. برای بستن نوار کناری به صورت برنامه‌نویسی، google.script.host.close() را در سمت کلاینت یک برنامه وب Html Service فراخوانی کنید. برای اطلاعات بیشتر، راهنمای گفتگوها و نوارهای کناری را ببینید.
نوار کناری در سمت راست ویرایشگر برای کاربرانی که محیط آنها از زبان چپ به راست استفاده می کند و در سمت چپ ویرایشگر برای زبان های راست به چپ نمایش داده می شود. همه نوارهای کناری نشان داده شده توسط اسکریپت ها 300 پیکسل عرض دارند.
// Display a sidebar with custom HtmlService content.
const htmlOutput = HtmlService
.createHtmlOutput(
'<p>A change of speed, a change of style...</p>',
)
.setTitle('My add-on');
SpreadsheetApp.getUi().showSidebar(htmlOutput);پارامترها
| نام | تایپ کنید | توضیحات |
|---|---|---|
user Interface | Object | یک Html Output که نمایانگر رابط برای نمایش است. |
مجوز
اسکریپت هایی که از این روش استفاده می کنند نیاز به مجوز با یک یا چند مورد از حوزه های زیر دارند:
-
https://www.googleapis.com/auth/script.container.ui