Class Ui

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.
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.');
}

屬性

屬性類型說明
ButtonButton這個列舉代表由 alertPromptResponse.getSelectedButton() 傳回的預先定義、經過本地化的對話方塊按鈕,用於指出使用者按下對話方塊中的哪個按鈕。
ButtonSetButtonSet這個列舉代表預先定義的本地化一或多個對話方塊集合,可新增至警示提示

方法

方法傳回類型簡短說明
alert(prompt)Button在使用者編輯器中開啟對話方塊,並顯示指定訊息和「確定」按鈕。
alert(prompt, buttons)Button在使用者編輯器中開啟對話方塊,並顯示指定訊息和一組按鈕。
alert(title, prompt, buttons)Button在使用者編輯器中開啟對話方塊,並顯示指定的標題、訊息和按鈕組合。
createAddonMenu()Menu建立可用於在編輯器的「Extensions」選單中插入子選單的建構工具。
createMenu(caption)Menu建立可用於將選單新增至編輯器使用者介面的建構工具。
prompt(prompt)PromptResponse在使用者編輯器中開啟輸入對話方塊,並顯示指定訊息和「確定」按鈕。
prompt(prompt, buttons)PromptResponse在使用者編輯器中開啟輸入對話方塊,並顯示指定訊息和一組按鈕。
prompt(title, prompt, buttons)PromptResponse在使用者編輯器中開啟輸入對話方塊,並顯示指定的標題、訊息和按鈕組合。
showModalDialog(userInterface, title)void在使用者編輯器中開啟模態對話方塊,並顯示自訂用戶端內容。
showModelessDialog(userInterface, title)void在使用者編輯器中開啟無模式對話方塊,並顯示自訂的用戶端內容。
showSidebar(userInterface)void在使用者編輯器中開啟側欄,並顯示自訂用戶端內容。

內容詳盡的說明文件

alert(prompt)

在使用者編輯器中開啟對話方塊,並顯示指定訊息和「確定」按鈕。這個方法會在對話方塊開啟時暫停伺服器端指令碼。使用者關閉對話方塊後,指令碼會恢復,但 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');

參數

名稱類型說明
promptString對話方塊中顯示的訊息。

回攻員

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.',
  );
}

參數

名稱類型說明
promptString對話方塊中顯示的訊息。
buttonsButtonSet對話方塊中顯示的按鈕。

回攻員

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.',
  );
}

參數

名稱類型說明
titleString顯示在對話方塊上方的標題。
promptString對話方塊中顯示的訊息。
buttonsButtonSet對話方塊中顯示的按鈕。

回攻員

Button:使用者按下的按鈕。


createAddonMenu()

建立可用於在編輯器的「Extensions」選單中插入子選單的建構工具。系統必須呼叫 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();
}

參數

名稱類型說明
captionString選單的標籤,頂層選單的所有主要字詞都會大寫,子選單則只會將第一個字詞大寫。

回攻員

Menu:新版選單建構工具。


prompt(prompt)

在使用者編輯器中開啟輸入對話方塊,並顯示指定訊息和「確定」按鈕。這個方法會在對話方塊開啟時暫停伺服器端指令碼。使用者關閉對話方塊後,指令碼會繼續執行,但 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.');
}

參數

名稱類型說明
promptString對話方塊中顯示的訊息。

回攻員

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.');
}

參數

名稱類型說明
promptString對話方塊中顯示的訊息。
buttonsButtonSet對話方塊中顯示的按鈕。

回攻員

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.');
}

參數

名稱類型說明
titleString顯示在對話方塊上方的標題。
promptString對話方塊中顯示的訊息。
buttonsButtonSet對話方塊中顯示的按鈕。

回攻員

PromptResponse:代表使用者的回應。


showModalDialog(userInterface, title)

在使用者編輯器中開啟模態對話方塊,並顯示自訂用戶端內容。這個方法在對話方塊開啟時「不會」暫停伺服器端指令碼。為了與伺服器端指令碼進行通訊,用戶端元件必須使用 HtmlServicegoogle.script API 發出非同步回呼。如要以程式設計方式關閉對話方塊,請在 HtmlService 網路應用程式的用戶端端點叫用 google.script.host.close()。詳情請參閱對話方塊和側欄指南

強制回應對話方塊可防止使用者與對話方塊以外的任何內容互動。相較之下,無模式對話方塊側欄可讓使用者與編輯器互動。在大多數情況下,使用模態對話方塊或側邊欄,比使用無模式對話方塊更為合適。

// 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');

參數

名稱類型說明
userInterfaceObject代表要顯示的介面的 HtmlOutput
titleString對話方塊的標題,會覆寫在 userInterface 物件上呼叫 setTitle() 時設定的任何標題。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權:

  • https://www.googleapis.com/auth/script.container.ui

showModelessDialog(userInterface, title)

在使用者編輯器中開啟無模式對話方塊,並顯示自訂用戶端內容。這個方法在對話方塊開啟時「不會」暫停伺服器端指令碼。如要與伺服器端指令碼通訊,用戶端元件必須使用 HtmlServicegoogle.script API 建立非同步回呼。如要以程式設計方式關閉對話方塊,請在 HtmlService 網路應用程式的用戶端端點叫用 google.script.host.close()。詳情請參閱對話方塊和側欄指南

無模式對話方塊可讓使用者與對話方塊後方的編輯器互動。相反地,模態對話方塊則不會。在大多數情況下,使用模式對話方塊或側欄,比使用無模式對話方塊更適合。

// 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');

參數

名稱類型說明
userInterfaceObject代表要顯示的介面的 HtmlOutput
titleString對話方塊的標題,會覆寫在 userInterface 物件上呼叫 setTitle() 時設定的任何標題。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權:

  • https://www.googleapis.com/auth/script.container.ui

showSidebar(userInterface)

在使用者編輯器中開啟側欄,並顯示自訂用戶端內容。這個方法在側欄開啟時「不會」暫停伺服器端指令碼。為了與伺服器端指令碼進行通訊,用戶端元件必須使用 HtmlServicegoogle.script API 發出非同步回呼。如要以程式設計方式關閉側欄,請在 HtmlService 網路應用程式的用戶端端點叫用 google.script.host.close()。詳情請參閱對話方塊和側欄指南

如果使用者環境使用由左至右的語言,側欄會顯示在編輯器的右側;如果使用由右至左的語言,則會顯示在編輯器的左側。所有由指令碼顯示的側欄寬度皆為 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);

參數

名稱類型說明
userInterfaceObject代表要顯示的介面的 HtmlOutput

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權:

  • https://www.googleapis.com/auth/script.container.ui

已淘汰的方法