Mostre ou oculte o painel de tarefas de seu Suplemento do Office
Importante
O runtime partilhado só é suportado em algumas aplicações do Office. Para obter mais informações, confira Conjuntos de requisitos de tempo de execução compartilhados.
Pode mostrar o painel de tarefas do seu Suplemento do Office ao chamar 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 existe uma folha de cálculo do Excel com o nome CurrentQuarterSales. O suplemento tornará o painel de tarefas visível sempre que esta folha de cálculo for ativada. O método onCurrentQuarter é um processador do evento Office.Worksheet.onActivated que foi registado na folha de cálculo.
Também pode ocultar o painel de tarefas ao chamar o Office.addin.hide() método .
function onCurrentQuarterDeactivated() {
Office.addin.hide();
}
O código anterior é um processador registado para o evento Office.Worksheet.onDeactivated .
Detalhes adicionais sobre como mostrar o painel de tarefas
Quando chama Office.addin.showAsTaskpane(), o Office irá apresentar num painel de tarefas o ficheiro que especificou no manifesto. A configuração depende do tipo de manifesto que está a utilizar.
Manifesto unificado para o Microsoft 365: o URL do ficheiro é atribuído como o valor de uma propriedade "runtimes.code.page" do objeto de runtime que tem um objeto de ação do tipo "openPage".
Observação
O manifesto unificado do Microsoft 365 pode ser utilizado nos suplementos de produção do Outlook. Está disponível apenas como uma pré-visualização para suplementos do Excel, PowerPoint e Word.
Manifesto apenas de suplemento: o URL do ficheiro é atribuído como o valor de ID de recurso (
resid) do painel de tarefas. Esteresidvalor pode ser atribuído ou alterado ao abrir o ficheiro de manifesto e localizar <SourceLocation> dentro do<Action xsi:type="ShowTaskpane">elemento .
(Consulte Configurar o seu Suplemento do Office para utilizar um runtime partilhado para obter detalhes adicionais.)
Uma Office.addin.showAsTaskpane() vez que é um método assíncrono, o código continuará em execução até que o método esteja concluído. Aguarde até esta conclusão com o await palavra-chave ou um then() método, consoante a sintaxe JavaScript que estiver a utilizar.
Configurar o suplemento para utilizar o runtime partilhado
Para utilizar os showAsTaskpane() métodos e hide() , o seu suplemento tem de utilizar o runtime partilhado. Para obter mais informações, consulte Configurar o seu Suplemento do Office para utilizar um runtime partilhado.
Preservação de serviços de escuta de estado e eventos
Os hide() métodos e showAsTaskpane() só alteram a visibilidade do painel de tarefas. Não descarregam nem recarregam (nem reiniciam o estado).
Considere o seguinte cenário: um painel de tarefas foi concebido com separadores. O separador Base é aberto quando o suplemento é iniciado pela primeira vez. Suponha que um utilizador abre o separador Definições e, mais tarde, o código no painel de tarefas chama hide() em resposta a algum evento. Ainda mais tarde, o código chama showAsTaskpane() em resposta a outro evento. O painel de tarefas voltará a aparecer e o separador Definições ainda está selecionado.
Além disso, todos os serviços de escuta de eventos registados 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 processador registado para o Excel Worksheet.onActivated e Worksheet.onDeactivated eventos para uma folha com o nome Folha1. O processador ativado faz com que seja apresentado um ponto verde no painel de tarefas. O processador desativado torna o ponto vermelho (que é o estado predefinido). Suponhamos que o código chama hide() quando a Folha1 não está ativada e o ponto é vermelho. Enquanto o painel de tarefas está oculto, a Folha1 é ativada. Chamadas showAsTaskpane() de código posteriores em resposta a algum evento. Quando o painel de tarefas é aberto, o ponto fica verde porque os serviços de escuta e os processadores de eventos foram executados, apesar de o painel de tarefas estar oculto.
Processar o evento alterado de visibilidade
Quando o código altera a visibilidade do painel de tarefas com showAsTaskpane() ou hide(), o Office aciona o VisibilityModeChanged evento. Pode ser útil para lidar com este evento. Por exemplo, suponha que o painel de tarefas apresenta uma lista de todas as folhas num livro. Se for adicionada uma nova folha de cálculo enquanto o painel de tarefas estiver oculto, tornar o painel de tarefas visível não adicionaria, por si só, o novo nome da folha de cálculo à lista. No entanto, o código pode responder ao VisibilityModeChanged evento para recarregar a propriedade Worksheet.name de todas as folhas de cálculo na coleção Workbook.worksheets , conforme mostrado no código de exemplo abaixo.
Para registar um processador para o evento, não utilize um método "adicionar processador", como faria na maioria dos contextos javaScript do Office. Em vez disso, existe uma função especial à qual transmite o seu processador: Office.addin.onVisibilityModeChanged. Apresentamos um exemplo a seguir. Tenha em atenção 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 devolve outra função que desregiste o processador. Eis 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 devolve uma promessa, o que significa que o código tem de aguardar o cumprimento da promessa antes de poder chamar o processador de registo .
// 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 registo de registo também é assíncrona e devolve uma promessa. Por isso, se tiver código que só deve ser executado após a conclusão da desregistração, deverá aguardar a promessa devolvida pela função de registo.
// await the promise from the deregister handler before continuing
await removeVisibilityModeHandler();
// subsequent code here