Habilitar e Desabilitar Comandos de Suplemento
Quando algumas funcionalidades no seu suplemento só devem estar disponíveis em determinados contextos, pode ativar ou desativar programaticamente os comandos de suplementos 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 está familiarizado com os conceitos básicos dos Comandos de Suplementos. 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).
A ativação programática ou desativação de menus de contexto não é suportada. Só são suportados botões, menus e separadores do friso.
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. 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 obter mais informações, veja Configurar um suplemento para utilizar um runtime partilhado.
Defina o estado padrão como desabilitado
Por predefinição, qualquer comando de suplemento é ativado quando a aplicação do Office é iniciada. 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. O processo depende do tipo de manifesto utilizado pelo suplemento.
Observação
O manifesto unificado do Microsoft 365 pode ser utilizado nos suplementos de produção do Outlook. Está disponível apenas como uma pré-visualização para suplementos do Excel, PowerPoint e Word.
Basta adicionar uma propriedade "ativada" com o valor false ao objeto de item de controlo ou menu. O seguinte mostra a estrutura básica.
"extensions": [
...
{
...
"ribbons": [
...
{
...
"tabs": [
{
"id": "MyTab",
"groups": [
{
...
"controls": [
{
"id": "Contoso.MyButton1",
...
"enabled": false
}
]
}
]
}
]
}
]
}
]
Alterar o estado programaticamente
Os passos essenciais para alterar a status ativada 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á resolve o objeto de promessa assim que colocar o pedido em fila, 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.
Alternar a visibilidade do separador e a status ativada 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.");
}
}
}