Google Workspace 文件中的對話方塊和側欄

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

與 Google 文件、試算表或表單繫結的指令碼可以顯示多種類型的使用者介面元素,包括預先建立的快訊和提示,以及含有自訂 HTML 服務頁面的對話方塊和側欄。一般來說,這些元素會從選單項目開啟。請注意,在 Google 表單中,使用者介面元素只有開啟表單及修改的編輯器才能查看,而開啟表單回應的使用者則不會看見。

快訊對話方塊

快訊是預先建立的對話方塊,會在 Google 文件、試算表、簡報或表單編輯器中開啟。系統隨即會顯示訊息和「確定」按鈕;您可以視需要使用標題和替代按鈕。做法類似在網路瀏覽器中透過用戶端 JavaScript 呼叫 window.alert()

警示會在對話方塊開啟時暫停伺服器端指令碼。使用者關閉對話方塊後,系統會繼續執行指令碼,但 JDBC 連線不會在暫停期間保留。

如下方範例所示,Google 文件、表單、簡報和試算表均使用 Ui.alert() 方法,有三種變化版本。如要覆寫預設的「OK」按鈕,請將 Ui.ButtonSet 列舉中的值做為 buttons 引數傳遞。如要評估使用者點選的按鈕,請比較 alert() 的傳回值與 Ui.Button 列舉。

function onOpen() {
  SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp.
      .createMenu('Custom Menu')
      .addItem('Show alert', 'showAlert')
      .addToUi();
}

function showAlert() {
  var ui = SpreadsheetApp.getUi(); // Same variations.

  var result = ui.alert(
     'Please confirm',
     'Are you sure you want to continue?',
      ui.ButtonSet.YES_NO);

  // Process the user's response.
  if (result == ui.Button.YES) {
    // User clicked "Yes".
    ui.alert('Confirmation received.');
  } else {
    // User clicked "No" or X in the title bar.
    ui.alert('Permission denied.');
  }
}

提示對話方塊

提示是指在 Google 文件、試算表、簡報或表單編輯器中開啟的預先建立對話方塊。當中顯示訊息、文字輸入欄位和「確定」按鈕;可加入標題和替代按鈕。做法類似在網路瀏覽器中透過用戶端 JavaScript 呼叫 window.prompt()

對話方塊會在開啟時暫停伺服器端指令碼。使用者關閉對話方塊後,系統會繼續執行指令碼,但 JDBC 連線不會在暫停期間保留。

如下方範例所示,Google 文件 إ 表單、簡報和試算表均使用 Ui.prompt() 方法,這個方法有三種變化版本。如要覆寫預設的「OK」指標,請將 Ui.ButtonSet 列舉的值傳遞為 buttons 引數。如要評估使用者的回應,請擷取 prompt() 的傳回值,然後呼叫 PromptResponse.getResponseText() 以擷取使用者的輸入內容,然後比較 PromptResponse.getSelectedButton()Ui.Button 列舉的傳回值。

function onOpen() {
  SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp.
      .createMenu('Custom Menu')
      .addItem('Show prompt', 'showPrompt')
      .addToUi();
}

function showPrompt() {
  var ui = SpreadsheetApp.getUi(); // Same variations.

  var result = ui.prompt(
      'Let\'s get to know each other!',
      'Please enter your name:',
      ui.ButtonSet.OK_CANCEL);

  // Process the user's response.
  var button = result.getSelectedButton();
  var text = result.getResponseText();
  if (button == ui.Button.OK) {
    // User clicked "OK".
    ui.alert('Your name is ' + text + '.');
  } else if (button == ui.Button.CANCEL) {
    // User clicked "Cancel".
    ui.alert('I didn\'t get your name.');
  } else if (button == ui.Button.CLOSE) {
    // User clicked X in the title bar.
    ui.alert('You closed the dialog.');
  }
}

自訂對話方塊

自訂對話方塊可在 Google 文件、試算表、簡報或表單編輯器中顯示 HTML 服務使用者介面。

自訂對話方塊在開啟時不會暫停伺服器端指令碼。用戶端元件可以使用 google.script API,對 HTML 服務介面進行非同步呼叫。

透過在 HTML 服務介面的用戶端呼叫 google.script.host.close() 來關閉對話方塊。其他介面只能由使用者或其他本身關閉。

如下方範例所示,Google 文件、表單、簡報和試算表都會使用 Ui.showModalDialog() 方法開啟對話方塊。

Code.gs

