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

Confira também

• Configurar seu Suplemento do Office para usar um runtime compartilhado
• Execute o código em seu Suplemento do Office quando o documento for aberto