Processamento de erros com as APIs de JavaScript específicas da aplicação

Artigo
07/16/2024

Quando criar um suplemento com as APIs de JavaScript do Office específicas da aplicação, certifique-se de que inclui a lógica de processamento de erros para contabilizar os erros de runtime. Fazê-lo é fundamental, devido à natureza assíncrona das APIs.

Práticas recomendadas

Nos nossos exemplos de código e fragmentos do Script Lab , irá reparar que todas as chamadas para Excel.run, PowerPoint.runou Word.run são acompanhadas por uma catch instrução para detetar erros. Recomendamos que utilize o mesmo padrão quando criar um suplemento com as APIs específicas da aplicação.

$("#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 um pedido da API JavaScript do Office não é executado com êxito, a API devolve um objeto de erro que contém as seguintes propriedades.

code: a code propriedade de uma mensagem de erro contém uma cadeia de carateres que faz parte ou OfficeExtension.ErrorCodes{application}.ErrorCodes em que {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 por parte dos utilizadores finais; deve utilizar o código de erro e a lógica de negócio adequada para determinar a mensagem de erro que o suplemento mostra aos utilizadores 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.

Observação

Se utilizar console.log() para imprimir mensagens de erro na consola do , essas mensagens só são visíveis no servidor. Os utilizadores finais não veem essas mensagens de erro no painel de tarefas do suplemento ou em qualquer parte da aplicação do Office. Para comunicar erros ao utilizador, veja Notificações de erro.

Códigos de erro e mensagens

As tabelas seguintes listam os erros que as APIs específicas da aplicação podem devolver.

Observação

As tabelas seguintes listam as mensagens de erro que pode encontrar ao utilizar as APIs específicas da aplicação. Se estiver a trabalhar com a API Comum, consulte Códigos de erro da API Comum do Office para saber mais sobre as mensagens de erro relevantes.

Código de erro	Mensagem de erro	Notas
`AccessDenied`	Você não pode realizar a operação solicitada.	Nenhum
`ActivityLimitReached`	O limite de atividades foi alcançado.	Nenhum
`ApiNotAvailable`	A API solicitada não está disponível.	Nenhum
`ApiNotFound`	Não foi possível localizar a API que está a tentar utilizar. Pode estar disponível numa versão mais recente da aplicação do Office. Para obter mais informações, consulte Disponibilidade da plataforma e da aplicação cliente do Office para suplementos do Office .	Nenhum
`BadPassword`	A palavra-passe que forneceu está incorreta.	Nenhum
`Conflict`	A solicitação não pôde ser processada devido a um conflito.	Nenhum
`ContentLengthRequired`	Falta um `Content-length` cabeçalho HTTP.	Nenhum
`GeneralException`	Ocorreu um erro interno ao processar a solicitação.	Nenhum
`HostRestartNeeded`	A aplicação do Office tem de ser reiniciada.	Este erro é gerado pelo método Office.ribbon.requestUpdate() se o suplemento que chama o método tiver sido atualizado desde o início da aplicação do Office.
`InsertDeleteConflict`	A tentativa de operação de exclusão ou inserção resultou em um conflito.	Nenhum
`InvalidArgument`	O argumento é inválido, está ausente ou tem um formato incorreto.	Nenhum
`InvalidBinding`	Esta associação de objetos não é mais válida devido às atualizações anteriores.	Nenhum
`InvalidOperation`	A tentativa de operação é inválida no objeto.	Nenhum
`InvalidReference`	Esta referência não é válida para a operação atual.	Nenhum
`InvalidRequest`	Não é possível processar a solicitação.	Nenhum
`InvalidRibbonDefinition`	Foi dada ao Office uma definição de friso inválida.	Este erro é gerado se for transmitido um RibbonUpdateObject inválido ao método Office.ribbon.requestUpdate( ).
`InvalidSelection`	A seleção atual é inválida para esta operação.	Nenhum
`ItemAlreadyExists`	O recurso que está sendo criado já existe.	Nenhum
`ItemNotFound`	O recurso solicitado não existe.	Nenhum
`MemoryLimitReached`	O limite de memória foi atingido. Não foi possível concluir a ação.	Nenhum
`NotImplemented`	O recurso solicitado não foi implementado.	Isto pode significar que a API está em pré-visualização ou só é suportada numa determinada plataforma (como apenas online). Para obter mais informações, consulte Disponibilidade da plataforma e da aplicação cliente do Office para suplementos do Office .
`RequestAborted`	A solicitação foi anulada durante o tempo de execução.	Nenhum
`RequestPayloadSizeLimitExceeded`	O tamanho do payload do pedido excedeu o limite. Veja o artigo Limites de recursos e otimização de desempenho para Suplementos do Office para obter mais informações.	Este erro só ocorre no Office na Web.
`ResponsePayloadSizeLimitExceeded`	O tamanho do payload da resposta excedeu o limite. Veja o artigo Limites de recursos e otimização de desempenho para Suplementos do Office para obter mais informações.	Este erro só ocorre no Office na Web.
`ServiceNotAvailable`	O serviço não está disponível.	Nenhum
`Unauthenticated`	Informações de autenticação necessárias estão ausentes ou inválidas.	Nenhum
`UnsupportedFeature`	A operação falhou porque a folha de cálculo de origem contém uma ou mais funcionalidades não suportadas.	Nenhum
`UnsupportedOperation`	Não há suporte para a operação que está sendo tentada.	Nenhum

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

Código de erro	Mensagem de erro	Notas
`EmptyChartSeries`	A operação tentada falhou porque a série de gráficos está vazia.	Nenhum
`FilteredRangeConflict`	A operação tentada causa um conflito com um intervalo filtrado.	Nenhum
`FormulaLengthExceedsLimit`	O código de bytecode da fórmula aplicada excede o limite máximo de comprimento. Para o Office em computadores de 32 bits, o limite de comprimento do código de bytecode é de 16384 carateres. Em computadores de 64 bits, o limite de comprimento do código de bytecode é de 32768 carateres.	Este erro ocorre no Excel na Web e no ambiente de trabalho.
`GeneralException`	Vários.	As APIs de tipos de dados devolvem `GeneralException` erros com mensagens de erro dinâmicas. Estas mensagens referenciam a célula que é a origem do erro e o problema que está a causar o erro, como: "A célula A1 não tem a propriedade `type`necessária ."
`InactiveWorkbook`	A operação falhou porque vários livros estão abertos e o livro que está a ser chamado por esta API perdeu o foco.	Nenhum
`InvalidOperationInCellEditMode`	A operação não está disponível enquanto o Excel estiver no modo Editar célula. Saia do modo Editar com as teclas Enter ou Tab ou selecionando outra célula e, em seguida, tente novamente.	Nenhum
`MergedRangeConflict`	Não é possível concluir a operação. Uma tabela não pode sobrepor-se a outra tabela, um relatório de tabela dinâmica, resultados de consultas, células unidas ou um Mapa XML.	Nenhum
`NonBlankCellOffSheet`	O Microsoft Excel não consegue inserir novas células porque emitiria células não vazias para fora do final da folha de cálculo. Estas células não vazias podem parecer vazias, mas têm valores em branco, alguma formatação ou uma fórmula. Elimine linhas ou colunas suficientes para libertar espaço para o que pretende inserir e, em seguida, tente novamente.	Nenhum
`OperationCellsExceedLimit`	A operação tentada afeta mais do que o limite de 33554000 células.	Se o acionar `TableColumnCollection.add API` este erro, confirme que não existem dados não intencionais na folha de cálculo, mas fora da tabela. Em particular, verifique se existem dados nas colunas mais à direita da folha de cálculo. Remova os dados não intencionais para resolver este erro. Uma forma de verificar quantas células uma operação processa é executar o seguinte cálculo: `(number of table rows) x (16383 - (number of table columns))`. O número 16383 é o número máximo de colunas que o Excel suporta. Este erro só ocorre no Excel na Web.
`PivotTableRangeConflict`	A operação tentada causa um conflito com um intervalo de tabela dinâmica.	Nenhum
`RangeExceedsLimit`	A contagem de células no intervalo excedeu o número máximo suportado. Veja o artigo Limites de recursos e otimização de desempenho para Suplementos do Office para obter mais informações.	Nenhum
`RefreshWorkbookLinksBlocked`	A operação falhou porque o utilizador não concedeu permissão para atualizar ligações de livros externos.	Nenhum
`UnsupportedSheet`	Este tipo de folha não suporta esta operação, uma vez que se trata de uma folha de Macro ou Gráfico.	Nenhum

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

Código de erro	Mensagem de erro	Notas
`SearchDialogIsOpen`	A caixa de diálogo de pesquisa está aberta.	Nenhum
`SearchStringInvalidOrTooLong`	A cadeia de pesquisa é inválida ou demasiado longa.	O máximo da cadeia de pesquisa é de 255 carateres.

Notificações de erro

A forma como comunica erros aos utilizadores depende do sistema de IU que está a utilizar.

Se estiver a utilizar o React como o sistema de IU, utilize os componentes fluente da IU e os elementos de estrutura. Recomendamos que as mensagens de erro sejam transmitidas com um componente de Caixa de Diálogo . Se o erro estiver na entrada do utilizador, configure o componente Entrada para apresentar o erro como texto vermelho a negrito.

Observação

O componente Alerta também pode ser utilizado para comunicar erros aos utilizadores, mas está atualmente em pré-visualização e não deve ser utilizado num suplemento de produção. Para obter informações sobre o respetivo estado de lançamento, veja o Mapa de Objetivos do Componente Fluent UI React v9.
Se não estiver a utilizar o React para a IU, considere utilizar os componentes mais antigos da IU dos Recursos de Infraestrutura implementados diretamente em HTML e JavaScript. Alguns modelos de exemplo estão no repositório Office-Add-in-UX-Design-Patterns-Code . Dê uma vista de olhos especialmente nas subpastas de diálogo e navegação. O exemplo de Excel-Add-in-SalesLeads utiliza uma faixa de mensagens.

Partilhar via