Criar separadores contextuais personalizados nos Suplementos do Office

  • Artigo

Um separador contextual é um controlo de separador oculto no friso do Office que é apresentado na linha de separador quando um evento especificado ocorre no documento do Office. Por exemplo, o separador Estrutura da Tabela que aparece no friso do Excel quando uma tabela está selecionada. Pode incluir separadores contextuais personalizados no seu Suplemento do Office e especificar quando estão visíveis ou ocultos ao criar processadores de eventos que alteram a visibilidade. (No entanto, os separadores contextuais personalizados não respondem às alterações de foco.)

Observação

Este artigo pressupõe que está familiarizado com conceitos básicos para comandos de suplementos. Reveja-o se não tiver trabalhado com comandos de suplementos (itens de menu personalizados e botões do friso) recentemente.

Pré-requisitos

Atualmente, os separadores contextuais personalizados só são suportados no Excel e apenas nas seguintes plataformas e compilações.

  • Excel Online
  • Excel no Windows: Versão 2102 (Compilação 13801.20294) e posterior.
  • Excel no Mac: Versão 16.53 (21080600) e posterior.

Além disso, os separadores contextuais personalizados só funcionam em plataformas que suportam os seguintes conjuntos de requisitos. Para obter mais informações sobre os conjuntos de requisitos e como trabalhar com os mesmos, consulte Especificar as aplicações do Office e os requisitos da API.

Dica

Utilize as verificações de runtime no seu código para testar se a combinação de anfitrião e plataforma do utilizador suporta estes conjuntos de requisitos, conforme descrito em Verificações de runtime para o método e suporte do conjunto de requisitos. (A técnica de especificar os conjuntos de requisitos no manifesto, que também é descrito nesse artigo, não funciona atualmente para o RibbonApi 1.2.) Em alternativa, pode implementar uma experiência de IU alternativa quando os separadores contextuais personalizados não são suportados.

Comportamento dos separadores contextuais personalizados

A experiência do utilizador para separadores contextuais personalizados segue o padrão dos separadores contextuais incorporados do Office. Seguem-se os princípios básicos para os separadores contextuais personalizados de colocação.

  • Quando um separador contextual personalizado é visível, é apresentado na extremidade direita do friso.
  • Se um ou mais separadores contextuais incorporados e um ou mais separadores contextuais personalizados de suplementos estiverem visíveis ao mesmo tempo, os separadores contextuais personalizados estarão sempre à direita de todos os separadores contextuais incorporados.
  • Se o seu suplemento tiver mais do que um separador contextual e existirem contextos em que mais do que um é visível, estes são apresentados pela ordem em que são definidos no seu suplemento. (A direção é a mesma direção que o idioma do Office; ou seja, é da esquerda para a direita em idiomas da esquerda para a direita, mas da direita para a esquerda em idiomas da direita para a esquerda.) Consulte Definir os grupos e controlos que aparecem no separador para obter detalhes sobre como os define.
  • Se mais do que um suplemento tiver um separador contextual visível num contexto específico, estes serão apresentados pela ordem pela qual os suplementos foram iniciados.
  • Os separadores contextuais personalizados, ao contrário dos separadores principais personalizados, não são adicionados permanentemente ao friso da aplicação do Office. Só estão presentes em documentos do Office nos quais o seu suplemento está em execução.

Aviso

Atualmente, a utilização de separadores contextuais personalizados pode impedir o utilizador de anular as ações anteriores do Excel. Este é um problema conhecido (veja este tópico do GitHub) e está sob investigação ativa.

Principais passos para incluir um separador contextual num suplemento

Seguem-se os principais passos para incluir um separador contextual personalizado num suplemento.

  1. Configure o suplemento para utilizar um runtime partilhado.
  2. Especifique os ícones do separador contextual.
  3. Defina os grupos e controlos que aparecem no separador.
  4. Registe o separador contextual no Office.
  5. Especifique as circunstâncias em que o separador estará visível.

Configurar o suplemento para utilizar um runtime partilhado

Adicionar separadores contextuais personalizados requer que o suplemento utilize o runtime partilhado. Para obter mais informações, veja Configurar um suplemento para utilizar um runtime partilhado.

