Alterar a disponibilidade dos comandos de suplementos

Quando algumas funcionalidades no seu suplemento só devem estar disponíveis em determinados contextos, pode configurar programaticamente os seus comandos de suplemento personalizados para estarem disponíveis apenas nestes contextos. Por exemplo, uma função que altera o cabeçalho de uma tabela só deve estar disponível quando o cursor estiver numa tabela.

Recursos compatíveis

Pode alterar programaticamente a disponibilidade de um comando de suplemento para as seguintes capacidades.

• Botões, menus e separadores do friso.
• Itens de menu de contexto.

Suporte da aplicação e do conjunto de requisitos do Office

A tabela seguinte descreve as aplicações do Office que suportam a configuração da disponibilidade de comandos de suplementos. Também lista os conjuntos de requisitos necessários para utilizar a API.

Configurar um runtime partilhado

Para alterar a disponibilidade de um friso ou controlo de menu de contexto ou item, o manifesto do suplemento tem primeiro de ser configurado para utilizar um runtime partilhado. Para obter orientações sobre como configurar um runtime partilhado, consulte Configurar o seu Suplemento do Office para utilizar um runtime partilhado.

Alterar programaticamente a disponibilidade de um comando de suplemento

"extensions": [
    ...
    {
        ...
        "ribbons": [
            ...
            {
                ...
                "tabs": [
                    {
                        "id": "MyTab",
                        "groups": [
                            {
                                ...
                                "controls": [
                                    {
                                        "id": "Contoso.MyButton1",
                                        ...
                                        "enabled": false
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }
        ]
    }
]

<OfficeApp ...>
  ...
  <VersionOverrides ...>
    ...
    <Hosts>
      <Host ...>
        ...
        <DesktopFormFactor>
          <ExtensionPoint ...>
            <CustomTab ...>
              ...
              <Group ...>
                ...
                <Control ... id="Contoso.MyButton3">
                  ...
                  <Action ...>
                  <Enabled>false</Enabled>
...
</OfficeApp>

function enableButton() {
    const ribbonUpdaterData = {
        tabs: [
            {
                id: "OfficeAppTab1",
                groups: [
                    {
                      id: "CustomGroup111",
                      controls: [
                        {
                            id: "MyButton",
                            enabled: true
                        }
                      ]
                    }
                ]
            }
        ]
    };

    Office.ribbon.requestUpdate(ribbonUpdaterData);
}

const enableButton = async () => {
    const button: Control = { id: "MyButton", enabled: true };
    const parentGroup: Group = { id: "CustomGroup111", controls: [button] };
    const parentTab: Tab = { id: "OfficeAddinTab1", groups: [parentGroup] };
    const ribbonUpdater: RibbonUpdaterData = { tabs: [parentTab] };
    Office.ribbon.requestUpdate(ribbonUpdater);
}

await Office.contextMenu.requestUpdate({
    controls: [
        {
            id: Addin.CtxMenu.Button1,
            enabled: true
        },
        {
            id: Addin.CtxMenu.Button2,
            enabled: false
        },
    ]
});

Alterar o estado em resposta a um evento

Um cenário comum no qual o estado de um friso ou controlo de menu de contexto deve ser alterado é quando um evento iniciado pelo utilizador altera o contexto do suplemento. Considere um cenário em que um botão deve estar disponível quando, e apenas quando, um gráfico é ativado. Embora o exemplo seguinte utilize controlos do friso, uma implementação semelhante pode ser aplicada a itens personalizados num menu de contexto.

1. Em primeiro lugar, defina o <elemento Ativado> para o botão no manifesto como false. Para obter orientações sobre como configurar esta opção, veja Desativar controlos do friso no início.

2. Em seguida, atribua processadores. Normalmente, isto é feito na função Office.onReady , tal como no exemplo seguinte. No exemplo, os processadores (criados num passo posterior) são atribuídos aos eventos onActivated e onDeactivated de todos os gráficos numa folha de cálculo do Excel.

   Office.onReady(async () => {
       await Excel.run((context) => {
           const charts = context.workbook.worksheets
               .getActiveWorksheet()
               .charts;
           charts.onActivated.add(enableChartFormat);
           charts.onDeactivated.add(disableChartFormat);
           return context.sync();
       });
   });
   

3. Defina o enableChartFormat processador. Apresentamos um exemplo simples a seguir. Para obter uma forma mais robusta de alterar a status de um controlo, veja Melhores práticas: Testar erros de status de controlo.

   function enableChartFormat() {
       const button =
           {
               id: "ChartFormatButton",
               enabled: true
           };
       const parentGroup =
           {
               id: "MyGroup",
               controls: [button]
           };
       const parentTab =
           {
               id: "CustomChartTab",
               groups: [parentGroup]
           };
       const ribbonUpdater = { tabs: [parentTab] };
       Office.ribbon.requestUpdate(ribbonUpdater);
   }
   

4. Defina o disableChartFormat processador. É idêntico ao enableChartFormat processador, exceto que a propriedade ativada do objeto de botão está definida como false.

Prática recomendada: Teste se há erros de status do controle

Em algumas circunstâncias, o friso ou menu de contexto não é repaint depois requestUpdate de ser chamado, pelo que a status clicável do controlo não é alterada. Por este motivo, é recomendado que o suplemento controle a status dos respetivos controlos. O suplemento deve estar em conformidade com as seguintes regras.

• Sempre que requestUpdate é chamado, o código deve registrar o estado pretendido dos botões e itens de menu personalizados.
• Quando um controlo personalizado é selecionado, o primeiro código no processador deve marcar para ver se o botão deveria estar disponível. Se não deveria estar disponível, o código deve comunicar ou registar um erro e tentar novamente definir os botões para o estado pretendido.

O exemplo seguinte mostra uma função que desativa um botão no friso e regista o status do botão. Neste exemplo, chartFormatButtonEnabled é uma variável booleana global que é inicializada para o mesmo valor que o elemento Ativado para o botão no manifesto do suplemento. Embora o exemplo utilize um botão do friso, uma implementação semelhante pode ser aplicada a itens personalizados num menu de contexto.

function disableChartFormat() {
    const button =
    {
        id: "ChartFormatButton",
        enabled: false
    };
    const parentGroup =
    {
        id: "MyGroup",
        controls: [button]
    };
    const parentTab =
    {
        id: "CustomChartTab",
        groups: [parentGroup]
    };
    const ribbonUpdater = { tabs: [parentTab] };
    Office.ribbon.requestUpdate(ribbonUpdater);

    chartFormatButtonEnabled = false;
}

O exemplo a seguir mostra como o manipulador do botão testa um estado incorreto do botão. Observe que reportError é uma função que mostra ou registra um erro.

function chartFormatButtonHandler() {
    if (chartFormatButtonEnabled) {

        // Do work here.

    } else {
        // Report the error and try to make the button unavailable again.
        reportError("That action is not possible at this time.");
        disableChartFormat();
    }
}

Tratamento de erros

Em alguns cenários, o Office não consegue atualizar o friso ou o menu de contexto e irá devolver 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. Veja um exemplo de como lidar com esse erro a seguir. Nesse caso, o método reportError exibe o erro para o usuário. Embora o exemplo utilize um botão do friso, uma implementação semelhante pode ser aplicada a itens personalizados num menu de contexto.

function disableChartFormat() {
    try {
        const button =
        {
            id: "ChartFormatButton",
            enabled: false
        };
        const parentGroup =
        {
            id: "MyGroup",
            controls: [button]
        };
        const parentTab =
        {
            id: "CustomChartTab",
            groups: [parentGroup]
        };
        const ribbonUpdater = { tabs: [parentTab] };
        Office.ribbon.requestUpdate(ribbonUpdater);

        chartFormatButtonEnabled = false;
    }
    catch(error) {
        if (error.code == "HostRestartNeeded"){
            reportError("Contoso Awesome Add-in has been upgraded. Please save your work, close the Office application, and restart it.");
        }
    }
}

Confira também

• Comandos de suplemento
• Criar comandos de suplemento com o manifesto apenas do suplemento
• Criar separadores contextuais personalizados nos Suplementos do Office