Обработка ошибок с помощью API JavaScript для конкретного приложения
При создании надстройки с помощью 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 используется баннер сообщения.
См. также
Office Add-ins