Especifique os ícones do separador contextual

Antes de poder personalizar o separador contextual, primeiro tem de especificar os ícones que serão apresentados no mesmo com um elemento Imagem na secção Recursos do manifesto do suplemento. Cada ícone tem de ter, pelo menos, três tamanhos: 16x16 px, 32x32 px e 80x80 px.

Apresentamos um exemplo a seguir.

<Resources>
    <bt:Images>
        <bt:Image id="contextual-tab-icon-16" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/Group16x16.png"/>
        <bt:Image id="contextual-tab-icon-32" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/Group32x32.png"/>
        <bt:Image id="contextual-tab-icon-80" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/Group80x80.png"/>
        <bt:Image id="contextual-button-icon-16" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton16x16.png"/>
        <bt:Image id="contextual-button-icon-32" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton32x32.png"/>
        <bt:Image id="contextual-button-icon-80" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton80x80.png"/>
    </bt:Images>
    ...
</Resources>

Importante

Quando mover o suplemento do desenvolvimento para a produção, lembre-se de atualizar os URLs no seu manifesto conforme necessário (como alterar o domínio de localhost para contoso.com).

Definir os grupos e controlos que aparecem no separador

Ao contrário dos separadores principais personalizados, que são definidos com XML no manifesto, os separadores contextuais personalizados são definidos no runtime com um blob JSON. O código analisa o blob num objeto JavaScript e, em seguida, transmite o objeto para o método Office.ribbon.requestCreateControls . Os separadores contextuais personalizados só estão presentes em documentos nos quais o suplemento está atualmente em execução. Isto é diferente dos separadores principais personalizados que são adicionados ao friso da aplicação do Office quando o suplemento é instalado e permanecem presentes quando outro documento é aberto. Além disso, o requestCreateControls método pode ser executado apenas uma vez numa sessão do seu suplemento. Se for chamado novamente, é gerado um erro.

Observação

A estrutura das propriedades e subpropriedades do blob JSON (e os nomes das chaves) é aproximadamente paralela à estrutura do elemento CustomTab e aos respetivos elementos descendentes no XML do manifesto.