function onOpen() {
  SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp.
      .createMenu('Custom Menu')
      .addItem('Show dialog', 'showDialog')
      .addToUi();
}

function showDialog() {
  var html = HtmlService.createHtmlOutputFromFile('Page')
      .setWidth(400)
      .setHeight(300);
  SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp.
      .showModalDialog(html, 'My custom dialog');
}

Page.html

Hello, world! <input type="button" value="Close" onclick="google.script.host.close()" />

自訂側欄

側欄可在 Google 文件、表單、簡報或試算表編輯器中顯示 HTML 服務使用者介面。

對話方塊開啟時,伺服器端不會暫停伺服器端指令碼。用戶端元件可以使用 google.script API,對 HTML 服務介面進行非同步呼叫。

側欄可透過在 HTML 服務介面的用戶端中呼叫 google.script.host.close() 來自行關閉。其他介面只能由使用者或其他介面關閉。

如下方範例所示,Google 文件、表單、簡報和試算表都會使用 Ui.showSidebar() 方法開啟側欄。

Code.gs

function onOpen() {
  SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp.
      .createMenu('Custom Menu')
      .addItem('Show sidebar', 'showSidebar')
      .addToUi();
}

function showSidebar() {
  var html = HtmlService.createHtmlOutputFromFile('Page')
      .setTitle('My custom sidebar');
  SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp.
      .showSidebar(html);
}

Page.html

Hello, world! <input type="button" value="Close" onclick="google.script.host.close()" />

檔案開啟對話方塊

Google 挑選器是「檔案開啟工具」對話方塊,用於儲存 Google 伺服器中儲存的資訊,包括 Google 雲端硬碟、Google 圖片搜尋、Google 影片搜尋等。

如下方範例所示,Picker' 的用戶端 JavaScript API 可在 HTML 服務中用來建立自訂對話方塊,讓使用者選取現有檔案或上傳新檔案,然後將所選內容傳回指令碼以供日後使用。

如要啟用挑選器並取得 API 金鑰,請按照下列說明操作:

  1. 確認您的指令碼專案使用的是標準 GCP 專案
  2. 在 GCP 專案中啟用「Google Picker API」。
  3. 開啟 GCP 專案時,選取 [API 與服務],然後按一下 [憑證]
  4. 按一下「建立憑證 > API 金鑰」。這項操作會建立金鑰,但請編輯金鑰,以便同時新增應用程式限制和金鑰的 API 限制。
  5. 在 API 金鑰對話方塊中按一下 [關閉]
  6. 在您建立的 API 金鑰旁邊,依序按一下「更多」圖示 更多圖示 >「編輯 API 金鑰」
  7. 在「應用程式限制」下方,完成下列步驟:

    1. 選取 [HTTP 參照網址 (網站)]
    2. 在「網站限制」下方,按一下「新增項目」
    3. 按一下「Referrer」(參照網址),然後輸入 *.google.com
    4. 新增其他項目,然後輸入 *.googleusercontent.com 做為參照網址。
    5. 按一下 [完成]。
  8. 在「API 限制」下方,完成下列步驟:

    1. 選取 [限制金鑰]
    2. 在「選取 API」部分中,選取「Google Picker API」,然後按一下「OK」(確定)

      注意:除非您已啟用 API,否則系統不會顯示 Google Picker API,因為此清單只會顯示已為 Cloud 專案啟用的 API。

  9. 按一下「API key」(API 金鑰) 下方的「複製到剪貼簿」圖示 複製到剪貼簿

  10. 按一下底部的 [儲存]。

code.gs

挑選器/code.gs
/**
 * Creates a custom menu in Google Sheets when the spreadsheet opens.
 */
function onOpen() {
  try {
    SpreadsheetApp.getUi().createMenu('Picker')
        .addItem('Start', 'showPicker')
        .addToUi();
  } catch (e) {
    // TODO (Developer) - Handle exception
    Logger.log('Failed with error: %s', e.error);
  }
}

/**
 * Displays an HTML-service dialog in Google Sheets that contains client-side
 * JavaScript code for the Google Picker API.
 */
function showPicker() {
  try {
    const html = HtmlService.createHtmlOutputFromFile('dialog.html')
        .setWidth(600)
        .setHeight(425)
        .setSandboxMode(HtmlService.SandboxMode.IFRAME);
    SpreadsheetApp.getUi().showModalDialog(html, 'Select a file');
  } catch (e) {
    // TODO (Developer) - Handle exception
    Logger.log('Failed with error: %s', e.error);
  }
}

