Compartilhar via

Compreender os conjuntos de requisitos específicos da plataforma

A plataforma de suplementos do Office permite criar soluções que estendem os aplicativos do Office e interagem com conteúdo nos documentos do Office. A sua solução pode ser executada no Office em várias plataformas, incluindo Windows, Mac, iPad e num browser. Fornecemos conjuntos de requisitos que o ajudam a declarar que APIs e plataformas o seu suplemento suporta. Os conjuntos de requisitos são grupos nomeados de membros da API que normalmente são suportados em todas as plataformas disponíveis. No entanto, com conjuntos de requisitos específicos da plataforma, as APIs são implementadas e disponibilizadas primeiro nas plataformas de destino.

Cada aplicação que suporta Suplementos do Office tem o seu conjunto habitual de plataformas disponíveis. Para obter uma listagem abrangente, consulte Disponibilidade da plataforma e da aplicação cliente do Office para Suplementos do Office. Para efeitos deste debate, vamos focar-nos no Excel, Outlook, PowerPoint e Word.

Os conjuntos de requisitos entre plataformas estão disponíveis no Windows, Mac e num browser. Dependendo das funcionalidades que estão a ser disponibilizadas, um conjunto de requisitos também pode ser suportado em iPad ou plataformas móveis.

No entanto, os conjuntos de requisitos específicos da plataforma fornecem suporte para um subconjunto das plataformas habituais. Por exemplo, os conjuntos de requisitos apenas online fornecem APIs que só estão disponíveis quando o suplemento é executado num browser. Da mesma forma, os conjuntos de requisitos apenas para ambiente de trabalho fornecem APIs que só podem estar disponíveis quando o suplemento é executado no Windows e Mac. Veja a página de conjunto de requisitos específica para obter suporte de plataforma real.

Conjuntos de requisitos específicos da plataforma atual

Atualmente, os conjuntos de requisitos específicos da plataforma estão disponíveis no Excel e Word. O Excel e Word incluem conjuntos de requisitos apenas online e apenas para ambiente de trabalho. Para obter a lista completa, veja Conjuntos de requisitos especiais.

Tenha em atenção que no Outlook, o comportamento específico da plataforma pode ser encontrado em pontos de extensão. Por exemplo, MobileOnlineMeetingCommandSurface e MobileLogEventAppointmentAttendee só estão disponíveis para suplementos em execução no Outlook no Android e no iOS.

Porquê conjuntos de requisitos específicos da plataforma?

Estamos a fornecer conjuntos de requisitos específicos da plataforma por alguns motivos.

  1. Disponibilidade de recursos. Algumas funcionalidades não são implementadas na IU das aplicações do Office numa determinada plataforma. Como tal, a API só pode ser disponibilizada em plataformas suportadas. Ter estes tipos de APIs num conjunto de requisitos específico da plataforma significa que os programadores podem utilizar essas APIs nos respetivos suplementos. Isto é especialmente útil para casos em que a funcionalidade pode nunca ser implementada noutras plataformas.
  2. Suplementos específicos da plataforma. Os programadores que têm suplementos focados numa determinada plataforma não precisam de esperar que essas APIs sejam implementadas noutras plataformas. Estes programadores são capazes de incorporar essas APIs nas suas soluções e enviar para os seus clientes muito mais cedo.
  3. Experiências personalizadas. Os clientes podem utilizar uma aplicação do Office de forma diferente consoante a plataforma por vários motivos, como a disponibilidade de funcionalidades ou o nível de conforto, por exemplo. Digamos que, na versão do Windows, um cliente conclui um conjunto de tarefas, mas num iPad conclui um conjunto diferente de tarefas. Pode fazer com que o seu suplemento proporcione uma experiência personalizada com base nos cenários habituais dos seus utilizadores por plataforma.

Para o ajudar a decidir se os conjuntos de requisitos específicos da plataforma podem funcionar para si, considere o seguinte.

Conjunto de requisitos de promoção de API para várias plataformas

Quando as APIs num conjunto de requisitos específicos da plataforma são suportadas em várias plataformas, são adicionadas ao próximo conjunto de requisitos direcionado para o lançamento. Mesmo após a disponibilização geral do novo requisito, essas APIs continuam a permanecer no conjunto de requisitos específicos da plataforma.

Como utilizar um conjunto de requisitos específico da plataforma

As secções seguintes descrevem onde pode especificar o seu conjunto de requisitos mínimo. Para obter mais informações sobre estas opções, consulte Especificar que versões e plataformas do Office podem alojar o seu suplemento.

Manifesto

Quando anota um conjunto de requisitos na "requirements.capabilities" propriedade do manifesto unificado (ou o elemento Set do manifesto apenas do suplemento), está a indicar o conjunto mínimo de APIs de que o suplemento precisa. Combinado com aplicações de anfitrião do Office suportadas e outras informações, isto determina se o seu suplemento é ativado num cliente do Office.