Vamos construir um exemplo de um blob JSON de separadores contextuais passo a passo. O esquema completo do separador contextual JSON está em dynamic-ribbon.schema.json. Se estiver a trabalhar no Visual Studio Code, pode utilizar este ficheiro para obter o IntelliSense e validar o JSON. Para obter mais informações, consulte Editar JSON com Visual Studio Code - esquemas e definições JSON.

  1. Comece por criar uma cadeia JSON com duas propriedades de matriz com o nome actions e tabs. A actions matriz é uma especificação de todas as funções que podem ser executadas por controlos no separador contextual. A tabs matriz define um ou mais separadores contextuais, até um máximo de 20.

    '{
  "actions": [

  ],
  "tabs": [

  ]
}'

  2. Este exemplo simples de um separador contextual terá apenas um único botão e, portanto, apenas uma única ação. Adicione o seguinte como o único membro da actions matriz. Acerca desta marcação, tenha em atenção:

    • As id propriedades e type são obrigatórias.
    • O valor de type pode ser "ExecuteFunction" ou "ShowTaskpane".
    • A functionName propriedade só é utilizada quando o valor de type é ExecuteFunction. É o nome de uma função definida no FunctionFile. Para obter mais informações sobre o FunctionFile, veja Conceitos básicos para comandos de suplementos.
    • Num passo posterior, irá mapear esta ação para um botão no separador contextual.
    {
  "id": "executeWriteData",
  "type": "ExecuteFunction",
  "functionName": "writeData"
}

  3. Adicione o seguinte como o único membro da tabs matriz. Acerca desta marcação, tenha em atenção:

    • A propriedade id é obrigatória. Utilize um ID breve e descritivo que seja exclusivo entre todos os separadores contextuais no seu suplemento.
    • A propriedade label é obrigatória. É uma cadeia simples de utilizar para servir como a etiqueta do separador contextual.
    • A propriedade groups é obrigatória. Define os grupos de controlos que serão apresentados no separador. Deve ter pelo menos um membro e não mais de 20. (Também existem limites no número de controlos que pode ter num separador contextual personalizado e isso também irá restringir o número de grupos que tem. Veja o passo seguinte para obter mais informações.)

    Observação

    O objeto de separador também pode ter uma propriedade opcional visible que especifica se o separador está visível imediatamente quando o suplemento é iniciado. Uma vez que os separadores contextuais são normalmente ocultados até que um evento do utilizador acione a visibilidade (como o utilizador que seleciona uma entidade de algum tipo no documento), a visible propriedade é predefinida para false quando não está presente. Numa secção posterior, mostramos como definir a propriedade como true em resposta a um evento.

    {
  "id": "CtxTab1",
  "label": "Contoso Data",
  "groups": [

  ]
}

  4. No exemplo contínuo simples, o separador contextual tem apenas um único grupo. Adicione o seguinte como o único membro da groups matriz. Acerca desta marcação, tenha em atenção:

    • Todas as propriedades são necessárias.
    • A id propriedade tem de ser exclusiva entre todos os grupos no manifesto. Utilize um ID breve e descritivo com até 125 carateres.
    • O label é uma cadeia amigável para o utilizador para servir como a etiqueta do grupo.
    • O icon valor da propriedade é uma matriz de objetos que especifica os ícones que o grupo terá no friso, dependendo do tamanho do friso e da janela da aplicação do Office.
    • O controls valor da propriedade é uma matriz de objetos que especifica os botões e menus no grupo. Deve haver pelo menos um.

    Importante

    O número total de controlos no separador inteiro não pode ser superior a 20. Por exemplo, pode ter 3 grupos com 6 controlos cada e um quarto grupo com 2 controlos, mas não pode ter 4 grupos com 6 controlos cada.

    {
    "id": "CustomGroup111",
    "label": "Insertion",
    "icon": [

    ],
    "controls": [

    ]
}

  5. Cada grupo tem de ter um ícone de, pelo menos, três tamanhos: 16x16 px, 32x32 px e 80x80 px. Opcionalmente, também pode ter ícones de tamanhos 20x20 px, 24x24 px, 40x40 px, 48x48 px e 64x64 px. O Office decide qual o ícone a utilizar com base no tamanho do friso e na janela da aplicação do Office. Adicione os seguintes objetos à matriz de ícones. (Se os tamanhos da janela e do friso forem suficientemente grandes para que pelo menos um dos controlos do grupo seja apresentado, não será apresentado nenhum ícone de grupo. Por exemplo, watch o grupo Estilos no friso Word à medida que encolhe e expande a janela de Word.) Acerca desta marcação, tenha em atenção:

    • Ambas as propriedades são necessárias.
    • A size unidade de propriedade da medida é de píxeis. Os ícones são sempre quadrados, pelo que o número tem a altura e a largura.
    • A sourceLocation propriedade especifica o URL completo para o ícone. O respetivo valor tem de corresponder ao URL especificado no <elemento Imagem> da <secção Recursos> do seu manifesto (consulte Especificar os ícones do separador contextual).

    Importante

    Tal como normalmente tem de alterar os URLs no manifesto do suplemento quando passa do desenvolvimento para a produção, também tem de alterar os URLs nos separadores contextuais JSON.

    {
    "size": 16,
    "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group16x16.png"
},
{
    "size": 32,
    "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group32x32.png"
},
{
    "size": 80,
    "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group80x80.png"
}

  6. No nosso exemplo contínuo simples, o grupo tem apenas um único botão. Adicione o seguinte objeto como o único membro da controls matriz. Acerca desta marcação, tenha em atenção:

    • Todas as propriedades, exceto enabled, são necessárias.
    • type especifica o tipo de controlo. Os valores podem ser "Botão", "Menu" ou "MobileButton".
    • id pode ter até 125 carateres.
    • actionId tem de ser o ID de uma ação definida na actions matriz. (Consulte o passo 1 desta secção.)
    • label é uma cadeia simples de utilizar para servir como a etiqueta do botão.
    • superTip representa uma forma avançada de sugestão de ferramenta. title As propriedades e description são necessárias.
    • icon especifica os ícones do botão. As observações anteriores sobre o ícone de grupo também se aplicam aqui.
    • enabled (opcional) especifica se o botão está ativado quando o separador contextual é apresentado. A predefinição se não estiver presente é true.
    {
    "type": "Button",
    "id": "CtxBt112",
    "actionId": "executeWriteData",
    "enabled": false,
    "label": "Write Data",
    "superTip": {
        "title": "Data Insertion",
        "description": "Use this button to insert data into the document."
    },
    "icon": [
        {
            "size": 16,
            "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton16x16.png"
        },
        {
            "size": 32,
            "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton32x32.png"
        },
        {
            "size": 80,
            "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton80x80.png"
        }
    ]
}

