Mostre ou oculte o painel de tarefas de seu Suplemento do Office
Importante
O runtime compartilhado só tem suporte em alguns aplicativos do Office. Para obter mais informações, confira Conjuntos de requisitos de tempo de execução compartilhados.
Você pode mostrar o painel de tarefas do suplemento do Office chamando o Office.addin.showAsTaskpane() método.
function onCurrentQuarter() {
Office.addin.showAsTaskpane()
.then(function() {
// Code that enables task pane UI elements for
// working with the current quarter.
});
}
O código anterior pressupõe um cenário em que há uma planilha do Excel chamada CurrentQuarterSales. O suplemento tornará o painel de tarefas visível sempre que essa planilha for ativada. O método onCurrentQuarter é um manipulador para o evento Office.Worksheet.onActivated que foi registrado para a planilha.
Você também pode ocultar o painel de tarefas chamando o Office.addin.hide() método.
function onCurrentQuarterDeactivated() {
Office.addin.hide();
}
O código anterior é um manipulador registrado para o evento Office.Worksheet.onDeactivated .
Detalhes adicionais sobre como mostrar o painel de tarefas
Quando você chamar Office.addin.showAsTaskpane(), o Office exibirá em um painel de tarefas o arquivo atribuído como o valor da ID do recurso (resid) do painel de tarefas. Esse resid valor pode ser atribuído ou alterado abrindo seu arquivo manifest.xml e localizando <SourceLocation> dentro do <Action xsi:type="ShowTaskpane"> elemento.
(Consulte Configurar seu Suplemento do Office para usar um runtime compartilhado para obter detalhes adicionais.)
Como Office.addin.showAsTaskpane() é um método assíncrono, seu código continuará em execução até que o método seja concluído. Aguarde essa conclusão com a await palavra-chave ou um then() método, dependendo de qual sintaxe JavaScript você está usando.
Configurar seu suplemento para usar o runtime compartilhado
Para usar os showAsTaskpane() métodos e hide() , o suplemento deve usar o runtime compartilhado. Para obter mais informações, consulte Configurar seu Suplemento do Office para usar um runtime compartilhado.
Preservação do estado e dos ouvintes de eventos
Os hide() métodos e showAsTaskpane() só alteram a visibilidade do painel de tarefas. Eles não descarregam ou recarregam (ou reinitializam seu estado).
Considere o seguinte cenário: um painel de tarefas foi projetado com guias. A guia Home é aberta quando o suplemento é iniciado pela primeira vez. Suponha que um usuário abra a guia Configurações e, posteriormente, o código no painel de tarefas chame hide() em resposta a algum evento. Chamadas de código ainda posteriores showAsTaskpane() em resposta a outro evento. O painel de tarefas reaparecerá e a guia Configurações ainda está selecionada.
Além disso, todos os ouvintes de eventos registrados no painel de tarefas continuam a ser executados mesmo quando o painel de tarefas está oculto.
Considere o seguinte cenário: o painel de tarefas tem um manipulador registrado para o Excel Worksheet.onActivated e Worksheet.onDeactivated eventos para uma planilha chamada Sheet1. O manipulador ativado faz com que um ponto verde apareça no painel de tarefas. O manipulador desativado transforma o ponto vermelho (que é seu estado padrão). Suponha que esse código chame hide() quando a Planilha1 não estiver ativada e o ponto estiver vermelho. Enquanto o painel de tarefas está oculto, o Sheet1 é ativado. Chamadas de código showAsTaskpane() posteriores em resposta a algum evento. Quando o painel de tarefas é aberto, o ponto fica verde porque os ouvintes e manipuladores de eventos foram executados mesmo que o painel de tarefas estivesse oculto.
Manipular o evento alterado de visibilidade
Quando o código altera a visibilidade do painel de tarefas com showAsTaskpane() ou hide(), o Office dispara o VisibilityModeChanged evento. Pode ser útil lidar com esse evento. Por exemplo, suponha que o painel de tarefas exiba uma lista de todas as planilhas em uma pasta de trabalho. Se uma nova planilha for adicionada enquanto o painel de tarefas estiver oculto, tornar o painel de tarefas visível não adicionará, por si só, o novo nome da planilha à lista. Mas seu código pode responder ao VisibilityModeChanged evento para recarregar a propriedade Worksheet.name de todas as planilhas da coleção Workbook.worksheets , conforme mostrado no código de exemplo abaixo.
Para registrar um manipulador para o evento, você não usa um método "adicionar manipulador" como faria na maioria dos contextos javaScript do Office. Em vez disso, há uma função especial para a qual você passa o manipulador: Office.addin.onVisibilityModeChanged. Apresentamos um exemplo a seguir. Observe que a args.visibilityMode propriedade é do tipo 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.
}
});
A função retorna outra função que desregista o manipulador. Aqui está um exemplo simples, mas não robusto.
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();
O onVisibilityModeChanged método é assíncrono e retorna uma promessa, o que significa que seu código precisa aguardar o cumprimento da promessa antes que ele possa chamar o manipulador de desregistro .
// 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.
}
});
A função de desregistro também é assíncrona e retorna uma promessa. Portanto, se você tiver um código que não deve ser executado até que a desregistração seja concluída, você deverá aguardar a promessa retornada pela função de desregistro.
// await the promise from the deregister handler before continuing
await removeVisibilityModeHandler();
// subsequent code here