Tratamento de erros com as APIs JavaScript específicas do aplicativo

Ao criar um suplemento usando as APIs JavaScript do Office específicas do aplicativo, inclua a lógica de tratamento de erros para levar em conta os erros de tempo de execução. Fazer isso é fundamental, devido à natureza assíncrona das APIs.

Práticas recomendadas

Em nossos exemplos de código e snippets do Script Lab, você notará que cada chamada para Excel.run, PowerPoint.runou Word.run é acompanhada por uma catch instrução para capturar erros. Recomendamos que você use o mesmo padrão ao criar um suplemento usando as APIs específicas do aplicativo.

$("#run").on("click", () => tryCatch(run));

async function run() {
  await Excel.run(async (context) => {
      // Add your Excel JavaScript API calls here.

      // Await the completion of context.sync() before continuing.
    await context.sync();
    console.log("Finished!");
  });
}

/** Default helper for invoking an action and handling errors. */
async function tryCatch(callback) {
  try {
    await callback();
  } catch (error) {
    // Note: In a production add-in, you'd want to notify the user through your add-in's UI.
    console.error(error);
  }
}

Erros de API

Quando uma solicitação de API JavaScript do Office não é executada com êxito, a API retorna um objeto de erro que contém as propriedades a seguir.

• code: a code propriedade de uma mensagem de erro contém uma cadeia de caracteres que faz parte de OfficeExtension.ErrorCodes ou {application}.ErrorCodes onde {application} representa o Excel, o PowerPoint ou o Word. Por exemplo, o código de erro "InvalidReference" indica que a referência não é válida para a operação especificada. Os códigos de erro não são localizados.

• message: A propriedade message de uma mensagem de erro contém um resumo do erro na cadeia de caracteres localizada. A mensagem de erro não se destina ao consumo dos usuários finais; Você deve usar o código de erro e a lógica de negócios apropriada para determinar a mensagem de erro que seu suplemento mostra aos usuários finais.

• debugInfo: Quando presente, a propriedade debugInfo da mensagem de erro fornece informações adicionais que você pode usar para compreender a causa raiz do erro.

Mensagens e códigos de erro

As tabelas a seguir listam os erros que as APIs específicas do aplicativo podem retornar.

Mensagens e códigos de erro específicos do Excel

Mensagens e códigos de erro específicos do Word

Notificações de erro

A maneira como você relata erros aos usuários depende do sistema de interface do usuário que você está usando.

• Se você estiver usando o React como o sistema de interface do usuário, use os componentes de interface do usuário do Fluent e os elementos de design. Recomendamos que as mensagens de erro sejam transmitidas com um componente Dialog . Se o erro estiver na entrada do usuário, configure o componente de entrada para exibir o erro como texto vermelho em negrito.

  Observação

  O componente Alerta também pode ser usado para relatar erros aos usuários, mas atualmente está em versão prévia e não deve ser usado em um suplemento de produção. Para obter informações sobre o status da versão, consulte o Roteiro do Componente React v9 da IU do Fluent.

• Se você não estiver usando o React para a interface do usuário, considere usar os componentes mais antigos da interface do usuário do Fabric implementados diretamente em HTML e JavaScript. Alguns modelos de exemplo estão no repositório Office-Add-in-UX-Design-Patterns-Code . Dê uma olhada especialmente nas subpastas de diálogo e navegação. O exemplo Excel-Add-in-SalesLeads usa uma faixa de mensagem.

Confira também

• objeto OfficeExtension.Error
• Códigos de erro comuns da API do Office