/**
 * Gets the user's OAuth 2.0 access token so that it can be passed to Picker.
 * This technique keeps Picker from needing to show its own authorization
 * dialog, but is only possible if the OAuth scope that Picker needs is
 * available in Apps Script. In this case, the function includes an unused call
 * to a DriveApp method to ensure that Apps Script requests access to all files
 * in the user's Drive.
 *
 * @return {string} The user's OAuth 2.0 access token.
 */
function getOAuthToken() {
  try {
    DriveApp.getRootFolder();
    return ScriptApp.getOAuthToken();
  } catch (e) {
    // TODO (Developer) - Handle exception
    Logger.log('Failed with error: %s', e.error);
  }
}

對話方塊.html

挑選器/dialog.html
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://ssl.gstatic.com/docs/script/css/add-ons.css">
  <script>
    // IMPORTANT: Replace the value for DEVELOPER_KEY with the API key obtained
    // from the Google Developers Console.
    var DEVELOPER_KEY = 'ABC123 ... ';
    var DIALOG_DIMENSIONS = {width: 600, height: 425};
    var pickerApiLoaded = false;

    /**
     * Loads the Google Picker API.
     */
    function onApiLoad() {
      gapi.load('picker', {'callback': function() {
        pickerApiLoaded = true;
      }});
     }

    /**
     * Gets the user's OAuth 2.0 access token from the server-side script so that
     * it can be passed to Picker. This technique keeps Picker from needing to
     * show its own authorization dialog, but is only possible if the OAuth scope
     * that Picker needs is available in Apps Script. Otherwise, your Picker code
     * will need to declare its own OAuth scopes.
     */
    function getOAuthToken() {
      google.script.run.withSuccessHandler(createPicker)
          .withFailureHandler(showError).getOAuthToken();
    }

    /**
     * Creates a Picker that can access the user's spreadsheets. This function
     * uses advanced options to hide the Picker's left navigation panel and
     * default title bar.
     *
     * @param {string} token An OAuth 2.0 access token that lets Picker access the
     *     file type specified in the addView call.
     */
    function createPicker(token) {
      if (pickerApiLoaded && token) {
        var picker = new google.picker.PickerBuilder()
            // Instruct Picker to display only spreadsheets in Drive. For other
            // views, see https://developers.google.com/picker/docs/#otherviews
            .addView(google.picker.ViewId.SPREADSHEETS)
            // Hide the navigation panel so that Picker fills more of the dialog.
            .enableFeature(google.picker.Feature.NAV_HIDDEN)
            // Hide the title bar since an Apps Script dialog already has a title.
            .hideTitleBar()
            .setOAuthToken(token)
            .setDeveloperKey(DEVELOPER_KEY)
            .setCallback(pickerCallback)
            .setOrigin(google.script.host.origin)
            // Instruct Picker to fill the dialog, minus 2 pixels for the border.
            .setSize(DIALOG_DIMENSIONS.width - 2,
                DIALOG_DIMENSIONS.height - 2)
            .build();
        picker.setVisible(true);
      } else {
        showError('Unable to load the file picker.');
      }
    }

    /**
     * A callback function that extracts the chosen document's metadata from the
     * response object. For details on the response object, see
     * https://developers.google.com/picker/docs/result
     *
     * @param {object} data The response object.
     */
    function pickerCallback(data) {
      var action = data[google.picker.Response.ACTION];
      if (action == google.picker.Action.PICKED) {
        var doc = data[google.picker.Response.DOCUMENTS][0];
        var id = doc[google.picker.Document.ID];
        var url = doc[google.picker.Document.URL];
        var title = doc[google.picker.Document.NAME];
        document.getElementById('result').innerHTML =
            '<b>You chose:</b><br>Name: <a href="' + url + '">' + title +
            '</a><br>ID: ' + id;
      } else if (action == google.picker.Action.CANCEL) {
        document.getElementById('result').innerHTML = 'Picker canceled.';
      }
    }

    /**
     * Displays an error message within the #result element.
     *
     * @param {string} message The error message to display.
     */
    function showError(message) {
      document.getElementById('result').innerHTML = 'Error: ' + message;
    }
  </script>
</head>
<body>
  <div>
    <button onclick="getOAuthToken()">Select a file</button>
    <p id="result"></p>
  </div>
  <script src="https://apis.google.com/js/api.js?onload=onApiLoad"></script>
</body>
</html>