Abrir automaticamente um painel de tarefas com um documento
Pode utilizar comandos de suplementos no seu Suplemento do Office para expandir a IU do Office ao adicionar botões ao friso da aplicação 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. Pode utilizar a funcionalidade de abertura automática do painel de tarefas, introduzida no conjunto de requisitos AddInCommands 1.1, para abrir automaticamente um painel de tarefas quando o seu cenário o exigir.
Observação
Para configurar um painel de tarefas para abrir imediatamente quando o suplemento é instalado, mas não necessariamente sempre que o documento é aberto mais tarde, consulte Abrir automaticamente um painel de tarefas quando um suplemento é instalado.
De que forma o recurso autoopen é diferente da inserção de um painel de tarefas?
Quando um utilizador inicia suplementos que não utilizam comandos de suplementos, os suplementos são inseridos no documento e persistem nesse documento. Como resultado, quando outros utilizadores abrem o documento, é-lhes pedido que instalem o suplemento e o painel de tarefas é aberto. O desafio deste modelo é que, em muitos casos, os utilizadores 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
A funcionalidade de abrir automaticamente é atualmente suportada nos seguintes produtos e plataformas.
| Produtos | Plataformas |
|---|---|
|
Plataformas suportadas para todos os produtos suportados:
|
Práticas recomendadas
Aplique as seguintes melhores práticas quando utilizar a funcionalidade de abrir automaticamente.
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.
Utilize a deteção do conjunto de requisitos para determinar se a funcionalidade de abertura automática está disponível e indique um comportamento de contingência se não estiver.
Não use o recurso autoopen para aumentar artificialmente o uso do seu suplemento. Se não fizer sentido que o seu suplemento abra automaticamente com determinados documentos, esta funcionalidade pode irritar os utilizadores.
Observação
Se a Microsoft detectar abuso do recurso autoopen, seu suplemento poderá ser rejeitado no AppSource.
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 a funcionalidade de abrir automaticamente
- Especifique o painel de tarefas a ser aberto automaticamente.
- Marque o documento para abrir o painel de tarefas automaticamente.
Importante
O painel que designar para abrir automaticamente só será aberto se o suplemento já estiver instalado no dispositivo do utilizador. Se o utilizador não tiver o suplemento instalado quando abrir um documento, a funcionalidade de abertura automática não funcionará e a definição será ignorada. Se também precisar que o suplemento seja distribuído com o documento, tem de definir a propriedade de visibilidade como 1; isto só pode ser feito com o OpenXML, um exemplo é fornecido mais à frente neste artigo.
Etapa 1: especificar o painel de tarefas que será aberto
Para especificar o painel de tarefas que será aberto automaticamente, defina o valor TaskpaneId para Office.AutoShowTaskpaneWithDocument. Você só pode definir esse valor em um painel de tarefas. Se você definir esse valor em vários painéis de tarefas, a primeira ocorrência do valor será reconhecida e as outras serão ignoradas.
O exemplo a seguir mostra o valor TaskPaneId configurado para 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
Utilize o método Office.js settings.set para definir Office.AutoShowTaskpaneWithDocumenttruecomo , conforme mostrado no exemplo seguinte.
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 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 AppSource 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.
storeType valor |
id valor |
store valor |
version valor |
|---|---|---|---|
| OMEX (AppSource) | O ID do recurso do AppSource do suplemento (veja Nota). | A localidade do AppSource, por exemplo, "pt-br". | A versão no catálogo do AppSource (veja Nota). |
| WOPICatalog (anfitriões WOPI parceiros) | O ID do recurso do AppSource do suplemento (veja Nota). | "wopicatalog". Utilize este valor para suplementos publicados na Origem da Aplicação e instalados em anfitriões WOPI. Para obter mais informações, consulte Integrar com o Office Online. | A versão no manifesto do suplemento. |
| FileSystem (um compartilhamento de rede) | O GUID do suplemento no manifesto do suplemento. | O caminho da partilha de rede; por exemplo, "\\MyComputer\MySharedFolder". | A versão no manifesto do suplemento. |
| EXCatalog (implantação por meio do servidor Exchange) | O GUID do suplemento no manifesto do suplemento. | "EXCatalog". A linha EXCatalog é a linha a utilizar com suplementos que utilizam a Implementação Centralizada no Centro de administração do Microsoft 365. | A versão no manifesto do suplemento. |
| Registro (registro de sistema) | O GUID do suplemento no manifesto do suplemento. | "developer" | A versão no manifesto do suplemento. |
Observação
Para localizar a ID de ativos e a versão de um suplemento no AppSource, vá para a página inicial do suplemento no AppSource. A ID de ativo aparece na barra de endereços no navegador. A versão aparece na seção Detalhes da página.
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.
Observação
Se quiser distribuir seu suplemento com o documento, para que os usuários sejam solicitados a instalá-lo, você deverá definir a propriedade de visibilidade para 1. Isso só pode ser feito pelo Open XML.
Uma forma fácil de escrever o XML é primeiro executar o seu suplemento e etiquetar o documento no lado do cliente para escrever o valor e, em seguida, guardar o documento e inspecionar o XML gerado. O Office irá detetar e fornecer os valores de atributo adequados. Também pode utilizar a Open XML SDK Productivity Tool para gerar código C# para adicionar programaticamente a marcação com base no XML que gerar.
Testar e verificar a abertura de painéis de tarefas
Pode implementar uma versão de teste do suplemento que irá abrir automaticamente um painel de tarefas com a Implementação Centralizada através 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>
Pode testar o exemplo anterior com a sua subscrição do Microsoft 365 para experimentar a Implementação Centralizada e verificar se o suplemento funciona conforme esperado. Se ainda não tiver uma subscrição do Microsoft 365, poderá qualificar-se para uma subscrição de programador Microsoft 365 E5 através do Programa para Programadores do Microsoft 365. Para obter detalhes, consulte as FAQ. Em alternativa, pode inscrever-se numa avaliação gratuita de um mês ou comprar um plano do Microsoft 365.
Confira também
- Para obter um exemplo que lhe mostra como utilizar a funcionalidade 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