Обработка ошибок с помощью API JavaScript для конкретного приложения

Статья
07/16/2024

При создании надстройки с помощью API JavaScript для Office, относящегося к приложению, обязательно включите логику обработки ошибок, чтобы учесть ошибки среды выполнения. Это крайне важно из-за асинхронной природы API.

Лучшие методики

В наших примерах кода и фрагментах скриптов лаборатории вы заметите, что каждый вызов Excel.run, PowerPoint.runили Word.run сопровождается инструкцией catch для перехвата ошибок. Мы рекомендуем использовать тот же шаблон при создании надстройки с помощью API-интерфейсов приложения.

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

Ошибки API

Если запрос API JavaScript для Office не выполняется успешно, API возвращает объект ошибки, содержащий следующие свойства.

code: code свойство сообщения об ошибке содержит строку, которая является частью OfficeExtension.ErrorCodes или {application}.ErrorCodes где {application} представляет Excel, PowerPoint или Word. Например, код ошибки InvalidReference указывает, что ссылка недопустима для указанной операции. Коды ошибок не локализованы.
message. Свойство message сообщения об ошибке содержит сводные сведения об ошибке в локализованной строке. Сообщение об ошибке не предназначено для использования конечными пользователями; Для определения сообщения об ошибке, отображаемого надстройкой для конечных пользователей, следует использовать код ошибки и соответствующую бизнес-логику.
debugInfo. Если в сообщении об ошибке имеется свойство debugInfo, в нем содержатся дополнительные сведения, которые вы можете использовать, чтобы понять причину ошибки.

Примечание.

Если вы используете для console.log() печати сообщений об ошибках в консоли, эти сообщения будут видны только на сервере. Пользователи не видят эти сообщения об ошибках в области задач надстройки или в приложении Office. Чтобы сообщить об ошибках пользователю, см. раздел Уведомления об ошибках.

Коды ошибок и сообщения

В следующих таблицах перечислены ошибки, которые могут возвращать API-интерфейсы приложений.

Примечание.

В следующих таблицах перечислены сообщения об ошибках, которые могут возникнуть при использовании API для конкретного приложения. Если вы работаете с Общим API, ознакомьтесь с разделом Коды ошибок Office Common API , чтобы узнать о соответствующих сообщениях об ошибках.

Код ошибки	Сообщение об ошибке	Примечания
`AccessDenied`	Вы не можете выполнить запрашиваемую операцию.	Нет
`ActivityLimitReached`	Достигнут предел действий.	Нет
`ApiNotAvailable`	Запрашиваемый интерфейс API недоступен.	Нет
`ApiNotFound`	Не удалось найти API, который вы пытаетесь использовать. Он может быть доступен в более новой версии приложения Office. Дополнительные сведения см. в статье Доступность клиентских приложений и платформ Office для надстроек Office .	Нет
`BadPassword`	Указан неправильный пароль.	Нет
`Conflict`	Запрос не удалось обработать из-за конфликта.	Нет
`ContentLengthRequired`	Отсутствует `Content-length` заголовок HTTP.	Нет
`GeneralException`	При обработке запроса возникла внутренняя ошибка.	Нет
`HostRestartNeeded`	Приложение Office необходимо перезапустить.	Эта ошибка возникает методом Office.ribbon.requestUpdate(), если надстройка, вызывающая метод, была обновлена с момента запуска приложения Office.
`InsertDeleteConflict`	Операция вставки или удаления привела к конфликту.	Нет
`InvalidArgument`	Аргумент недопустим, отсутствует или имеет неправильный формат.	Нет
`InvalidBinding`	Эта привязка объектов недопустима из-за предыдущих обновлений.	Нет
`InvalidOperation`	Выполняемая операция недопустима для этого объекта.	Нет
`InvalidReference`	Эта ссылка недопустима для текущей операции.	Нет
`InvalidRequest`	Не удается обработать запрос.	Нет
`InvalidRibbonDefinition`	Office было присвоено недопустимое определение ленты.	Эта ошибка возникает, если недопустимый объект RibbonUpdateObject передается в метод Office.ribbon.requestUpdate().
`InvalidSelection`	Выбранный фрагмент недопустим для этой операции.	Нет
`ItemAlreadyExists`	Создаваемый ресурс уже существует.	Нет
`ItemNotFound`	Запрашиваемый ресурс не существует.	Нет
`MemoryLimitReached`	Достигнут предел памяти. Не удалось выполнить действие.	Нет
`NotImplemented`	Запрашиваемая функция не реализована.	Это может означать, что API находится в предварительной версии или поддерживается только на определенной платформе (например, только в сети). Дополнительные сведения см. в статье Доступность клиентских приложений и платформ Office для надстроек Office .
`RequestAborted`	Запрос прерван во время выполнения.	Нет
`RequestPayloadSizeLimitExceeded`	Размер полезных данных запроса превысил ограничение. Дополнительные сведения см. в статье Ограничения ресурсов и оптимизация производительности надстроек Office .	Эта ошибка возникает только в Office в Интернете.
`ResponsePayloadSizeLimitExceeded`	Размер полезных данных ответа превысил ограничение. Дополнительные сведения см. в статье Ограничения ресурсов и оптимизация производительности надстроек Office .	Эта ошибка возникает только в Office в Интернете.
`ServiceNotAvailable`	Служба недоступна.	Нет
`Unauthenticated`	Требуемые сведения о проверке подлинности отсутствуют или недопустимы.	Нет
`UnsupportedFeature`	Операция завершилась сбоем, так как исходный лист содержит один или несколько неподдерживаемых функций.	Нет
`UnsupportedOperation`	Выполняемая операция не поддерживается.	Нет

