Class 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 یک enum که دکمه‌های محاوره‌ای از پیش تعیین‌شده و محلی‌شده را نشان می‌دهد که توسط یک alert یا Prompt Response.getSelectedButton() برگردانده می‌شود تا نشان دهد کاربر روی کدام دکمه در یک محاوره کلیک کرده است.
Button Set Button Set یک enum که نشان‌دهنده‌ی مجموعه‌های از پیش تعیین‌شده و محلی‌شده‌ای از یک یا چند دکمه‌ی محاوره‌ای است که می‌توانند به یک هشدار یا اعلان اضافه شوند.

روش‌ها

روش نوع بازگشتی شرح مختصر
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 یک کادر محاوره‌ای modal را در ویرایشگر کاربر با محتوای سفارشی سمت کلاینت باز می‌کند.
show Modeless Dialog(userInterface, title) void یک کادر محاوره‌ای بدون مدل در ویرایشگر کاربر با محتوای سفارشی سمت کلاینت باز می‌کند.
show Sidebar(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.
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 و قفل‌های 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.
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 - دکمه‌ای که کاربر روی آن کلیک کرده است.

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 نادیده گرفته می‌شود و منو به عنوان یک زیرمنو از منوی افزونه‌ها، معادل 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.
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 پیامی که قرار است در کادر محاوره‌ای نمایش داده شود.

بازگشت

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.
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 دکمه‌ای که برای نمایش در کادر محاوره‌ای تنظیم شده است.

بازگشت

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.
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 دکمه‌ای که برای نمایش در کادر محاوره‌ای تنظیم شده است.

بازگشت

PromptResponse — نمایشی از پاسخ کاربر.

showModalDialog(userInterface, title)

یک کادر محاوره‌ای modal را در ویرایشگر کاربر با محتوای سفارشی سمت کلاینت باز می‌کند. این روش اسکریپت سمت سرور را در حالی که کادر محاوره‌ای باز است، به حالت تعلیق در نمی‌آورد . برای برقراری ارتباط با اسکریپت سمت سرور، کامپوننت سمت کلاینت باید با استفاده از API google.script برای HtmlService ، فراخوانی‌های غیرهمزمان انجام دهد. برای بستن کادر محاوره‌ای به صورت برنامه‌نویسی، google.script.host.close() را در سمت کلاینت یک برنامه وب HtmlService فراخوانی کنید. برای اطلاعات بیشتر، به راهنمای کادرهای محاوره‌ای و نوارهای کناری مراجعه کنید.

دیالوگ‌های مودال مانع از تعامل کاربر با هر چیزی غیر از دیالوگ می‌شوند. در مقابل، دیالوگ‌ها و نوارهای کناری بدون مود به کاربر اجازه می‌دهند تا با ویرایشگر تعامل داشته باشد. تقریباً در همه موارد، یک دیالوگ مودال یا نوار کناری انتخاب بهتری نسبت به یک دیالوگ بدون مود است. 

// 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

showModelessDialog(userInterface, title)

یک کادر محاوره‌ای بدون مد را در ویرایشگر کاربر با محتوای سفارشی سمت کلاینت باز می‌کند. این روش اسکریپت سمت سرور را در حالی که کادر محاوره‌ای باز است، به حالت تعلیق در نمی‌آورد . برای برقراری ارتباط با اسکریپت سمت سرور، کامپوننت سمت کلاینت باید با استفاده از API google.script برای HtmlService ، فراخوانی‌های غیرهمزمان انجام دهد. برای بستن کادر محاوره‌ای به صورت برنامه‌نویسی، google.script.host.close() را در سمت کلاینت یک برنامه وب HtmlService فراخوانی کنید. برای اطلاعات بیشتر، به راهنمای کادرهای محاوره‌ای و نوارهای کناری مراجعه کنید.

دیالوگ‌های بدون مدل به کاربر اجازه می‌دهند تا با ویرایشگر پشت دیالوگ تعامل داشته باشد. در مقابل، دیالوگ‌های مودال این قابلیت را ندارند. تقریباً در همه موارد، یک دیالوگ مودال یا نوار کناری انتخاب بهتری نسبت به یک دیالوگ بدون مدل است. 

// 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

showSidebar(userInterface)

یک نوار کناری را در ویرایشگر کاربر با محتوای سفارشی سمت کلاینت باز می‌کند. این روش اسکریپت سمت سرور را در حالی که نوار کناری باز است، به حالت تعلیق در نمی‌آورد . برای برقراری ارتباط با اسکریپت سمت سرور، کامپوننت سمت کلاینت باید با استفاده از API google.script برای HtmlService ، فراخوانی‌های غیرهمزمان انجام دهد. برای بستن نوار کناری به صورت برنامه‌نویسی، google.script.host.close() را در سمت کلاینت یک برنامه وب HtmlService فراخوانی کنید. برای اطلاعات بیشتر، به راهنمای دیالوگ‌ها و نوارهای کناری مراجعه کنید.

نوار کناری برای کاربرانی که محیط‌هایشان از زبان چپ به راست استفاده می‌کند، در سمت راست ویرایشگر و برای زبان‌های راست به چپ در سمت چپ ویرایشگر نمایش داده می‌شود. تمام نوارهای کناری نشان داده شده توسط اسکریپت‌ها ۳۰۰ پیکسل عرض دارند. 

// 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

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