对于大多数编辑器插件而言,对话框窗口和边栏面板是主要插件界面。两者均可使用标准 HTML 和 CSS 进行完全自定义,并且您可以使用 Apps 脚本的客户端-服务器通信模型在用户与边栏或对话框互动时运行 Apps 脚本函数。该插件可以定义多个边栏和对话框,但一次只能显示一个。
如果您想阻止用户与编辑器互动,直到他们在插件界面中做出某种选择,请使用对话框;否则,请使用边栏。
对话框
对话框是叠加在主要编辑器内容之上的窗口面板。Apps 脚本对话框是模态的;当对话框打开时,用户无法与编辑器界面的其他元素互动。您可以自定义对话框的内容和大小。
插件对话框的构建方式与 Apps 脚本的自定义对话框相同;一般推荐的步骤如下:
- 创建一个脚本项目文件,用于定义对话框的 HTML 结构、CSS 和客户端 JavaScript 行为。定义对话框时,请参阅编辑器插件样式指南。
- 在您希望打开对话框的服务器端代码中,调用
HtmlService.createHtmlOutputFromFile(filename)
创建一个表示对话框的HtmlOutput
对象。或者,如果您使用的是模板化 HTML,则可以调用HtmlService.createTemplateFromFile(filename)
生成模板,然后调用HtmlTemplate.evaluate()
将其转换为HtmlOutput
对象。 - 调用
Ui.showModalDialog(htmlOutput, dialogTitle)
以使用该HtmlOutput
显示对话框。
对话框在打开时不会暂停服务器端脚本。客户端 JavaScript 可以使用 google.script.run()
和关联的处理程序函数对服务器端进行异步调用。如需了解详情,请参阅客户端到服务器通信。
打开文件的对话框
文件打开对话框是预建的对话框,可让用户从其 Google 云端硬盘中选择文件。您可以向插件添加文件打开对话框,而无需进行设计,但需要进行一些额外配置。此外,您还需要有权访问该插件的 Cloud Platform 项目,才能启用 Google Picker API。
如需了解完整详情,请参阅打开文件对话框。
侧边栏
边栏是显示在编辑器界面右侧的面板,是最常见的插件界面类型。与对话框不同,在边栏打开时,您可以继续与编辑器界面的其他元素进行互动。边栏具有固定宽度,但您可以自定义边栏的内容。
插件边栏的构建方式与 Apps 脚本自定义边栏相同;一般推荐的流程如下:
- 创建一个脚本项目文件,用于定义边栏的 HTML 结构、CSS 和客户端 JavaScript 行为。定义边栏时,请参阅编辑器插件样式指南。
在您希望打开边栏的服务器端代码中,调用
HtmlService.createHtmlOutputFromFile(filename)
创建一个表示边栏的HtmlOutput
对象。或者,如果您使用的是模板化 HTML,则可以调用HtmlService.createTemplateFromFile(filename)
生成模板,然后调用HtmlTemplate.evaluate()
将其转换为HtmlOutput
对象。调用
Ui.showSidebar(htmlOutput)
,以使用该HtmlOutput
显示边栏。
边栏在打开时不会暂停服务器端脚本。客户端 JavaScript 可以使用 google.script.run()
和关联的处理程序函数对服务器端进行异步调用。如需了解详情,请参阅客户端到服务器通信。