Abrir automaticamente um painel de tarefas com um documento

Você pode usar comandos de suplemento em seu Suplemento do Office para estender a interface do usuário do Office adicionando botões à faixa de opções de aplicativos do Office. Quando os usuários clicam no botão de comando, ocorre uma ação, como abrir um painel de tarefas.

Alguns cenários exigem que um painel de tarefas seja exibido automaticamente ao abrir um documento, sem a interação explícita do usuário. Você pode usar o recurso de painel de tarefas de abertura automática, introduzido no conjunto de requisitos do AddInCommands 1.1, para abrir automaticamente um painel de tarefas quando seu cenário exigir.

De que forma o recurso autoopen é diferente da inserção de um painel de tarefas?

Quando um usuário inicia suplementos que não usam comandos de suplemento, os suplementos são inseridos no documento e persistem nesse documento. Como resultado, quando outros usuários abrem o documento, eles são solicitados a instalar o suplemento e o painel de tarefas é aberto. O desafio com esse modelo é que, em muitos casos, os usuários não querem que o suplemento persista no documento. Por exemplo, um aluno que usa um suplemento de dicionário em um documento do Word pode não querer que seus colegas ou professores sejam avisados para instalar esse suplemento quando abrirem o documento.

Com o recurso autoopen, você pode explicitamente definir, ou permitir que o usuário defina, se um suplemento do painel de tarefas irá persistir em um documento específico.

Suporte e disponibilidade

O recurso de abertura automática tem suporte atualmente nos produtos e plataformas a seguir.

Práticas recomendadas

Aplique as seguintes práticas recomendadas ao usar o recurso de abertura automática.

• Use o recurso autoopen quando ele auxiliar a eficiência dos usuários do seu suplemento, como
  • Quando o documento precisa do suplemento para funcionar corretamente. Por exemplo, uma planilha que inclui valores de ações que são atualizados periodicamente por um suplemento. O suplemento deverá abrir automaticamente quando a planilha for aberta para manter os valores atualizados.
  • Quando é muito provável que o usuário sempre utilizará o suplemento com um determinado documento. Por exemplo, um suplemento que ajuda os usuários a preencher ou alterar dados em um documento puxando informações de um sistema de back-end.
• Permita que os usuários ativem ou desativem o recurso autoopen. Inclua uma opção em sua interface de usuário para que eles possam escolher quando não querem mais que o suplemento abra automaticamente no painel de tarefas.
• Use a detecção do conjunto de requisitos para determinar se o recurso de abertura automática está disponível e forneça um comportamento de fallback se não estiver.
• Não use o recurso autoopen para aumentar artificialmente o uso do seu suplemento. Se não fizer sentido para o seu suplemento abrir automaticamente com determinados documentos, esse recurso pode incomodar os usuários.
• Não use esse recurso para fixar vários painéis de tarefas. Você só pode definir um painel do suplemento para abrir automaticamente com um documento.

Implementar o recurso de abertura automática

• Especifique o painel de tarefas a ser aberto automaticamente.
• Marque o documento para abrir o painel de tarefas automaticamente.

Etapa 1: especificar o painel de tarefas que será aberto

Configure o manifesto para especificar a página do painel de tarefas que deve ser aberta automaticamente. O processo depende do tipo de manifesto que o suplemento usa.

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

<Action xsi:type="ShowTaskpane">
    <TaskpaneId>Office.AutoShowTaskpaneWithDocument</TaskpaneId>
    <SourceLocation resid="Contoso.Taskpane.Url" />
</Action>

Etapa 2: marcar o documento para abrir o painel de tarefas automaticamente

Você pode marcar o documento para acionar o recurso autoopen de duas maneiras. Escolha a alternativa que funciona melhor para o seu cenário.

Marcar o documento no lado do cliente

Use o método Office.js settings.set para definir Office.AutoShowTaskpaneWithDocument como true, conforme mostrado no exemplo a seguir.

Office.context.document.settings.set("Office.AutoShowTaskpaneWithDocument", true);
Office.context.document.settings.saveAsync();

Use esse método se você precisar marcar o documento como parte da interação com o suplemento (por exemplo, assim que o usuário criar uma ligação ou escolher uma opção para indicar que deseja que o painel abra automaticamente).

Usar Open XML para marcar o documento

Você pode usar o Open XML para criar ou modificar um documento e adicionar a marcação XML do Open Office apropriada para acionar o recurso autoopen. Veja um exemplo de como fazer isso em Office-OOXML-EmbedAddin.

Adicione duas partes do Open XML ao documento.

• Uma parte webextension
• Uma parte taskpane

O exemplo a seguir mostra como adicionar a parte webextension.