Segue-se o exemplo completo do blob JSON.

`{
  "actions": [
    {
      "id": "executeWriteData",
      "type": "ExecuteFunction",
      "functionName": "writeData"
    }
  ],
  "tabs": [
    {
      "id": "CtxTab1",
      "label": "Contoso Data",
      "groups": [
        {
          "id": "CustomGroup111",
          "label": "Insertion",
          "icon": [
            {
                "size": 16,
                "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group16x16.png"
            },
            {
                "size": 32,
                "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group32x32.png"
            },
            {
                "size": 80,
                "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group80x80.png"
            }
          ],
          "controls": [
            {
                "type": "Button",
                "id": "CtxBt112",
                "actionId": "executeWriteData",
                "enabled": false,
                "label": "Write Data",
                "superTip": {
                    "title": "Data Insertion",
                    "description": "Use this button to insert data into the document."
                },
                "icon": [
                    {
                        "size": 16,
                        "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton16x16.png"
                    },
                    {
                        "size": 32,
                        "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton32x32.png"
                    },
                    {
                        "size": 80,
                        "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton80x80.png"
                    }
                ]
            }
          ]
        }
      ]
    }
  ]
}`

Registar o separador contextual no Office com requestCreateControls

O separador contextual é registado no Office ao chamar o método Office.ribbon.requestCreateControls . Normalmente, isto é feito na função atribuída ou Office.initialize com a Office.onReady função . Para obter mais informações sobre estas funções e inicializar o suplemento, consulte Inicializar o suplemento do Office. No entanto, pode chamar o método em qualquer altura após a inicialização.

Importante

O requestCreateControls método pode ser chamado apenas uma vez numa determinada sessão de um suplemento. É gerado um erro se for chamado novamente.

Apresentamos um exemplo a seguir. Tenha em atenção que a cadeia JSON tem de ser convertida num objeto JavaScript com o JSON.parse método antes de poder ser transmitida para uma função JavaScript.

Office.onReady(async () => {
    const contextualTabJSON = ` ... `; // Assign the JSON string such as the one at the end of the preceding section.
    const contextualTab = JSON.parse(contextualTabJSON);
    await Office.ribbon.requestCreateControls(contextualTab);
});

Especifique os contextos em que o separador será visível com requestUpdate

Normalmente, deve ser apresentado um separador contextual personalizado quando um evento iniciado pelo utilizador altera o contexto do suplemento. Considere um cenário em que o separador deve estar visível quando, e apenas quando, um gráfico (na folha de cálculo predefinida de um livro do Excel) está ativado.

Comece por atribuir processadores. Isto é normalmente feito na Office.onReady função como no exemplo seguinte, que atribui processadores (criados num passo posterior) aos onActivated eventos e onDeactivated de todos os gráficos na folha de cálculo.

Office.onReady(async () => {
    const contextualTabJSON = ` ... `; // Assign the JSON string.
    const contextualTab = JSON.parse(contextualTabJSON);
    await Office.ribbon.requestCreateControls(contextualTab);

    await Excel.run(context => {
        const charts = context.workbook.worksheets
            .getActiveWorksheet()
            .charts;
        charts.onActivated.add(showDataTab);
        charts.onDeactivated.add(hideDataTab);
        return context.sync();
    });
});

