Habilitar e Desabilitar Comandos de Suplemento

Artigo
06/26/2024

Quando alguma funcionalidade do seu suplemento deve estar disponível apenas em determinados contextos, você pode habilitar ou desabilitar programaticamente seus Comandos de Suplemento personalizados. Por exemplo, uma função que altera o cabeçalho de uma tabela só deve ser ativada quando o cursor estiver em uma tabela.

Também pode especificar se o comando está ativado ou desativado quando a aplicação cliente do Office é aberta.

Observação

Este artigo pressupõe que você esteja familiarizado com a seguinte documentação. Revise-o se você não trabalhou recentemente com os Comandos de Suplemento (itens de menu personalizados e botões da faixa de opções).

Conceitos básicos dos Comandos de Suplemento

Suporte para aplicações e plataformas do Office

As APIs descritas neste artigo estão disponíveis no Excel, PowerPoint e Word como parte do conjunto de requisitos RibbonApi 1.1 . Atualmente, as APIs do Friso para as aplicações Web estão em pré-visualização. Para saber como testar o suporte da plataforma com conjuntos de requisitos, consulte Versões do Office e conjuntos de requisitos.

Tempo de execução compartilhado necessário

As APIs e a marcação de manifesto descritas neste artigo exigem que o manifesto do suplemento especifique que deve utilizar um runtime partilhado. Para tal, siga os seguintes passos.

No elemento Runtimes no manifesto, adicione o seguinte elemento filho: <Runtime resid="Contoso.SharedRuntime.Url" lifetime="long" />. (Se ainda não existir um <elemento Runtimes> no manifesto, crie-o como o primeiro subordinado <no elemento Anfitrião> na <secção VersionOverrides> .)
Na seção Resources.Urls do manifesto, adicione o seguinte elemento filho: <bt:Url id="Contoso.SharedRuntime.Url" DefaultValue="https://{MyDomain}/{path-to-start-page}" />, onde {MyDomain} é o domínio do suplemento e {path-to-start-page} o caminho da página inicial do suplemento; por exemplo: <bt:Url id="Contoso.SharedRuntime.Url" DefaultValue="https://localhost:3000/index.html" />.
Consoante o seu suplemento contenha um painel de tarefas, um ficheiro de função ou uma função personalizada do Excel, tem de efetuar um ou mais dos três passos seguintes.
- Se o suplemento contiver um painel de tarefas, defina o resid atributo da Ação.SourceLocation element to exactly the same string as you used for the of the resid<Runtime> element in step 1; for example, Contoso.SharedRuntime.Url. O elemento deve ficar assim: <SourceLocation resid="Contoso.SharedRuntime.Url"/>.
- Se o suplemento contiver uma função personalizada do Excel, defina o resid atributo da Página.SourceLocation element exactly the same string as you used for the of the resid<Runtime> element in step 1; for example, Contoso.SharedRuntime.Url. O elemento deve ficar assim: <SourceLocation resid="Contoso.SharedRuntime.Url"/>.
- Se o suplemento contiver um ficheiro de função, defina o resid atributo do elemento FunctionFile para exatamente a mesma cadeia que utilizou para o resid<elemento Runtime> no passo 1; por exemplo, Contoso.SharedRuntime.Url. O elemento deve ficar assim: <FunctionFile resid="Contoso.SharedRuntime.Url"/>.

Defina o estado padrão como desabilitado

Por padrão, qualquer comando de suplemento é habilitado quando o aplicativo do Office é iniciado. Se você deseja que um botão ou item de menu personalizado esteja desabilitado quando o aplicativo do Office for iniciado, especifique isso no manifesto. Basta adicionar um elemento Enabled (com o valor false) imediatamente abaixo (não dentro) do elemento Ação na declaração do controle. O seguinte mostra a estrutura básica.

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

Alterar o estado programaticamente

As etapas essenciais para alterar o status habilitado de um Comando de Suplemento são:

Crie um objeto RibbonUpdaterData que (1) especifique o comando e o respetivo grupo e separador principais, pelos respetivos IDs conforme declarado no manifesto; e (2) especifica o estado ativado ou desativado do comando.
Passe o objeto RibbonUpdaterData para o método OfficeRuntime.Ribbon.requestUpdate().

Apresentamos um exemplo simples a seguir. Tenha em atenção que "MyButton", "OfficeAddinTab1" e "CustomGroup111" são copiados do manifesto.

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

Também fornecemos várias interfaces (tipos) para facilitar a construção do objeto RibbonUpdateData. Veja a seguir o exemplo equivalente no TypeScript, que faz uso desses tipos.

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);
}

Pode await chamar requestUpdate() se a função principal for assíncrona, mas tenha em atenção que a aplicação do Office controla quando atualiza o estado do friso. O método requestUpdate() adiciona uma solicitação para atualização à fila de espera. O método irá resolver o objeto de promessa assim que colocar o pedido em fila e não quando o friso for realmente atualizado.

Alterar o estado em resposta a um evento

Um cenário comum em que o estado da faixa de opções deve mudar é quando um evento iniciado pelo usuário altera o contexto do suplemento.

Considere um cenário em que um botão deve ser ativado quando e somente quando um gráfico é ativado. A primeira etapa é definir o elemento Enabled para o botão no manifesto como false. Veja um exemplo acima.

Segundo, atribua manipuladores. Normalmente, isto é feito na função Office.onReady , tal como no exemplo seguinte, que atribui processadores (criados num passo posterior) aos eventos onActivated e onDeactivated de todos os gráficos na folha de cálculo.

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();
    });
});

Terceiro, defina o manipulador enableChartFormat. A seguir, é apresentado um exemplo simples, mas consulte Prática recomendada: Teste se há erros de status do controle abaixo para obter uma maneira mais robusta de alterar o status de um controle.

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);
}

Quarto, defina o manipulador disableChartFormat. Seria idêntico a enableChartFormat, exceto que a propriedade enabled do objeto button seria configurada como false.

Ativar/desativar a visibilidade do separador e o estado ativado de um botão ao mesmo tempo

O método requestUpdate também é utilizado para alternar a visibilidade de um separador contextual personalizado. Para obter detalhes sobre este e código de exemplo, consulte Criar separadores contextuais personalizados nos Suplementos do Office.

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

Em algumas circunstâncias, a faixa de opções não é redesenhada após requestUpdate ser chamado, portanto, o status clicável do controle não muda. Por esse motivo, é uma prática recomendada para o suplemento acompanhar o status de seus controles. 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 controle personalizado é clicado, o primeiro código no manipulador deve verificar se o botão deveria ter sido clicável. Se não deveria ter sido, o código deve relatar ou registrar um erro e tentar novamente definir os botões no estado pretendido.

O exemplo a seguir mostra uma função que desativa um botão e registra o status do botão. Observe que chartFormatButtonEnabled é uma variável booleana global inicializada com o mesmo valor que o elemento Enabled para o botão no manifesto.

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 again to disable.
        reportError("That action is not possible at this time.");
        disableChartFormat();
    }
}

Tratamento de erros

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. Veja um exemplo de como lidar com esse erro a seguir. Nesse caso, o método reportError exibe o erro para o usuário.

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.");
        }
    }
}

Partilhar via