Abrir automaticamente um painel de tarefas quando um suplemento é instalado

Você pode configurar o painel de tarefas do suplemento para ser iniciado imediatamente após a instalação. Esse recurso aumenta o uso.

Dica

Este artigo descreve um recurso que permite que um suplemento abra seu painel de tarefas quando o suplemento é instalado por um usuário final. Esse recurso tem como escopo um único documento: aquele que é aberto quando o suplemento é instalado. Esse recurso é diferente de três recursos semelhantes:

  • Um suplemento pode configurar programaticamente um documento para abrir automaticamente o painel de tarefas do suplemento quando o documento é aberto. A técnica tem escopo documental, o que significa que deve ser aplicada a cada documento individualmente. Para obter mais informações, consulte Abrir automaticamente um painel de tarefas com um documento.
  • Um suplemento pode se configurar programaticamente para executar o código quando um documento é aberto. Esse recurso também deve ser aplicado a cada documento individualmente. Para obter mais informações, consulte Configurar um documento para executar código quando ele for aberto.
  • Um suplemento pode ser configurado no manifesto para executar o código quando qualquer documento for aberto. Esse recurso tem escopo de aplicativo do Office. Depois que um suplemento é instalado por um administrador do Microsoft 365 no portal de Administração do locatário do Microsoft 365, o suplemento inicia e executa o código em todos os documentos do Office abertos nos aplicativos do Office aos quais o suplemento está configurado, no manifesto, para dar suporte. Para obter mais informações, consulte Ativar suplementos com eventos, especialmente as informações sobre o OnDocumentOpened evento.

Por padrão, os suplementos do painel de tarefas que não incluem nenhum comando de suplemento abrem o painel de tarefas imediatamente após a instalação. No entanto, quando um suplemento tem um ou mais comandos de suplemento, o usuário é notificado sobre um novo suplemento, mas o suplemento não é iniciado automaticamente. Esse comportamento padrão histórico está mudando, portanto, os suplementos que têm comandos de suplemento serão iniciados automaticamente em algumas situações. Além disso, se o suplemento tiver mais de uma página do painel de tarefas, será possível controlar se o suplemento é iniciado após a instalação e, em caso afirmativo, qual página será aberta no painel de tarefas.

Observação

  • Esse recurso se aplica somente a suplementos instalados por um usuário final, não a suplementos implantados centralmente.
  • Esse recurso não se aplica a suplementos de conteúdo ou suplementos de Email (Outlook).
  • Esse recurso se aplica somente a suplementos que tenham pelo menos um comando de suplemento do tipo "comando do painel de tarefas".

Novo comportamento

O novo comportamento é o seguinte:

  • Se o suplemento tiver apenas um comando do painel de tarefas, a guia da faixa de opções do suplemento será selecionada e o painel de tarefas será aberto automaticamente após a instalação. Você não precisa configurar nada.
  • Se o suplemento tiver vários comandos do painel de tarefas e um estiver configurado para ser o padrão (confira Configurar painel de tarefas padrão), a guia da faixa de opções do suplemento será selecionada e o painel de tarefas padrão será aberto automaticamente após a instalação.
  • Se o suplemento tiver vários comandos do painel de tarefas, mas nenhum estiver configurado para ser o padrão, a guia da faixa de opções do suplemento será selecionada automaticamente após a instalação e um texto explicativo será exibido próximo a ela notificando o usuário sobre o novo suplemento, mas nenhum painel de tarefas será aberto. Isso é igual ao comportamento padrão histórico.

Observação

Se, por algum motivo, o comando do suplemento que inicia o painel de tarefas não puder ser selecionado manualmente por um usuário na inicialização, como quando ele está configurado para ser desabilitado na inicialização, ele não será aberto automaticamente, independentemente da configuração.

Configurar o painel de tarefas padrão no manifesto

O processo para especificar o painel de tarefas padrão depende do tipo de manifesto que o suplemento usa.

Para especificar o painel de tarefas padrão, localize o objeto de tempo de execução na "runtimes" matriz cuja "code.page" propriedade está definida para a URL da página que você deseja que seja o padrão. Certifique-se de que a "actions" matriz nesse mesmo objeto de runtime tenha pelo menos uma ação cujo "type" valor seja "openPage". Adicione uma "view" propriedade a este objeto de ação e defina-o como "Office.AutoShowTaskpaneWithDocument". Você só pode definir esse valor em um objeto de ação e ele deve ser uma ação do tipo "openPage". Se você definir esse valor em várias ações, a primeira ocorrência do valor será reconhecida como padrão e as outras serão ignoradas.

O exemplo a seguir mostra um "view" valor definido como "Office.AutoShowTaskpaneWithDocument".

"runtimes": [
    {
        ...
        "code": {
            "page": "https://contoso.com/taskpane.html"
        },
        "actions": [
            {
                "id": "ShowTaskPane",
                "type": "openPage",
                "view": "Office.AutoShowTaskpaneWithDocument"
            }
        ]
    }
]

Dica

Se quiser que o suplemento seja iniciado automaticamente sempre que o usuário reabrir o documento, você precisará executar outras etapas de configuração. Para obter detalhes e conselhos sobre quando usar esse recurso, consulte Abrir automaticamente um painel de tarefas com um documento.

Confira também

  • Última atualização em