Em seguida, defina os processadores. Segue-se um exemplo simples de um showDataTab, mas veja Handling the HostRestartNeeded error later neste artigo para obter uma versão mais robusta da função. Sobre este código, observe:

  • O Office controla quando atualiza o estado da faixa de opções. O método Office.ribbon.requestUpdate coloca em fila um pedido de atualização. O método irá resolve o Promise objeto assim que colocar o pedido em fila, não quando o friso for realmente atualizado.
  • O parâmetro para o requestUpdate método é um objeto RibbonUpdaterData que (1) especifica o separador pelo respetivo ID exatamente conforme especificado no JSON e (2) especifica a visibilidade do separador.
  • Se tiver mais do que um separador contextual personalizado que deve estar visível no mesmo contexto, basta adicionar objetos de separador adicionais à tabs matriz.
async function showDataTab() {
    await Office.ribbon.requestUpdate({
        tabs: [
            {
                id: "CtxTab1",
                visible: true
            }
        ]});
}

O processador para ocultar o separador é quase idêntico, exceto que define a visible propriedade novamente como false.

A biblioteca JavaScript do Office também fornece várias interfaces (tipos) para facilitar a construção doRibbonUpdateData objeto. Segue-se a showDataTab função em TypeScript e utiliza estes tipos.

const showDataTab = async () => {
    const myContextualTab: Office.Tab = {id: "CtxTab1", visible: true};
    const ribbonUpdater: Office.RibbonUpdaterData = { tabs: [ myContextualTab ]};
    await Office.ribbon.requestUpdate(ribbonUpdater);
}

Alternar a visibilidade do separador e a status ativada de um botão ao mesmo tempo

O requestUpdate método também é utilizado para ativar ou desativar status de um botão personalizado num separador contextual personalizado ou num separador de núcleo personalizado. Para obter detalhes sobre isto, veja Ativar e desativar comandos de suplementos. Podem existir cenários em que pretende alterar a visibilidade de um separador e a status ativada de um botão ao mesmo tempo. Pode fazê-lo com uma única chamada de requestUpdate. Segue-se um exemplo em que um botão num separador principal está ativado ao mesmo tempo que um separador contextual fica visível.

function myContextChanges() {
    Office.ribbon.requestUpdate({
        tabs: [
            {
                id: "CtxTab1",
                visible: true
            },
            {
                id: "OfficeAppTab1",
                groups: [
                    {
                        id: "CustomGroup111",
                        controls: [
                            {
                                id: "MyButton",
                                enabled: true
                            }
                        ]
                    }
                ]
            ]}
        ]
    });
}

No exemplo seguinte, o botão que está ativado encontra-se no mesmo separador contextual que está a ser visível.

function myContextChanges() {
    Office.ribbon.requestUpdate({
        tabs: [
            {
                id: "CtxTab1",
                visible: true,
                groups: [
                    {
                        id: "CustomGroup111",
                        controls: [
                            {
                                id: "MyButton",
                                enabled: true
                           }
                       ]
                   }
               ]
            }
        ]
    });
}

Abrir um painel de tarefas a partir de separadores contextuais

Para abrir o painel de tarefas a partir de um botão num separador contextual personalizado, crie uma ação no JSON com um type de ShowTaskpane. Em seguida, defina um botão com a actionId propriedade definida como a id da ação. Esta ação abre o painel de tarefas predefinido especificado pelo <elemento Runtime> no seu manifesto.

`{
  "actions": [
    {
      "id": "openChartsTaskpane",
      "type": "ShowTaskpane",
      "title": "Work with Charts",
      "supportPinning": false
    }
  ],
  "tabs": [
    {
      // some tab properties omitted
      "groups": [
        {
          // some group properties omitted
          "controls": [
            {
                "type": "Button",
                "id": "CtxBt112",
                "actionId": "openChartsTaskpane",
                "enabled": false,
                "label": "Open Charts Taskpane",
                // some control properties omitted
            }
          ]
        }
      ]
    }
  ]
}`

Para abrir qualquer painel de tarefas que não seja o painel de tarefas predefinido, especifique uma sourceLocation propriedade na definição da ação. No exemplo seguinte, é aberto um segundo painel de tarefas a partir de um botão diferente.

