Control de errores con las API de JavaScript específicas de la aplicación

Artículo
03/01/2024

Al compilar un complemento con las API de JavaScript de Office específicas de la aplicación, asegúrese de incluir la lógica de control de errores para tener en cuenta los errores en tiempo de ejecución. Hacerlo es fundamental, debido a la naturaleza asincrónica de las API.

Procedimientos recomendados

En nuestros ejemplos de código y Script Lab fragmentos de código, observará que todas las llamadas a Excel.run, PowerPoint.runo Word.run van acompañadas de una catch instrucción para detectar errores. Se recomienda usar el mismo patrón al compilar un complemento mediante las API específicas de la aplicación.

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

Errores de API

Cuando una solicitud de API de JavaScript de Office no se ejecuta correctamente, la API devuelve un objeto de error que contiene las siguientes propiedades.

code: la code propiedad de un mensaje de error contiene una cadena que forma parte de OfficeExtension.ErrorCodes o {application}.ErrorCodes donde {application} representa Excel, PowerPoint o Word. Por ejemplo, el código de error "InvalidReference" indica que la referencia no es válida para la operación especificada. Los códigos de error no se localizan.
message La propiedad message de un mensaje de error contiene un resumen del error en la cadena localizada. El mensaje de error no está pensado para su consumo por parte de los usuarios finales; debe usar el código de error y la lógica de negocios adecuada para determinar el mensaje de error que el complemento muestra a los usuarios finales.
debugInfo: Cuando está presente, la propiedad debugInfo del mensaje de error proporciona información adicional que puede usar para conocer la causa principal del error.

Nota:

Si usa console.log() para imprimir mensajes de error en la consola, esos mensajes solo estarán visibles en el servidor. Los usuarios finales no ven esos mensajes de error en el panel de tareas del complemento ni en ninguna parte de la aplicación de Office. Para notificar errores al usuario, consulte Notificaciones de errores.

Códigos de error y mensajes

En las tablas siguientes se enumeran los errores que pueden devolver las API específicas de la aplicación.

Nota:

En las tablas siguientes se enumeran los mensajes de error que puede encontrar al usar las API específicas de la aplicación. Si está trabajando con Common API, consulte Códigos de error de La API común de Office para obtener información sobre los mensajes de error pertinentes.

Código de error	Mensaje de error	Notas
`AccessDenied`	No se puede realizar la operación solicitada.	Ninguno.
`ActivityLimitReached`	Se alcanzó el límite de actividad.	Ninguno.
`ApiNotAvailable`	La API solicitada no está disponible.	Ninguno.
`ApiNotFound`	No se encontró la API que está intentando usar. Puede estar disponible en una versión más reciente de la aplicación de Office. Consulte Disponibilidad de la plataforma y la aplicación cliente de Office para complementos de Office para obtener más información.	Ninguno.
`BadPassword`	La contraseña proporcionada es incorrecta.	Ninguno.
`Conflict`	No se pudo procesar la solicitud debido a un conflicto.	Ninguno.
`ContentLengthRequired`	Falta un `Content-length` encabezado HTTP.	Ninguno.
`GeneralException`	Se produjo un error interno al procesar la solicitud.	Ninguno.
`HostRestartNeeded`	Es necesario reiniciar la aplicación de Office.	Este error lo produce el método Office.ribbon.requestUpdate() si el complemento que llama al método se ha actualizado desde que se inició la aplicación de Office.
`InsertDeleteConflict`	La operación de inserción o eliminación intentada dio lugar a un conflicto.	Ninguno.
`InvalidArgument`	El argumento no es válido, o falta o tiene un formato incorrecto.	Ninguno.
`InvalidBinding`	Este enlace de objeto ya no es válido debido a actualizaciones anteriores.	Ninguno.
`InvalidOperation`	La operación intentada no es válida en el objeto.	Ninguno.
`InvalidReference`	Esta referencia no es válida para la operación actual.	Ninguno.
`InvalidRequest`	No se puede procesar la solicitud.	Ninguno.
`InvalidRibbonDefinition`	A Office se le ha dado una definición de cinta de opciones no válida.	Este error se produce si se pasa un objeto RibbonUpdateObject no válido al método Office.ribbon.requestUpdate().
`InvalidSelection`	La selección actual no es válida para esta operación.	Ninguno.
`ItemAlreadyExists`	El recurso que se está creando ya existe.	Ninguno.
`ItemNotFound`	El recurso solicitado no existe.	Ninguno.
`MemoryLimitReached`	Se ha alcanzado el límite de memoria. No se pudo completar la acción.	Ninguno.
`NotImplemented`	La característica solicitada no se implementó.	Esto podría significar que la API está en versión preliminar o solo se admite en una plataforma determinada (por ejemplo, solo en línea). Consulte Disponibilidad de la plataforma y la aplicación cliente de Office para complementos de Office para obtener más información.
`RequestAborted`	La solicitud se anuló durante el tiempo de ejecución.	Ninguno.
`RequestPayloadSizeLimitExceeded`	El tamaño de carga de la solicitud ha superado el límite. Consulte el artículo Límites de recursos y optimización de rendimiento para complementos de Office para obtener más información.	Este error solo se produce en Office en la Web.
`ResponsePayloadSizeLimitExceeded`	El tamaño de carga de respuesta ha superado el límite. Consulte el artículo Límites de recursos y optimización de rendimiento para complementos de Office para obtener más información.	Este error solo se produce en Office en la Web.
`ServiceNotAvailable`	El servicio no está disponible.	Ninguno.
`Unauthenticated`	La información de autenticación necesaria falta o no es válida.	Ninguno.
`UnsupportedFeature`	Error en la operación porque la hoja de cálculo de origen contiene una o varias características no admitidas.	Ninguno.
`UnsupportedOperation`	No se admite la operación que se está intentando.	Ninguno.

