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

Al compilar un complemento con las API de JavaScript de Office específicas de la aplicación, asegúrese de incluir 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 fragmentos de código de Script Lab, observarás que cada llamada a Excel.run, PowerPoint.runo Word.run va acompañada de una catch instrucción para detectar errores. Se recomienda usar el mismo patrón al compilar un complemento con 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 Excel, PowerPoint o Word o donde {application} representa{application}.ErrorCodes. 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 que lo consuman 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 suele console.log() imprimir mensajes de error en la consola, esos mensajes solo serán visibles en el servidor. Los usuarios finales no verán esos mensajes de error en el panel de tareas del complemento ni en ningún otro lugar de la aplicación de Office. Para notificar errores al usuario, consulte Notificaciones de errores.

Códigos y mensajes de error

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 pueden encontrarse al usar las API específicas de la aplicación. Si trabaja con la API común, consulte Códigos de error de la API común de Office para obtener información sobre los mensajes de error relevantes.

Código de error Mensaje de error Notas
AccessDenied No se puede realizar la operación solicitada. Esto puede deberse a que el software antivirus de un usuario bloquea partes de Office. Consulte los errores comunes y los pasos de solución de problemas de "Error: acceso denegado" para obtener más ayuda.
ActivityLimitReached Se alcanzó el límite de actividad. Ninguna
ApiNotAvailable La API solicitada no está disponible. Ninguna
ApiNotFound No se encontró la API que intenta usar. Puede que esté disponible en una versión más reciente de la aplicación de Office. Vea Disponibilidad de aplicaciones y plataformas cliente de Office para complementos de Office para obtener más información. Ninguna
BadPassword La contraseña proporcionada es incorrecta. Ninguna
Conflict No se pudo procesar la solicitud debido a un conflicto. Ninguna
ContentLengthRequired Falta un Content-length encabezado HTTP. Ninguna
GeneralException Se produjo un error interno al procesar la solicitud. Ninguna
HostRestartNeeded Es necesario reiniciar la aplicación de Office. Este error lo genera 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. Ninguna
InvalidArgument El argumento no es válido, o falta o tiene un formato incorrecto. Ninguna
InvalidBinding Este enlace de objeto ya no es válido debido a actualizaciones anteriores. Ninguna
InvalidOperation La operación intentada no es válida en el objeto. Ninguna
InvalidReference Esta referencia no es válida para la operación actual. Ninguna
InvalidRequest No se puede procesar la solicitud. Ninguna
InvalidRibbonDefinition A Office se le ha asignado una definición de cinta de opciones no válida. Este error se produce si se pasa un RibbonUpdateObject no válido al método Office.ribbon.requestUpdate().
InvalidSelection La selección actual no es válida para esta operación. Ninguna
ItemAlreadyExists El recurso que se está creando ya existe. Ninguna
ItemNotFound El recurso solicitado no existe. Ninguna
MemoryLimitReached Se ha alcanzado el límite de memoria. No se pudo completar la acción. Ninguna
NotImplemented La característica solicitada no se implementó. Esto podría significar que la API está en versión preliminar o solo es compatible con una plataforma determinada (por ejemplo, solo en línea). Vea Disponibilidad de aplicaciones y plataformas cliente de Office para complementos de Office para obtener más información.
RequestAborted La solicitud se anuló durante el tiempo de ejecución. Ninguna
RequestPayloadSizeLimitExceeded El tamaño de carga útil de la solicitud ha superado el límite. Vea el artículo Límites de recursos y optimización del 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 la carga útil de la respuesta ha superado el límite. Vea el artículo Límites de recursos y optimización del 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. Ninguna
Unauthenticated La información de autenticación necesaria falta o no es válida. Ninguna
UnsupportedFeature Se ha producido un error en la operación porque la hoja de cálculo de origen contiene una o varias características no admitidas. Ninguna
UnsupportedOperation No se admite la operación que se está intentando. Ninguna

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

Código de error Mensaje de error Notas
EmptyChartSeries Error en la operación intentada porque la serie de gráficos está vacía. Ninguna
FilteredRangeConflict La operación intentada provoca un conflicto con un intervalo filtrado. Ninguna
FormulaLengthExceedsLimit El código de bytes de la fórmula aplicada supera el límite de longitud máxima. Para Office en máquinas de 32 bits, el límite de longitud de 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 está causando el error, por ejemplo: "Falta la propiedad requerida typeen la celda A1".
InactiveWorkbook Se ha producido un error en la operación porque hay varios libros abiertos y el libro al que llama esta API ha perdido el enfoque. Ninguna
InvalidOperationInCellEditMode La operación no está disponible mientras Excel está en modo Editar celda. Salga del modo de edición con las teclas Entrar o Tab , o seleccionando otra celda, y vuelva a intentarlo. Ninguna
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. Ninguna
NonBlankCellOffSheet Microsoft Excel no puede insertar nuevas celdas porque empujaría las celdas no vacías fuera del final de la hoja de cálculo. Estas celdas no vacías pueden parecer vacías, pero tienen valores en blanco, algo de formato o una fórmula. Elimine las filas o columnas suficientes para dejar espacio para lo que desea insertar y vuelva a intentarlo. Ninguna
OperationCellsExceedLimit El intento de operación 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 particular, compruebe si hay datos en las columnas del extremo derecho de la hoja de cálculo. Quite los datos no deseados para resolver este error. Una forma 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 Excel admite.

Este error solo se produce en Excel en la Web.
PivotTableRangeConflict La operación intentada provoca un conflicto con un rango de tabla dinámica. Ninguna
RangeExceedsLimit El recuento de celdas del intervalo ha superado el número máximo admitido. Vea el artículo Límites de recursos y optimización del rendimiento para complementos de Office para obtener más información. Ninguna
RefreshWorkbookLinksBlocked Se ha producido un error en la operación porque el usuario no ha concedido permiso para actualizar vínculos de libros externos. Ninguna
UndoNotSupported Se produjo un error en la solicitud de API de JavaScript debido a la falta de compatibilidad con la operación de deshacer. Ninguna
UnsupportedSheet Este tipo de hoja no admite esta operación, ya que es una hoja de macros o de gráfico. Ninguna

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

Código de error Mensaje de error Notas
SearchDialogIsOpen Se abre el cuadro de diálogo de búsqueda. Ninguna
SearchStringInvalidOrTooLong La cadena de búsqueda no es válida o es demasiado larga. La cadena de búsqueda máxima es de 255 caracteres.

Notificaciones de error

La forma de notificar errores a los usuarios depende del sistema de interfaz de usuario que estés usando.

  • Si usa React como sistema de interfaz de usuario, use los componentes y elementos de diseño de la interfaz de usuario de Fluent. Recomendamos 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 que muestre 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 debería usarse en un complemento de producción. Para obtener información sobre su estado de lanzamiento, consulte la hoja de ruta del componente React v9 de Fluent UI.

  • 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.

Vea también

  • Last updated on