Importante

  • Quando é especificado um sourceLocation para a ação, o painel de tarefas não utiliza o runtime partilhado. É executado num novo runtime separado.
  • Não pode utilizar mais do que um painel de tarefas para utilizar o runtime partilhado, pelo que nenhuma ação do tipo ShowTaskpane pode omitir a sourceLocation propriedade.
`{
  "actions": [
    {
      "id": "openChartsTaskpane",
      "type": "ShowTaskpane",
      "title": "Work with Charts",
      "supportPinning": false
    },
    {
      "id": "openTablesTaskpane",
      "type": "ShowTaskpane",
      "title": "Work with Tables",
      "supportPinning": false
      "sourceLocation": "https://MyDomain.com/myPage.html"
    }
  ],
  "tabs": [
    {
      // some tab properties omitted
      "groups": [
        {
          // some group properties omitted
          "controls": [
            {
                "type": "Button",
                "id": "CtxBt112",
                "actionId": "openChartsTaskpane",
                "enabled": false,
                "label": "Open Charts Taskpane",
                // some control properties omitted
            },
            {
                "type": "Button",
                "id": "CtxBt113",
                "actionId": "openTablesTaskpane",
                "enabled": false,
                "label": "Open Tables Taskpane",
                // some control properties omitted
            }
          ]
        }
      ]
    }
  ]
}`

Localizar o texto JSON

O blob JSON transmitido para requestCreateControls não é localizado da mesma forma que a marcação de manifesto para separadores de núcleo personalizados é localizada (que é descrita em Controlar a localização do manifesto). Em vez disso, a localização tem de ocorrer no runtime com blobs JSON distintos para cada região. Sugerimos que utilize uma switch instrução que teste a propriedade Office.context.displayLanguage . Apresentamos um exemplo a seguir.

function GetContextualTabsJsonSupportedLocale () {
    const displayLanguage = Office.context.displayLanguage;

        switch (displayLanguage) {
            case 'en-US':
                return `{
                    "actions": [
                        // actions omitted
                     ],
                    "tabs": [
                        {
                          "id": "CtxTab1",
                          "label": "Contoso Data",
                          "groups": [
                              // groups omitted
                          ]
                        }
                    ]
                }`;

            case 'fr-FR':
                return `{
                    "actions": [
                        // actions omitted 
                    ],
                    "tabs": [
                        {
                          "id": "CtxTab1",
                          "label": "Contoso Données",
                          "groups": [
                              // groups omitted
                          ]
                       }
                    ]
               }`;

            // Other cases omitted
       }
}

Em seguida, o código chama a função para obter o blob localizado que é transmitido para requestCreateControls, como no exemplo seguinte.

const contextualTabJSON = GetContextualTabsJsonSupportedLocale();

Melhores práticas para separadores contextuais personalizados

Implementar uma experiência de IU alternativa quando os separadores contextuais personalizados não são suportados

Algumas combinações de plataforma, aplicação do Office e compilação do Office não suportam requestCreateControls. O seu suplemento deve ser concebido para proporcionar uma experiência alternativa aos utilizadores que estão a executar o suplemento numa dessas combinações. As secções seguintes descrevem duas formas de proporcionar uma experiência de contingência.

Utilizar separadores ou controlos não contextuais

Existe um elemento de manifesto, OverriddenByRibbonApi, concebido para criar uma experiência de contingência num suplemento que implementa separadores contextuais personalizados quando o suplemento está em execução numa aplicação ou plataforma que não suporta separadores contextuais personalizados.

A estratégia mais simples para utilizar este elemento é definir um separador de núcleo personalizado (ou seja, um separador personalizado não contextual ) no manifesto que duplica as personalizações do friso dos separadores contextuais personalizados no seu suplemento. No entanto, adiciona <OverriddenByRibbonApi>true</OverriddenByRibbonApi> como o primeiro elemento subordinado dos elementos de Grupo, Controlo e item<> duplicados nos separadores principais personalizados. O efeito deste procedimento é o seguinte:

  • Se o suplemento for executado numa aplicação e plataforma que suportem separadores contextuais personalizados, os controlos e grupos principais personalizados não serão apresentados no friso. Em vez disso, o separador contextual personalizado será criado quando o suplemento chamar o requestCreateControls método .
  • Se o suplemento for executado numa aplicação ou plataforma que não suporte requestCreateControls, os elementos serão apresentados no separador de núcleo personalizado.

