Especificar os requisitos do Suplemento do Office no manifesto unificado do Microsoft 365
Existem várias propriedades de "requisitos" no manifesto unificado do Microsoft 365. A propriedade extensions.requirements controla as aplicações e versões do Office nas quais o suplemento pode ser instalado. Outras propriedades de "requisitos" são utilizadas para suprimir seletivamente algumas funcionalidades de um suplemento em aplicações ou versões específicas do Office em que essas funcionalidades seriam desnecessárias ou não suportadas. Para obter mais informações, veja Funcionalidades de filtro.
extensions.requirements
A propriedade "extensions.requirements" especifica os âmbitos, os fatores de formulário e os conjuntos de requisitos dos Suplementos do Microsoft 365. Se a versão do Microsoft 365 não suportar os requisitos especificados, a extensão não estará disponível para instalação. Os utilizadores não o verão na IU do Office para procurar e instalar suplementos. Alguns exemplos:
- Se a propriedade "requirements.capabilities.name" estiver definida como "Caixa de Correio" e "requirements.capabilities.minVersion" como "1.10", o suplemento não é instalável em versões mais antigas do Office que não suportam conjuntos de requisitos da Caixa de Correio superiores à versão 1.9.
- Se "requirements.scopes" estiver definido como "mail", o suplemento só pode ser instalado no Outlook.
- Se "requirements.formFactors" estiver definido como apenas "ambiente de trabalho", o suplemento não é instalável no Office em execução num dispositivo móvel.
Pode ter mais do que um objeto de capacidade. O exemplo seguinte mostra como garantir que um suplemento é instalável apenas em versões do Office que suportam dois conjuntos de requisitos diferentes e não em dispositivos móveis.
"extensions": [
...
"requirements": {
"capabilities": [
{
"name": "Mailbox",
"minVersion": "1.10"
},
{
"name": "DialogAPI",
"minVersion": "1.2"
}
],
"formFactors": [
"desktop"
]
}
]
Filtrar funcionalidades
As propriedades "requisitos" em objetos descendentes de "extensões" são utilizadas para bloquear algumas funcionalidades de um suplemento, permitindo ainda a instalação do suplemento. A implementação desta filtragem é feita na origem da instalação, como o AppSource ou o Administração Microsoft 365 Center. Se a versão do Office não suportar os requisitos especificados para a funcionalidade, o nó JSON da funcionalidade será removido do manifesto antes de ser instalado na aplicação do Office.
extensions.alternates.requirements
A propriedade "extensions.alternates" permite que os programadores de suplementos façam o seguinte:
- Mantenha uma versão de um suplemento criado numa plataforma de extensibilidade mais antiga (como suplementos COM ou VSTO) ou utilizando o manifesto apenas de suplemento, além da versão que utiliza o manifesto unificado.
- Oculte ou dê preferência à versão que utiliza a tecnologia mais antiga.
- Especifique os ícones necessários para tornar a versão de manifesto unificada do suplemento instalável em versões do Office que não suportam diretamente o manifesto unificado.
Observação
Os Suplementos do Office que utilizam o manifesto unificado do Microsoft 365 são diretamente suportados no Office na Web, no novo Outlook no Windows e no Office no Windows ligado a uma subscrição do Microsoft 365, Versão 2304 (Compilação 16320.00000) ou posterior.
Quando o pacote de aplicação que contém o manifesto unificado é implementado no AppSource ou no Centro de Administração Microsoft 365, é gerado um manifesto apenas de suplemento a partir do manifesto unificado e armazenado. Este manifesto apenas de suplemento permite que o suplemento seja instalado em plataformas que não suportam diretamente o manifesto unificado, incluindo o Office no Mac, o Office em dispositivos móveis, versões de subscrição do Office no Windows anteriores à 2304 (Compilação 16320.00000) e versões perpétuas do Office no Windows.
Para obter mais informações, consulte Gerir um manifesto unificado e uma versão de manifesto apenas de suplemento do seu Suplemento do Office.
A subpropriedade "requisitos" de "extensions.alternates" para aplicar seletivamente os subpropriedades "ocultar" ou "preferir" apenas quando determinados requisitos são cumpridos.
Por exemplo, suponha que pretende ocultar (da IU do Office para instalar suplementos) uma versão mais antiga do seu suplemento, mas apenas nas versões do Office que suportam o conjunto de requisitos da Caixa de Correio 1.10 . Pode fazê-lo com marcações semelhantes às seguintes:
"extensions": [
...
{
...
"alternates": [
...
{
...
"hide": {
"storeOfficeAddin": {
"officeAddinId": "b5a2794d-4aa5-4023-a84b-c60a3cbd33d4",
"assetId": "WA999999999"
}
},
"requirements": {
"capabilities": [
{
"name": "Mailbox",
"minVersion": "1.10"
}
]
}
}
]
}
]
extensions.autoRunEvents.requirements
A propriedade "extensions.autoRunEvents" configura um suplemento para executar automaticamente o código especificado em resposta a eventos especificados. A subpropriedade "requisitos" pode ser utilizada para bloquear este comportamento em algumas versões do Office.
Por exemplo, suponha que um suplemento do Outlook está configurado para iniciar automaticamente em resposta ao evento OnMailSend e suponha que o código na função que é executada requer o conjunto de requisitos da Caixa de Correio 1.13 . No entanto, o suplemento tem outras funcionalidades que seriam úteis nas versões do Office que suportam apenas a versão 1.12. Para garantir que o suplemento é instalável em versões que suportam a versão 1.12, um programador pode definir a propriedade "extensions.requirements.capabilities" para o conjunto de requisitos Caixa de Correio 1.12 em vez de 1.13. No entanto, para bloquear a funcionalidade de início automático em versões que não suportam a versão 1.13, o programador pode adicionar uma propriedade "extensions.autoRunEvents.requirements.capabilities" que especifica a Caixa de Correio 1.13. Apresentamos um exemplo a seguir.
"extensions": [
...
{
...
"autoRunEvents": [
...
{
...
"events": {
"type": "OnMailSend",
"actionId": "logOutgoingEmail",
"options": {
"sendMode": "promptUser"
}
},
"requirements": {
"capabilities": [
{
"name": "Mailbox",
"minVersion": "1.13"
}
]
}
}
]
}
]
extensions.contextMenus.requirements
A propriedade "extensions.contextMenus" configura os menus de contexto do suplemento. Um menu de contexto é um menu de atalho que é apresentado quando clica com o botão direito do rato (ou seleciona sem soltar) na IU do Office. A subpropriedade "requisitos" só pode ser utilizada para permitir menus de contexto quando determinados requisitos são cumpridos.
Por exemplo, suponha que pretende mostrar menus de contexto apenas em versões do Excel que suportam o conjunto de requisitos AddinCommands 1.1. Pode fazê-lo com marcações semelhantes às seguintes:
"extensions": [
...
{
...
"contextMenus": [
...
{
// Insert details of the context menu configuration here.
"requirements": {
"scopes": [
"workbook"
],
"capabilities": [
{
"name": "AddinCommands",
"minVersion": "1.1"
}
]
}
}
]
}
]
extensions.ribbons.requirements
A propriedade "extensions.ribbons" é utilizada para personalizar o friso da aplicação do Office quando o suplemento está instalado. A subpropriedade "requisitos" pode ser utilizada para impedir as personalizações em algumas versões do Office.
Por exemplo, suponha que um suplemento do Outlook está configurado para adicionar um botão personalizado ao friso e o botão executa uma função que utiliza código introduzido no conjunto de requisitos da Caixa de Correio 1.9 . No entanto, o suplemento tem outras funcionalidades que seriam úteis em versões do Office que só suportam a versão 1.8. Para garantir que o suplemento é instalável em versões que suportam a versão 1.8, um programador pode definir a propriedade "extensions.requirements.capabilities" para o requisito definido como Caixa de Correio 1.8 em vez de 1.9. No entanto, para bloquear a apresentação do botão personalizado no friso em versões que não suportam a versão 1.9, o programador pode adicionar uma propriedade "extensions.ribbons.requirements.capabilities" que especifica a Caixa de Correio 1.9. Apresentamos um exemplo a seguir. Para obter detalhes sobre a configuração personalizada do friso, consulte Criar comandos de suplementos com o manifesto unificado para o Microsoft 365.
"extensions": [
...
{
...
"ribbons": [
...
{
// Insert details of the ribbon configuration here.
"requirements": {
"capabilities": [
{
"name": "Mailbox",
"minVersion": "1.9"
}
]
}
}
]
}
]
extensions.runtimes.requirements
A propriedade "extensions.runtimes" configura os conjuntos de runtimes e ações que cada ponto de extensão pode utilizar. Para obter mais informações sobre a utilização, veja Criar comandos de suplementos, Configurar o runtime para um painel de tarefas e Configurar o runtime para o comando de função. Para obter mais informações sobre runtimes em suplementos do Office, consulte Runtimes nos Suplementos do Office.
A subpropriedade "requisitos" pode ser utilizada para impedir que o runtime seja incluído em versões do Office ou em aplicações do Office onde não seria utilizado.
O exemplo anterior apresentado em extensions.autoRunEvents.requirements mostra como bloquear a funcionalidade de início automático em versões que não suportam todo o código na logOutgoingEmail função, que inclui código que requer a Caixa de Correio 1.13. Suponha que, nesse mesmo cenário, o objeto "runtime" configurado para suportar a ação "logOutgoingEmail" não está configurado para suportar qualquer outra ação. Nesse caso, o programador deve bloquear o objeto de runtime em versões que não suportam a Caixa de Correio 1.13 , uma vez que nunca seria utilizado. Apresentamos um exemplo a seguir. Para obter detalhes sobre a configuração do runtime, consulte Criar comandos de suplementos com o manifesto unificado para o Microsoft 365.
"extensions": [
...
{
...
"runtimes": [
...
{
// Insert details of the runtime configuration here.
"requirements": {
"capabilities": [
{
"name": "Mailbox",
"minVersion": "1.13"
}
]
}
}
]
}
]
Da mesma forma, para o exemplo em extensions.ribbons.requirements, se a ação ligada ao botão personalizado for a única ação configurada num objeto de runtime, esse objeto de runtime deve ser bloqueado nas mesmas circunstâncias em que o objeto do friso está bloqueado.