Adicionar suporte para comandos de suplementos no Outlook em dispositivos móveis

Artigo
09/25/2024

A utilização de comandos de suplementos no Outlook em dispositivos móveis permite que os seus utilizadores acedam à mesma funcionalidade (com algumas limitações) que já têm no Outlook na Web, no Windows (novo e clássico) e no Mac. A adição de suporte para o Outlook Mobile requer a atualização do manifesto do suplemento e, possivelmente, a alteração do código para cenários móveis.

Atualizar o manifesto

O primeiro passo para ativar comandos de suplementos no Outlook Mobile é defini-los no manifesto do suplemento.

Manifesto unificado para o Microsoft 365
Manifesto apenas de suplemento

Na matriz "extensions.ribbons.requirements.formFactors", adicione "mobile" como um item. Quando tiver terminado, a matriz deverá ter o seguinte aspeto.
```
"formFactors": [
    "mobile",
    
]
```
Se o seu suplemento utilizar o modo Participante do Compromisso, como um suplemento que integra um fornecedor de uma aplicação de criação de notas ou gestão de relações com o cliente (CRM), adicione "logEventMeetingDetailsAttendee" à matriz "extensions.ribbons.contexts". Apresentamos um exemplo a seguir.
```
"contexts": [
    "meetingDetailsAttendee",
    "logEventMeetingDetailsAttendee"
],
```
Se o seu suplemento utilizar um fornecedor integrado de reuniões online, adicione "onlineMeetingDetailsOrganizer" à matriz "extensions.ribbons.contexts". Apresentamos um exemplo a seguir.
```
"contexts": [
    "meetingDetailsOrganizer",
    "onlineMeetingDetailsOrganizer"
],
```

Na matriz "extensions.ribbons.tabs", localize o separador com "builtInTabId" de "TabDefault". Adicione uma matriz "customMobileRibbonGroups" subordinada à mesma (como elemento da propriedade "grupos" existente). Dentro desta matriz, crie um objeto e faça o seguinte:

Defina os valores "id" e "label" adequados.
Crie um objeto na matriz "controlos" para representar um botão e configure-o da seguinte forma.
- Defina os valores "id" e "label" adequados. Para garantir que o botão encaixa corretamente no friso, recomendamos que limite a "etiqueta" a 16 carateres.
- Defina "type" como "mobileButton".
- Atribua uma função à propriedade "actionId". Isto deve corresponder ao "ID" do objeto na matriz "extensions.runtimes.actions".
- Certifique-se de que tem os nove ícones necessários.

Apresentamos um exemplo a seguir.

"tabs": [
    {
        "builtInTabId": "TabDefault",
        "groups": [
            <-- non-mobile group objects omitted -->
        ],
        "customMobileRibbonGroups": [
            {
                "id": "mobileApptComposeGroup",
                "label": "Contoso Meeting",
                "controls": [
                    { 
                        "id": "mobileInsertMeetingButton",
                        "label": "Add meeting",
                        "type": "mobileButton",
                        "actionId": "insertContosoMeeting",
                        "icons": [
                            {
                                "scale": 1,
                                "size": 25,
                                "url": "https://contoso.com/assets/icon-25.png"
                            },
                            {
                                "scale": 1,
                                "size": 32,
                                "url": "https://contoso.com/assets/icon-32.png"
                            },
                            {
                                "scale": 1,
                                "size": 48,
                                "url": "https://contoso.com/assets/icon-48.png"
                            },                                
                            {
                                "scale": 2,
                                "size": 25,
                                "url": "https://contoso.com/assets/icon-25.png"
                            },
                            {
                                "scale": 2,
                                "size": 32,
                                "url": "https://contoso.com/assets/icon-32.png"
                            },
                            {
                                "scale": 2,
                                "size": 48,
                                "url": "https://contoso.com/assets/icon-48.png"
                            },                                
                            {
                                "scale": 3,
                                "size": 25,
                                "url": "https://contoso.com/assets/icon-25.png"
                            },
                            {
                                "scale": 3,
                                "size": 32,
                                "url": "https://contoso.com/assets/icon-32.png"
                            },
                            {
                                "scale": 3,
                                "size": 48,
                                "url": "https://contoso.com/assets/icon-48.png"
                            }
                        ]
                    }
                ]
            }
        ]
    }
]

O esquema VersionOverrides versão 1.1 define um novo fator forma para dispositivos móveis, o MobileFormFactor.

Esse elemento contém todas as informações para carregar o suplemento em clientes móveis. Isso permite que você defina elementos de interface completamente diferentes e arquivos JavaScript para a experiência móvel.

O exemplo seguinte mostra um botão de painel de tarefas único num <elemento MobileFormFactor> .