Apresentamos um exemplo a seguir. Tenha em atenção que "MyButton" só será apresentado no separador de núcleo personalizado quando os separadores contextuais personalizados não forem suportados. No entanto, o grupo principal e o separador core personalizado serão apresentados independentemente de os separadores contextuais personalizados serem suportados.

<OfficeApp ...>
  ...
  <VersionOverrides ...>
    ...
    <Hosts>
      <Host ...>
        ...
        <DesktopFormFactor>
          <ExtensionPoint ...>
            <CustomTab ...>              
              ...
              <Group ...>
                ...
                <Control ... id="Contoso.MyButton1">
                  <OverriddenByRibbonApi>true</OverriddenByRibbonApi>
                  ...
                  <Action ...>
...
</OfficeApp>

Para obter mais exemplos, veja OverriddenByRibbonApi.

Quando um grupo principal ou menu é marcado com <OverriddenByRibbonApi>true</OverriddenByRibbonApi>, não é visível e todas as marcações subordinadas são ignoradas quando os separadores contextuais personalizados não são suportados. Portanto, não importa se algum desses elementos subordinados tem o <elemento OverriddenByRibbonApi> ou qual é o respetivo valor. A implicação disto é que, se um item de menu ou controlo tiver de ser visível em todos os contextos, não só não deve ser marcado com <OverriddenByRibbonApi>true</OverriddenByRibbonApi>, como o respetivo menu e grupo predecessores também não devem ser marcados desta forma.

Importante

Não marque todos os elementos subordinados de um grupo ou menu com <OverriddenByRibbonApi>true</OverriddenByRibbonApi>. Isto não faz sentido se o elemento principal for marcado por <OverriddenByRibbonApi>true</OverriddenByRibbonApi> motivos indicados no parágrafo anterior. Além disso, se deixar de fora o <OverriddenByRibbonApi> no elemento principal (ou definido como false), o elemento principal será apresentado independentemente de os separadores contextuais personalizados serem suportados, mas ficará vazio quando forem suportados. Assim, se todos os elementos subordinados não aparecerem quando os separadores contextuais personalizados são suportados, marque o elemento principal com <OverriddenByRibbonApi>true</OverriddenByRibbonApi>.

Utilizar APIs que mostram ou ocultam um painel de tarefas em contextos especificados

Como alternativa a <OverriddenByRibbonApi>, o suplemento pode definir um painel de tarefas com controlos de IU que duplicam a funcionalidade dos controlos num separador contextual personalizado. Em seguida, utilize os métodos Office.addin.showAsTaskpane e Office.addin.hide para mostrar o painel de tarefas quando o separador contextual teria sido apresentado se fosse suportado. Para obter detalhes sobre como utilizar estes métodos, consulte Mostrar ou ocultar o painel de tarefas do seu Suplemento do Office.

Processar o erro HostRestartNeeded

Em alguns cenários, o Office não consegue atualizar a faixa de opções e retornará um erro. Por exemplo, se o suplemento for atualizado e o suplemento atualizado tiver um conjunto diferente de comandos de suplemento personalizados, o aplicativo do Office deverá ser fechado e reaberto. Até que isso ocorra, o método requestUpdate retornará o erro HostRestartNeeded. O código deve processar este erro. Segue-se um exemplo de como. Nesse caso, o método reportError exibe o erro para o usuário.

function showDataTab() {
    try {
        Office.ribbon.requestUpdate({
            tabs: [
                {
                    id: "CtxTab1",
                    visible: true
                }
            ]});
    }
    catch(error) {
        if (error.code == "HostRestartNeeded"){
            reportError("Contoso Awesome Add-in has been upgraded. Please save your work, then close and reopen the Office application.");
        }
    }
}

Recursos