编辑器插件的对话框和边栏

对于大多数 编辑器插件, 对话框窗口和侧边栏面板是主要的 插件界面。两者均可使用标准 HTML 和 CSS 进行完全自定义 ,并且您可以使用 Google Apps 脚本的 客户端-服务器通信模型 在用户与 侧边栏或对话框互动时运行 Apps 脚本函数。您的插件可以定义多个侧边栏和对话框,但插件一次只能显示一个。

如果您希望在用户在插件界面中做出选择之前阻止用户与编辑器互动,请使用对话框;否则,请使用侧边栏。

对话框

对话框是覆盖在主要编辑器内容之上的窗口面板。Apps 脚本对话框是模态对话框;在打开时,用户无法与编辑器界面的其他元素互动。您可以自定义对话框的内容和大小。

您可以使用与 Apps 脚本 自定义对话框相同的方式构建插件对话框。一般过程如下:

  1. 创建一个脚本项目文件,用于定义对话框的 HTML 结构、CSS 和客户端 JavaScript 行为。请参阅 编辑器插件样式指南
  2. 在您希望打开对话框的服务器端代码中,调用 HtmlService.createHtmlOutputFromFile 以创建一个HtmlOutput 对象表示对话框。或者,如果您使用的是 模板化 HTML,则可以调用 HtmlService.createTemplateFromFile 以生成模板,然后调用 HtmlTemplate.evaluate 以将其转换为 HtmlOutput 对象。
  3. 调用 Ui.showModalDialog 以使用该 HtmlOutput显示对话框。

对话框在打开时不会暂停服务器端脚本。客户端 JavaScript 可以使用 google.script.run 和关联的处理程序函数向服务器端发出异步调用。如需了解详情,请参阅 客户端到服务器的通信

文件打开对话框

文件打开对话框是预构建的对话框,可让用户从其 Google 云端硬盘中选择文件。您可以将文件打开对话框添加到插件,而无需设计它,但它需要一些额外的配置。您还需要访问 插件的 Cloud Platform 项目,才能启用 Google Picker API。

如需了解详情,请参阅 文件打开对话框

侧边栏是显示在编辑器界面右侧的面板,也是最常见的插件界面类型。与对话框不同,您可以在侧边栏打开时继续与编辑器界面的其他元素互动。侧边栏的宽度是固定的,但您可以自定义其内容。

您可以使用与 Apps 脚本 自定义侧边栏相同的方式构建插件侧边栏。一般过程如下:

  1. 创建一个脚本项目文件,用于定义侧边栏的 HTML 结构、CSS 和客户端 JavaScript 行为。定义侧边栏时,请参阅 编辑器插件样式指南
  2. 在您希望打开侧边栏的服务器端代码中,调用 HtmlService.createHtmlOutputFromFile 以创建一个HtmlOutput 对象表示侧边栏。或者,如果您使用的是 模板化 HTML,则可以调用 HtmlService.createTemplateFromFile 以生成模板,然后调用 HtmlTemplate.evaluate 以将其转换为 HtmlOutput 对象。

    插件侧边栏的宽度固定为 300 像素 ,您无法通过调用 HtmlOutput.setWidth 来更改此宽度。

  3. 调用 Ui.showSidebar 以使用该 HtmlOutput显示侧边栏。

侧边栏在打开时不会暂停服务器端脚本。客户端 JavaScript 可以使用 google.script.run 和关联的处理程序函数向服务器端发出异步调用。如需了解详情,请参阅 客户端到服务器的通信