<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
  ...
  <MobileFormFactor>
    <FunctionFile resid="residUILessFunctionFileUrl" />
    <ExtensionPoint xsi:type="MobileMessageReadCommandSurface">
      <Group id="mobileMsgRead">
        <Label resid="groupLabel" />
        <Control xsi:type="MobileButton" id="TaskPaneBtn">
          <Label resid="residTaskPaneButtonName" />
          <Icon xsi:type="bt:MobileIconList">
            <bt:Image size="25" scale="1" resid="tp0icon" />
            <bt:Image size="25" scale="2" resid="tp0icon" />
            <bt:Image size="25" scale="3" resid="tp0icon" />

            <bt:Image size="32" scale="1" resid="tp0icon" />
            <bt:Image size="32" scale="2" resid="tp0icon" />
            <bt:Image size="32" scale="3" resid="tp0icon" />

            <bt:Image size="48" scale="1" resid="tp0icon" />
            <bt:Image size="48" scale="2" resid="tp0icon" />
            <bt:Image size="48" scale="3" resid="tp0icon" />
          </Icon>
          <Action xsi:type="ShowTaskpane">
            <SourceLocation resid="residTaskpaneUrl" />
          </Action>
        </Control>
      </Group>
    </ExtensionPoint>
  </MobileFormFactor>
  ...
</VersionOverrides>

Isso é muito semelhante aos elementos que aparecem em um elemento DesktopFormFactor, com algumas diferenças importantes.

O elemento OfficeTab não é utilizado.
O elemento ExtensionPoint deve ter apenas um elemento filho. Se o seu suplemento implementar o ponto de extensão MobileOnlineMeetingCommandSurface ou MobileLogEventAppointmentAttendee , tem de incluir um elemento Subordinado de controlo . Se o suplemento implementar o ponto de extensão MobileMessageReadCommandSurface , tem de incluir um elemento subordinado de Grupo que contenha vários <elementos de Controlo> .
Não existe nenhum Menu tipo equivalente para o <elemento Controlo> .
O elemento Supertip não é utilizado.
Os tamanhos de ícone obrigatórios são diferentes. Suplementos móveis devem, no mínimo, dar suporte a ícones de 25 x 25, 32 x 32 e 48 x 48 pixels. Para obter mais informações, veja Requisitos adicionais para fatores de forma móvel.

Considerações sobre código

Criar um suplemento para o Mobile traz algumas considerações adicionais.

Usar REST em vez de Serviços Web do Exchange

O método Office.context.mailbox.makeEwsRequestAsync não é suportado no Outlook mobile. Os suplementos devem preferir obter as informações da API Office.js sempre que possível. Se os suplementos exigem informações que não são expostas pela API Office.js devem usar as APIs REST do Outlook para acessar as caixas de correio do usuário.

O conjunto de requisitos da caixa de correio 1.5 introduziu uma nova versão do Office.context.mailbox.getCallbackTokenAsync que pode pedir um token de acesso compatível com as APIs REST e uma nova propriedade Office.context.mailbox.restUrl que pode ser utilizada para encontrar o ponto final da API REST para o utilizador.

Pinçar e zoom

Por predefinição, os utilizadores podem utilizar o gesto de "aproximar os dedos" para ampliar os painéis de tarefas. Se isto não fizer sentido para o seu cenário, certifique-se de que desativa o zoom de aproximar os dedos no HTML.

Fechar painéis de tarefas

No Outlook mobile, os painéis de tarefas ocupam todo o ecrã e, por predefinição, exigem que o utilizador os feche para regressar à mensagem. Considere utilizar o método Office.context.ui.closeContainer para fechar o painel de tarefas quando o seu cenário estiver concluído.

Modo de redação e compromissos

Atualmente, os suplementos no Outlook Mobile só suportam a ativação ao ler mensagens. Os suplementos não são ativados ao compor mensagens ou ao visualizar ou compor compromissos. No entanto, existem algumas exceções.

Os suplementos integrados do fornecedor de reuniões online são ativados no modo Organizador de Compromissos. Para obter mais informações sobre esta exceção (incluindo as APIs disponíveis), consulte Criar um suplemento móvel do Outlook para um fornecedor de reuniões online.
Os suplementos que registam notas de compromisso e outros detalhes para a gestão de relações com os clientes (CRM) ou os serviços de tomada de notas são ativados no modo Participante do Compromisso. Para obter mais informações sobre esta exceção (incluindo as APIs disponíveis), veja Registar notas de compromisso para uma aplicação externa em suplementos móveis do Outlook.
Os suplementos baseados em eventos são ativados quando o OnNewMessageCompose evento ocorre. Para obter mais informações sobre esta exceção (incluindo APIs suportadas adicionais), veja Implementar ativação baseada em eventos em suplementos móveis do Outlook.

APIs suportadas

Apesar de o Outlook mobile suportar o requisito de Caixa de Correio definido como 1.5, agora pode implementar APIs adicionais a partir de conjuntos de requisitos posteriores para expandir ainda mais a capacidade do seu suplemento no Outlook Mobile. Para obter orientações sobre as APIs que pode implementar no seu suplemento móvel, consulte ApIs JavaScript do Outlook suportadas no Outlook em dispositivos móveis.

Partilhar via