<we:webextension xmlns:we="http://schemas.microsoft.com/office/webextensions/webextension/2010/11" id="[ADD-IN ID PER MANIFEST]">
  <we:reference id="[GUID or Microsoft Marketplace asset ID]" version="[your add-in version]" store="[Pointer to store or catalog]" storeType="[Store or catalog type]"/>
  <we:alternateReferences/>
  <we:properties>
   <we:property name="Office.AutoShowTaskpaneWithDocument" value="true"/>
  </we:properties>
  <we:bindings/>
  <we:snapshot xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"/>
</we:webextension>

A parte webextension inclui um conjunto de propriedades e uma propriedade chamada Office.AutoShowTaskpaneWithDocument que deve ser definida como true.

A parte webextension também inclui uma referência para a loja ou o catálogo com atributos para id, storeType, store e version. Dos valores storeType, somente quatro são relevantes para o recurso autoopen. Os valores dos outros três atributos dependem do valor de storeType, conforme mostrado na tabela a seguir.

Saiba mais sobre a marcação webextension em [MS-OWEXML] 2.2.5. WebExtensionReference.

O exemplo a seguir mostra como adicionar a parte taskpane.

<wetp:taskpane dockstate="right" visibility="0" width="350" row="4" xmlns:wetp="http://schemas.microsoft.com/office/webextensions/taskpanes/2010/11">
  <wetp:webextensionref xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" r:id="rId1" />
</wetp:taskpane>

Observe que neste exemplo, o atributo visibility está definido como "0". Isso significa que, após adicionar as partes webextension e taskpane, a primeira vez que o documento for aberto, o usuário deve instalar o suplemento clicando no botão Suplemento na faixa de opções. Depois disso, o painel de tarefas do suplemento abre automaticamente quando o arquivo for aberto. E, ao definir visibility como "0", é possível usar o Office.js para permitir que os usuários ativem ou desativem o recurso autoopen. Especificamente, seu script define a configuração de documento Office.AutoShowTaskpaneWithDocument como true ou false. Confira mais detalhes em Marcar o documento no lado do cliente.

Se o elemento visibility é definido como "1", o painel de tarefas abrirá automaticamente na primeira vez em que o documento for aberto. O usuário é solicitado a confiar no suplemento e, quando a confiança é concedida, o suplemento é aberto. Depois disso, o painel de tarefas do suplemento abrirá automaticamente quando o arquivo for aberto. Entretanto, ao definir visibility como "1", não é possível usar o Office.js para permitir que os usuários ativem ou desativem o recurso autoopen.

Definir o visibility como "1" é uma boa opção quando o suplemento e o modelo ou o conteúdo do documento são muito estreitamente integrados de modo que o usuário não poderia optar por cancelar o recurso autoopen.

Uma maneira fácil de escrever o XML é primeiro executar o suplemento e marcar o documento no lado do cliente para gravar o valor e, em seguida, salvar o documento e inspecionar o XML gerado. O Office detectará e fornecerá os valores de atributos apropriados. Você também pode usar a Ferramenta de Produtividade do Open XML SDK para gerar código C# para adicionar programaticamente a marcação com base no XML gerado.

Testar e verificar a abertura de painéis de tarefas

Você pode implantar uma versão de teste do suplemento que abrirá automaticamente um painel de tarefas usando a Implantação Centralizada por meio do Centro de administração do Microsoft 365. O exemplo a seguir mostra como os suplementos são inseridos do catálogo de Implantação Centralizada usando a versão de armazenamento EXCatalog.

<we:webextension xmlns:we="http://schemas.microsoft.com/office/webextensions/webextension/2010/11" id="{52811C31-4593-43B8-A697-EB873422D156}">
    <we:reference id="af8fa5ba-4010-4bcc-9e03-a91ddadf6dd3" version="1.0.0.0" store="EXCatalog" storeType="EXCatalog"/>
    <we:alternateReferences/>
    <we:properties/>
    <we:bindings/>
    <we:snapshot xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"/>
</we:webextension>

Você pode testar o exemplo anterior usando sua assinatura do Microsoft 365 para experimentar a Implantação Centralizada e verificar se o suplemento funciona conforme o esperado. Se você ainda não tiver uma assinatura do Microsoft 365, poderá se qualificar para uma assinatura de desenvolvedor do Microsoft 365 E5 por meio do Programa de Desenvolvedor do Microsoft 365. Para obter detalhes, consulte as Perguntas frequentes. Como alternativa, você pode se inscrever para uma avaliação gratuita de 1 mês ou adquirir um plano do Microsoft 365.

Confira também

• Para obter um exemplo que mostra como usar o recurso de abertura automática, consulte Abrir automaticamente um painel de tarefas com um documento.
• Abrir automaticamente um painel de tarefas quando um suplemento é instalado
• Saiba mais sobre o Programa para Desenvolvedores do Microsoft 365
• Gerenciando opções de confiança para Suplementos do Office