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.
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	アラートまたはプロンプトに追加できる 1 つ以上のダイアログ ボタンのローカライズされた事前定義済みセットを表す列挙型。

Methods

メソッド	戻り値の型	概要
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	ユーザーのエディタでサイドバーを開き、クライアントサイドのカスタム コンテンツを表示します。

サポート終了のメソッド

メソッド	戻り値の型	概要
showDialog(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 パラメータは無視され、メニューが拡張機能メニューのサブメニューとして追加されます（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)

ユーザーのエディタでモーダル ダイアログ ボックスが開き、クライアント サイドのカスタム コンテンツが表示されます。このメソッドでは、ダイアログが開いている間はサーバー側のスクリプトは一時停止されません。サーバーサイド スクリプトと通信するために、クライアントサイド コンポーネントは HtmlService の google.script API を使用して非同期コールバックを行う必要があります。プログラムでダイアログを閉じるには、HtmlService ウェブアプリのクライアント側で google.script.host.close() を呼び出します。詳しくは、ダイアログとサイドバーに関するガイドをご覧ください。

モーダル ダイアログでは、ユーザーはダイアログ以外を操作できません。一方、モードレス ダイアログとサイドバーでは、ユーザーはエディタを操作できます。ほとんどの場合、モードレス ダイアログよりもモーダル ダイアログまたはサイドバーを使用することをおすすめします。

// 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	ダイアログのタイトル。userInterface オブジェクトに対して setTitle() を呼び出すことで、設定されたタイトルをオーバーライドします。

承認

この方法を使用するスクリプトには、次の 1 つ以上のスコープによる承認が必要です。

• 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.
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	ダイアログのタイトル。userInterface オブジェクトに対して setTitle() を呼び出すことで、設定されたタイトルをオーバーライドします。

承認

この方法を使用するスクリプトには、次の 1 つ以上のスコープによる承認が必要です。

• 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.
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。

承認

この方法を使用するスクリプトには、次の 1 つ以上のスコープによる承認が必要です。

• 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.
var 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。

承認

この方法を使用するスクリプトには、次の 1 つ以上のスコープによる承認が必要です。

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