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

  • Статья

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

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

В наших примерах кода и фрагментах кода Script Lab вы заметите, что каждый вызов 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 используется баннер сообщения.

См. также