Коды ошибок и сообщения, относящиеся к Excel

Код ошибки	Сообщение об ошибке	Примечания
`EmptyChartSeries`	Попытка операции завершилась сбоем, так как ряд диаграммы пуст.	Нет
`FilteredRangeConflict`	Предпринятая попытка операции вызывает конфликт с отфильтрованным диапазоном.	Нет
`FormulaLengthExceedsLimit`	Байт-код примененной формулы превышает предел максимальной длины. Для Office на 32-разрядных компьютерах ограничение длины байт-кода составляет 16384 символа. На 64-разрядных компьютерах ограничение длины байт-кода составляет 32768 символов.	Эта ошибка возникает как в Excel в Интернете, так и на рабочем столе.
`GeneralException`	Различный.	API типов данных возвращают `GeneralException` ошибки с динамическими сообщениями об ошибках. Эти сообщения ссылались на ячейку, которая является источником ошибки, и на проблему, которая вызывает ошибку, например: "Ячейка A1 отсутствует требуемое свойство `type`".
`InactiveWorkbook`	Операция завершилась сбоем, так как открыто несколько книг, а книга, вызываемая этим API, потеряла фокус.	Нет
`InvalidOperationInCellEditMode`	Операция недоступна, пока Excel находится в режиме редактирования ячейки. Выйдите из режима редактирования с помощью клавиш ВВОД или TAB или выбрав другую ячейку, а затем повторите попытку.	Нет
`MergedRangeConflict`	Не удается завершить операцию. Таблица не может перекрываться с другой таблицей, отчетом сводной таблицы, результатами запроса, объединенными ячейками или картой XML.	Нет
`NonBlankCellOffSheet`	Microsoft Excel не может вставлять новые ячейки, так как он будет отправлять непустые ячейки с конца листа. Эти непустые ячейки могут казаться пустыми, но иметь пустые значения, некоторые форматирование или формулу. Удалите достаточно строк или столбцов, чтобы освободить место для вставки, а затем повторите попытку.	Нет
`OperationCellsExceedLimit`	Предпринятая операция затрагивает более 33554000 ячеек.	`TableColumnCollection.add API` Если вызывает эту ошибку, убедитесь, что на листе нет непреднамеренных данных, но за пределами таблицы. В частности, проверьте наличие данных в самых правых столбцах листа. Удалите непреднамеренные данные, чтобы устранить эту ошибку. Один из способов проверить, сколько ячеек обрабатывает операция, — выполнить следующее вычисление: `(number of table rows) x (16383 - (number of table columns))`. Число 16383 — это максимальное количество столбцов, поддерживаемых Excel. Эта ошибка возникает только в Excel в Интернете.
`PivotTableRangeConflict`	Предпринятая попытка операции вызывает конфликт с диапазоном сводной таблицы.	Нет
`RangeExceedsLimit`	Число ячеек в диапазоне превысило максимальное поддерживаеме число. Дополнительные сведения см. в статье Ограничения ресурсов и оптимизация производительности надстроек Office .	Нет
`RefreshWorkbookLinksBlocked`	Операция завершилась сбоем, так как пользователь не предоставил разрешение на обновление ссылок на внешние книги.	Нет
`UnsupportedSheet`	Этот тип листа не поддерживает эту операцию, так как это лист макроса или диаграммы.	Нет

Коды ошибок и сообщения о word

Код ошибки	Сообщение об ошибке	Примечания
`SearchDialogIsOpen`	Открыто диалоговое окно поиска.	Нет
`SearchStringInvalidOrTooLong`	Строка поиска недопустимая или слишком длинная.	Максимальная строка поиска — 255 символов.

Уведомления об ошибках

Способ сообщения об ошибках пользователям зависит от используемой системы пользовательского интерфейса.

Если вы используете React в качестве системы пользовательского интерфейса, используйте компоненты пользовательского интерфейса Fluent и элементы конструктора. Рекомендуется передавать сообщения об ошибках с помощью компонента Dialog . Если ошибка находится во входных данных пользователя, настройте компонент Input , чтобы отобразить ошибку полужирным красным шрифтом.

Примечание.

Компонент Оповещение также можно использовать для сообщения об ошибках пользователям, но в настоящее время он находится в предварительной версии и не должен использоваться в рабочей надстройке. Сведения о состоянии выпуска см. в статье Стратегия развития компонентов Fluent UI React версии 9.
Если вы не используете React для пользовательского интерфейса, рассмотрите возможность использования старых компонентов пользовательского интерфейса Fabric , реализованных непосредственно в HTML и JavaScript. Некоторые примеры шаблонов находятся в репозитории Office-Add-in-UX-Design-Patterns-Code . Обратите внимание, особенно на вложенные папки диалогового окна и навигации. В примере Excel-Add-in-SalesLeads используется баннер сообщения.

Поделиться через