显示或隐藏 Office 加载项的任务窗格

重要

共享运行时仅在某些 Office 应用程序中受支持。 有关详细信息，请参阅共享运行时要求集。

可以通过调用 Office.addin.showAsTaskpane() 方法显示 Office 加载项的任务窗格。

function onCurrentQuarter() {
    Office.addin.showAsTaskpane()
    .then(function() {
        // Code that enables task pane UI elements for
        // working with the current quarter.
    });
}

前面的代码假定存在名为 CurrentQuarterSales 的 Excel 工作表的情况。 每当激活此工作表时，加载项都会使任务窗格可见。 方法是 onCurrentQuarter 已为工作表注册的 Office.Worksheet.onActivated 事件的处理程序。

还可以通过调用 Office.addin.hide() 方法隐藏任务窗格。

function onCurrentQuarterDeactivated() {
    Office.addin.hide();
}

前面的代码是为 Office.Worksheet.onDeactivated 事件注册的处理程序。

有关显示任务窗格的其他详细信息

调用 Office.addin.showAsTaskpane()时，Office 会在任务窗格中显示你分配为资源 ID 的文件， resid (任务窗格) 值。 resid可以通过打开 manifest.xml 文件并在 元素内<Action xsi:type="ShowTaskpane">定位 <SourceLocation> 来分配或更改此值。 (有关更多详细信息，请参阅 将 Office 外接程序配置为使用共享运行时 。)

由于 Office.addin.showAsTaskpane() 是异步方法，因此代码将继续运行，直到方法完成。 使用 await 关键字或 then() 方法等待完成，具体取决于所使用的 JavaScript 语法。

将外接程序配置为使用共享运行时

若要使用 showAsTaskpane() 和 hide() 方法，外接程序必须使用 共享运行时。 有关详细信息，请参阅 将 Office 外接程序配置为使用共享运行时。

保留状态和事件侦听器

hide()和 showAsTaskpane() 方法只会更改任务窗格的可见性。 它们不会卸载或重新加载它 (或重新初始化其状态) 。

请考虑以下方案：任务窗格设计有选项卡。 首次启动加载项时，“ 开始 ”选项卡处于打开状态。 假设用户打开“ 设置” 选项卡，稍后，任务窗格中的代码调用 hide() 以响应某个事件。 稍后的代码调用 showAsTaskpane() 以响应另一个事件。 任务窗格将重新出现，并且“ 设置” 选项卡仍处于选中状态。

此外，即使在任务窗格处于隐藏状态，在任务窗格中注册的任何事件侦听器也会继续运行。

请考虑以下方案：任务窗格具有 Excel Worksheet.onActivated 的已注册处理程序，以及 Worksheet.onDeactivated 名为 Sheet1 的工作表的事件。 激活的处理程序会导致任务窗格中显示一个绿色点。 停用的处理程序会 (红色点 (这是其默认状态) 。 假设当 Sheet1 未激活且点为红色时，代码调用 hide() 。 当任务窗格处于隐藏状态时， 将激活 Sheet1 。 稍后的代码调用 showAsTaskpane() 以响应某个事件。 打开任务窗格时，点为绿色，因为即使任务窗格已隐藏，事件侦听器和处理程序也会运行。

处理可见性更改事件

当代码使用 showAsTaskpane() 或 hide()更改任务窗格的可见性时，Office 会触发事件 VisibilityModeChanged 。 处理此事件可能很有用。 例如，假设任务窗格显示工作簿中所有工作表的列表。 如果在隐藏任务窗格时添加新工作表，则使任务窗格可见本身不会向列表中添加新工作表名称。 但是，代码可以响应 VisibilityModeChanged 事件以重新加载 Workbook.worksheets 集合中所有工作表的 Worksheet.name 属性，如下面的示例代码所示。

若要为事件注册处理程序，请不要像在大多数 Office JavaScript 上下文中那样使用“add handler”方法。 相反，有一个特殊的函数传递给你的处理程序： Office.addin.onVisibilityModeChanged。 示例如下。 请注意，属性 args.visibilityMode 的类型为 VisibilityMode。

Office.addin.onVisibilityModeChanged(function(args) {
    if (args.visibilityMode == "Taskpane") {
        // Code that runs whenever the task pane is made visible.
        // For example, an Excel.run() that loads the names of
        // all worksheets and passes them to the task pane UI.
    }
});

该函数返回另一个 取消注册处理程序的 函数。 下面是一个简单但不可靠的示例。

const removeVisibilityModeHandler =
    Office.addin.onVisibilityModeChanged(function(args) {
        if (args.visibilityMode == "Taskpane") {
            // Code that runs whenever the task pane is made visible.
        }
    });


// In some later code path, deregister with:
removeVisibilityModeHandler();

onVisibilityModeChanged方法是异步的，并返回一个 promise，这意味着代码需要等待承诺的实现，然后才能调用取消注册处理程序。

// await the promise from onVisibilityModeChanged and assign
// the returned deregister handler to removeVisibilityModeHandler.
const removeVisibilityModeHandler =
    await Office.addin.onVisibilityModeChanged(function(args) {
        if (args.visibilityMode == "Taskpane") {
            // Code that runs whenever the task pane is made visible.
        }
    });

取消注册函数也是异步的，并返回 promise。 因此，如果代码在注销完成之前不应运行，则应等待注销函数返回的承诺。

// await the promise from the deregister handler before continuing
await removeVisibilityModeHandler();
// subsequent code here

另请参阅

• 将 Office 外接程序配置为使用共享运行时
• 文档打开时在 Office 加载项中运行代码