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.
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`	這個列舉代表 alert 或 `PromptResponse.getSelectedButton()` 傳回的預先決定本地化對話方塊按鈕，用於指出使用者點選對話方塊中的哪個按鈕。
`ButtonSet`	`ButtonSet`	列舉代表預先決定的本地化一或多個對話方塊按鈕集，可新增至快訊或提示。

方法

方法	傳回類型	簡短說明
`alert(prompt)`	`Button`	在使用者編輯器中開啟對話方塊，顯示指定訊息和「確定」按鈕。
`alert(prompt, buttons)`	`Button`	在使用者編輯器中開啟對話方塊，顯示指定訊息和一組按鈕。
`alert(title, prompt, buttons)`	`Button`	在使用者編輯器中開啟對話方塊，並顯示指定標題、訊息和按鈕組合。
`createAddonMenu()`	`Menu`	建立可用於在編輯器的「擴充功能」選單中插入子選單的建構工具。
`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`	在使用者編輯器中開啟側欄，顯示自訂的用戶端內容。

已淘汰的方法

方法	傳回類型	簡短說明
`showDialog(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');

參數

名稱	類型	說明
`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`	`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.
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`	`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 參數，並將選單新增為「擴充功能」選單的子選單，相當於 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)`

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

回攻員

PromptResponse：代表使用者的回應。

`showModalDialog(userInterface, title)`

在使用者編輯器中開啟強制回應對話方塊，並顯示自訂的用戶端內容。對話方塊開啟時，這個方法不會暫停伺服器端指令碼。如要與伺服器端指令碼通訊，用戶端元件必須使用 HtmlService 的 google.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');

參數

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

授權

使用這個方法的指令碼需要下列一或多個範圍的授權：

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

`showModelessDialog(userInterface, title)`

在使用者編輯器中開啟無模式對話方塊，並顯示自訂的用戶端內容。對話方塊開啟時，這個方法不會暫停伺服器端指令碼。如要與伺服器端指令碼通訊，用戶端元件必須使用 HtmlService 的 google.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');

參數

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

授權

使用這個方法的指令碼需要下列一或多個範圍的授權：

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

`showSidebar(userInterface)`

在使用者編輯器中開啟側欄，顯示自訂的用戶端內容。側欄開啟時，這個方法不會暫停伺服器端指令碼。如要與伺服器端指令碼通訊，用戶端元件必須使用 HtmlService 的 google.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);

參數

名稱	類型	說明
`userInterface`	`Object`	代表要顯示介面的 `HtmlOutput`。

授權

使用這個方法的指令碼需要下列一或多個範圍的授權：

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

已淘汰的方法

`showDialog(userInterface)`

已淘汰。這項方法已於 2014 年 3 月淘汰。直接替代項目是 showModelessDialog(userInterface, title)，但在幾乎所有情況下，showModalDialog(userInterface, title) 都是更好的選擇。

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

// Display a dialog box with custom HtmlService content.
const htmlOutput = HtmlService
                       .createHtmlOutput(
                           '<p>A change of speed, a change of style...</p>',
                           )
                       .setTitle('My add-on')
                       .setWidth(250)
                       .setHeight(300);
SpreadsheetApp.getUi().showDialog(htmlOutput);

參數

名稱	類型	說明
`userInterface`	`Object`	代表要顯示介面的 `HtmlOutput`。

授權

使用這個方法的指令碼需要下列一或多個範圍的授權：

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

Class Ui 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

屬性

方法

已淘汰的方法

內容詳盡的說明文件

alert(prompt)

參數

回攻員

alert(prompt, buttons)

參數

回攻員

alert(title, prompt, buttons)

參數

回攻員

createAddonMenu()

回攻員

createMenu(caption)

參數

回攻員

prompt(prompt)

參數

回攻員

prompt(prompt, buttons)

參數

回攻員

prompt(title, prompt, buttons)

參數

回攻員

showModalDialog(userInterface, title)

參數

授權

showModelessDialog(userInterface, title)

參數

授權

showSidebar(userInterface)

參數

授權

已淘汰的方法

showDialog(userInterface)

參數

授權

Class Ui

`alert(prompt)`

`alert(prompt, buttons)`

`alert(title, prompt, buttons)`

`createAddonMenu()`

`createMenu(caption)`

`prompt(prompt)`

`prompt(prompt, buttons)`

`prompt(title, prompt, buttons)`

`showModalDialog(userInterface, title)`

`showModelessDialog(userInterface, title)`

`showSidebar(userInterface)`

`showDialog(userInterface)`