Quando declara um conjunto de requisitos específicos da plataforma, o seu suplemento é ativado apenas quando é executado no Office nessa plataforma. Por exemplo, se tiver o requisito wordApiDesktop 1.1 definido no seu manifesto, o seu suplemento só será ativado no Word no Windows e no Mac.

Tenha em atenção que, no caso de as APIs se tornarem suportadas em várias plataformas, terá de atualizar o manifesto do suplemento para adicionar um conjunto de requisitos para várias plataformas e remover o conjunto de requisitos específicos da plataforma. Se o seu suplemento estiver disponível no Microsoft Marketplace, terá de o submeter novamente para validação.

Dica

Para obter informações sobre como o Office interpreta os requisitos, veja Compreender a lógica da configuração de requisitos de API.

Código

Outra opção é implementar um marcar de runtime no seu código. Desta forma, pode disponibilizar novas funcionalidades aos seus clientes nessas plataformas. O runtime marcar também garante que o código específico da plataforma não é executado em plataformas não suportadas e as funcionalidades entre plataformas continuam a funcionar para os seus clientes. O código seguinte é um exemplo que verifica a existência de um conjunto de requisitos específico.

if (Office.context.requirements.isSetSupported("WordApiDesktop", "1.1")) {
   // Any API exclusive to this WordApiDesktop requirement set.
}

Sempre que as APIs específicas da plataforma ficarem disponíveis em várias plataformas, permita que os seus clientes em todas as plataformas suportadas utilizem essas funcionalidades ao implementar uma das seguintes opções.

  • Remova o marcar de runtime. No entanto, tenha em atenção que os clientes em clientes mais antigos do Office, especialmente no Windows, podem encontrar erros se o cliente ainda não suportar as novas APIs.
  • Atualize o código de runtime para marcar para o conjunto de requisitos entre plataformas.

Uma variação é fazer um runtime marcar para uma API específica. Isto significa que o código encapsulado deve ser executado em quaisquer plataformas que suportem essa API. Se a API tiver sido lançada pela primeira vez num conjunto de requisitos específico da plataforma e depois promovida para uma plataforma cruzada, não deverá precisar de atualizar o código, a menos que tenha feito suposições sobre as plataformas suportadas. O código a seguir é um exemplo.

if (Office.context.document.setSelectedDataAsync)
{
    // Run code that uses document.setSelectedDataAsync.
}

Notificar os clientes no Microsoft Marketplace

Se o seu suplemento estiver no Microsoft Marketplace ou na Loja Office, certifique-se de que notifica os clientes sobre qualquer comportamento específico da plataforma.

Detalhes + suporte>Os produtos suportados na página do Microsoft Marketplace do suplemento devem mostrar automaticamente as plataformas suportadas adequadas com base nos requisitos que declarou no manifesto.

No entanto, se o seu suplemento for suportado em várias plataformas, mas também tiver implementado comportamentos específicos da plataforma, deve apontar essas diferenças de funcionalidades na secção Descrição geral na página do Microsoft Marketplace do seu suplemento.

Exceções

Seguem-se exceções à abordagem descrita.

Conjuntos de requisitos apenas online

Um conjunto de requisitos apenas online é um superconjunto do mais recente conjunto de requisitos numerados. Para cada aplicação do Office com um requisito apenas online definido, 1.1 é a única versão. É inválido especificar um conjunto de requisitos apenas online na "requirements.capabilities" propriedade do manifesto unificado (ou o elemento Set do manifesto apenas de suplemento).

Para marcar para APIs que só são suportadas nestes conjuntos de requisitos e para impedir que o suplemento tente executar o código em plataformas não suportadas, adicione código semelhante ao seguinte:

if (Office.context.requirements.isSetSupported("ExcelApiOnline", "1.1")) {
   // Any API exclusive to the ExcelApiOnline requirement set.
}

if (Office.context.requirements.isSetSupported("WordApiOnline", "1.1")) {
   // Any API exclusive to the WordApiOnline requirement set.
}

Quando as APIs num conjunto de requisitos apenas online são suportadas em várias plataformas, são adicionadas ao próximo conjunto de requisitos de lançamento. Após a disponibilização geral do novo conjunto de requisitos, essas APIs são removidas do conjunto de requisitos apenas online.

Siga as orientações na secção Código anterior para ajustar a implementação do suplemento em conformidade.

Conjuntos de requisitos hiddenDocument apenas para ambiente de trabalho no Word

É importante ter em atenção que, embora os conjuntos de requisitos HiddenDocument no Word sejam apenas de ambiente de trabalho, é inválido especificar um requisito HiddenDocument definido no elemento Set do seu manifesto de suplemento.

Para marcar para APIs que só são suportadas nestes conjuntos de requisitos e para impedir que o suplemento tente executar o código em plataformas não suportadas, adicione código semelhante ao seguinte:

if (Office.context.requirements.isSetSupported("WordApiHiddenDocument", "1.5")) {
   // Any API exclusive to this WordApiHiddenDocument requirement set.
}

Confira também

  • Last updated on