Mostre ou oculte o painel de tarefas de seu Suplemento do Office

Você pode mostrar o painel de tarefas do seu 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 , o Office exibirá em um painel de tarefas o arquivo que você especificou no manifesto. A configuração depende do tipo de manifesto que você está usando.

• Manifesto unificado para o Microsoft 365: a URL do arquivo é atribuída como o valor de uma propriedade "runtimes.code.page" do objeto de tempo de execução que tem um objeto de ação do tipo "openPage".
• Manifesto somente do suplemento: a URL do arquivo é atribuída como o valor da ID de recurso (resid) do painel de tarefas. Esse resid valor pode ser atribuído ou alterado abrindo o arquivo de manifesto e localizando-o <SourceLocation> dentro do <Action xsi:type="ShowTaskpane"> elemento.

(Confira Configurar o Suplemento do Office para usar um tempo de execução 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 tempo de execução compartilhado

Para usar os showAsTaskpane() métodos and hide() , o suplemento deve usar o runtime compartilhado. Para obter mais informações, confira Configurar seu Suplemento do Office para usar um runtime compartilhado.

Preservação de ouvintes de estado e eventos

Os hide() métodos e showAsTaskpane() alteram apenas a visibilidade do painel de tarefas. Eles não o descarregam nem recarregam (nem reinicializam seu estado).

Considere o seguinte cenário: Um painel de tarefas é projetado com guias. A guia Página Inicial é 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. Ainda mais tarde, o código chama showAsTaskpane() em resposta a outro evento. O painel de tarefas reaparecerá, e a guia Configurações ainda estará 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 Planilha1. O manipulador ativado faz com que um ponto verde apareça no painel de tarefas. O manipulador desativado deixa o ponto vermelho (que é seu estado padrão). Suponha, então, que o código chame hide() quando Planilha1 não estiver ativada e o ponto estiver vermelho. Enquanto o painel de tarefas estiver oculto, a Planilha1 será ativada. Chamadas showAsTaskpane() de código 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.

Lidar com o evento de alteração de visibilidade

Quando seu código altera a visibilidade do painel de tarefas com showAsTaskpane() ou hide(), o Office dispara o VisibilityModeChanged evento. Pode ser útil manipular 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 na 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 seu manipulador: Office.addin.onVisibilityModeChanged. Apresentamos um exemplo a seguir. Observe que a propriedade é do args.visibilityMode 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 cancela o registro do 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 de chamar o manipulador de cancelamento de registro .

// 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 cancelamento de registro também é assíncrona e retorna uma promessa. Portanto, se você tiver um código que não deve ser executado até que o cancelamento do registro seja concluído, deverá aguardar a promessa retornada pela função de cancelamento de registro.

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

Confira também

• Configurar seu Suplemento do Office para usar um tempo de execução compartilhado
• Execute o código em seu Suplemento do Office quando o documento for aberto