Class Ui

رابط کاربری

نمونه‌ای از محیط رابط کاربری برای یک برنامه 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

روش های منسوخ شده