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. Sua solução pode ser executada no Office em várias plataformas, incluindo Windows, Mac, iPad e em um navegador. Fornecemos conjuntos de requisitos que ajudam você a declarar a quais APIs e plataformas seu suplemento dá suporte. Os conjuntos de requisitos são grupos nomeados de membros da API que geralmente têm suporte 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 aplicativo compatível com Suplementos do Office tem seu conjunto usual de plataformas disponíveis. Para obter uma listagem abrangente, consulte Disponibilidade de aplicativos e plataformas de cliente do Office para Suplementos do Office. Para fins desta discussão, vamos nos concentrar no Excel, no Outlook, no PowerPoint e no Word.

Os conjuntos de requisitos multiplataforma estão disponíveis no Windows, Mac e em um navegador. Dependendo dos recursos disponibilizados, um conjunto de requisitos também pode ter suporte no iPad ou em plataformas móveis.

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

Conjuntos de requisitos atuais específicos da plataforma

Atualmente, conjuntos de requisitos específicos da plataforma estão disponíveis no Excel e no Word. O Excel e o Word incluem conjuntos de requisitos somente online e somente desktop. Para obter a lista completa, consulte Conjuntos de requisitos especiais.

Observe 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.

Por que conjuntos de requisitos específicos da plataforma?

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

  1. Disponibilidade de recursos. Alguns recursos não são implementados na interface do usuário dos aplicativos do Office em uma plataforma específica. Dessa forma, a API só pode ser disponibilizada em plataformas compatíveis. Ter esses tipos de APIs em um conjunto de requisitos específico da plataforma significa que os desenvolvedores podem usar essas APIs em seus suplementos. Isso é especialmente útil para casos em que o recurso pode nunca ser implementado em outras plataformas.
  2. Suplementos específicos da plataforma. Os desenvolvedores que têm suplementos focados em uma plataforma específica não precisam esperar que essas APIs sejam implementadas em outras plataformas. Esses desenvolvedores são capazes de incorporar essas APIs em suas soluções e enviar para seus clientes muito mais cedo.
  3. Experiências personalizadas. Os clientes podem usar um aplicativo do Office de forma diferente dependendo da plataforma por vários motivos, como disponibilidade de recursos ou nível de conforto, por exemplo. Digamos que, na versão do Windows, um cliente conclua um conjunto de tarefas, mas em um iPad, ele conclui um conjunto diferente de tarefas. Você pode fazer com que seu suplemento forneça uma experiência personalizada com base nos cenários usuais dos usuários por plataforma.

Para ajudá-lo a decidir se os conjuntos de requisitos específicos da plataforma podem funcionar para você, considere o seguinte.

Promoção de API para conjunto de requisitos de plataforma cruzada

Quando as APIs em um conjunto de requisitos específicos da plataforma têm suporte entre plataformas, elas são adicionadas ao próximo conjunto de requisitos direcionado para lançamento. Mesmo depois que o novo requisito for disponibilizado geralmente, essas APIs ainda permanecem no conjunto de requisitos específicos da plataforma.

Como usar um conjunto de requisitos específico da plataforma

As seções a seguir descrevem onde você pode especificar seu conjunto mínimo de requisitos. Para obter mais informações sobre essas opções, consulte Especificar quais versões e plataformas do Office podem hospedar seu suplemento.

Manifesto

Ao observar um requisito definido na propriedade do manifesto "requirements.capabilities" unificado (ou no elemento Set do manifesto somente do suplemento), você está indicando o conjunto mínimo de APIs de que seu suplemento precisa. Combinado com aplicativos host do Office compatíveis e outras informações, isso determina se o suplemento é ativado ou não em um cliente do Office.

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

Lembre-se de que, no caso em que as APIs se tornem compatíveis com várias plataformas, você precisará atualizar o manifesto do suplemento para adicionar um conjunto de requisitos entre plataformas e remover o conjunto de requisitos específicos da plataforma. Se o suplemento estiver disponível no Microsoft Marketplace, você precisará reenviá-lo para validação.

Dica

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

Código

Outra opção é implementar uma marca de tempo de execução em seu código. Dessa forma, você pode disponibilizar novos recursos para seus clientes nessas plataformas. A marca de tempo de execução também garante que o código específico da plataforma não seja executado em plataformas sem suporte e que os recursos de plataforma cruzada continuem funcionando para seus clientes. O código a seguir é um exemplo que verifica um conjunto de requisitos específico.

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

Sempre que APIs específicas da plataforma se tornarem disponíveis entre plataformas, permita que seus clientes em todas as plataformas com suporte usem esses recursos implementando uma das opções a seguir.

  • Remova a marca de tempo de execução. Mas observe que os clientes de clientes mais antigos do Office, especialmente no Windows, podem encontrar erros se o cliente ainda não der suporte às novas APIs.
  • Atualize o código de tempo de execução para marcar o conjunto de requisitos de plataforma cruzada.

Uma variação é fazer uma marca de tempo de execução para uma API específica. Isso significa que o código encapsulado deve ser executado em todas as plataformas que dão suporte a essa API. Se a API foi lançada pela primeira vez em um conjunto de requisitos específicos da plataforma e depois promovida para um conjunto de plataformas cruzadas, você não precisará atualizar seu código, a menos que tenha feito suposições sobre as plataformas com suporte. 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 Office Store, notifique os clientes sobre qualquer comportamento específico da plataforma.

Detalhes + suporte>Os produtos com suporte na página do Microsoft Marketplace do seu suplemento devem mostrar automaticamente as plataformas com suporte apropriadas com base nos requisitos declarados no manifesto.

No entanto, se o seu suplemento tiver suporte multiplataforma, mas você também implementou comportamentos específicos da plataforma, você deve apontar essas diferenças de recursos na seção Visão geral da página do Microsoft Marketplace do suplemento.

Exceções

A seguir estão as exceções à abordagem descrita.

Conjuntos de requisitos somente online

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

Para marcar se há APIs com suporte apenas nesses conjuntos de requisitos e para evitar que o suplemento tente executar o código em plataformas sem suporte, adicione um 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 em um conjunto de requisitos somente online têm suporte em várias plataformas, elas são adicionadas ao próximo conjunto de requisitos lançado. Depois que o novo conjunto de requisitos é disponibilizado geralmente, essas APIs são removidas do conjunto de requisitos somente online.

Siga as diretrizes na seção Código anterior para ajustar a implementação do suplemento de acordo.

Conjuntos de requisitos de HiddenDocument somente para área de trabalho no Word

É importante observar que, embora os conjuntos de requisitos de HiddenDocument no Word sejam somente da área de trabalho, é inválido especificar um conjunto de requisitos de HiddenDocument no elemento Set do manifesto do suplemento.

Para marcar se há APIs com suporte apenas nesses conjuntos de requisitos e para evitar que o suplemento tente executar o código em plataformas sem suporte, adicione um 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