Mensajes y códigos de error específicos de Excel

Código de error	Mensaje de error	Notas
`EmptyChartSeries`	Error en la operación de intento porque la serie de gráficos está vacía.	Ninguno.
`FilteredRangeConflict`	La operación intentada provoca un conflicto con un intervalo filtrado.	Ninguno.
`FormulaLengthExceedsLimit`	El código de bytes de la fórmula aplicada supera el límite de longitud máximo. Para Office en máquinas de 32 bits, el límite de longitud del código de bytes es de 16384 caracteres. En máquinas de 64 bits, el límite de longitud del código de bytes es de 32768 caracteres.	Este error se produce tanto en Excel en la Web como en el escritorio.
`GeneralException`	Varios.	Las API de tipos de datos devuelven `GeneralException` errores con mensajes de error dinámicos. Estos mensajes hacen referencia a la celda que es el origen del error y al problema que provoca el error, como: "A la celda A1 le falta la propiedad `type`necesaria".
`InactiveWorkbook`	Error en la operación porque hay varios libros abiertos y el libro al que llama esta API ha perdido el foco.	Ninguno.
`InvalidOperationInCellEditMode`	La operación no está disponible mientras Excel está en modo de edición de celda. Salga del modo De edición con las teclas Entrar o Tabulación , o bien seleccione otra celda y vuelva a intentarlo.	Ninguno.
`MergedRangeConflict`	No se puede completar la operación. Una tabla no se puede superponer con otra tabla, un informe de tabla dinámica, resultados de consultas, celdas combinadas o una asignación XML.	Ninguno.
`NonBlankCellOffSheet`	Microsoft Excel no puede insertar nuevas celdas porque insertaría celdas no vacías fuera del final de la hoja de cálculo. Estas celdas no vacías pueden aparecer vacías, pero tienen valores en blanco, algún formato o una fórmula. Elimine suficientes filas o columnas para dejar espacio a lo que quiere insertar y vuelva a intentarlo.	Ninguno.
`OperationCellsExceedLimit`	La operación intentada afecta a más del límite de 33554000 celdas.	Si desencadena `TableColumnCollection.add API` este error, confirme que no hay datos involuntarios dentro de la hoja de cálculo, pero fuera de la tabla. En concreto, compruebe si hay datos en las columnas más a la derecha de la hoja de cálculo. Quite los datos no deseados para resolver este error. Una manera de comprobar cuántas celdas procesa una operación es ejecutar el siguiente cálculo: `(number of table rows) x (16383 - (number of table columns))`. El número 16383 es el número máximo de columnas que admite Excel. Este error solo se produce en Excel en la Web.
`PivotTableRangeConflict`	La operación intentada provoca un conflicto con un intervalo de tabla dinámica.	Ninguno.
`RangeExceedsLimit`	El recuento de celdas del intervalo ha superado el número máximo admitido. Consulte el artículo Límites de recursos y optimización de rendimiento para complementos de Office para obtener más información.	Ninguno.
`RefreshWorkbookLinksBlocked`	Error en la operación porque el usuario no ha concedido permiso para actualizar vínculos de libros externos.	Ninguno.
`UnsupportedSheet`	Este tipo de hoja no admite esta operación, ya que es una hoja macro o de gráfico.	Ninguno.

mensajes y códigos de error específicos de Word

Código de error	Mensaje de error	Notas
`SearchDialogIsOpen`	El cuadro de diálogo de búsqueda está abierto.	Ninguno.
`SearchStringInvalidOrTooLong`	La cadena de búsqueda no es válida o es demasiado larga.	La cadena de búsqueda tiene un máximo de 255 caracteres.

Notificaciones de error

La forma de notificar errores a los usuarios depende del sistema de interfaz de usuario que use.

Si usa React como sistema de interfaz de usuario, use los componentes y los elementos de diseño de la interfaz de usuario de Fluent. Se recomienda que los mensajes de error se transmitan con un componente dialog . Si el error está en la entrada del usuario, configure el componente Entrada para mostrar el error como texto rojo en negrita.

Nota:

El componente Alerta también se puede usar para notificar errores a los usuarios, pero actualmente está en versión preliminar y no debe usarse en un complemento de producción. Para obtener información sobre su estado de versión, consulte fluent UI React v9 Component Roadmap( Hoja de ruta de componentes de Fluent UI React v9).
Si no usa React para la interfaz de usuario, considere la posibilidad de usar los componentes de interfaz de usuario de Fabric anteriores implementados directamente en HTML y JavaScript. Algunas plantillas de ejemplo se encuentran en el repositorio Office-Add-in-UX-Design-Patterns-Code . Eche un vistazo especialmente en las subcarpetas de diálogo y navegación. El ejemplo Excel-Add-in-SalesLeads usa un banner de mensaje.