<svelte:boundary>

<svelte:boundary onerror={handler}>...</svelte:boundary>

Заметка

Эта функция была добавлена в 5.3.0

Границы позволяют «отделить» части вашего приложения, чтобы вы могли:

• отображать интерфейс, который должен показываться во время первоначального выполнения await-выражений
• обрабатывать ошибки, возникающие при рендеринге или выполнении эффектов, и предоставлять интерфейс для отображения при возникновении ошибки

Если граница обрабатывает ошибку (с помощью сниппета failed или обработчика onerror, или обоих), её текущее содержимое будет удалено.

Заметка

Ошибки, возникающие вне процесса рендеринга (например, в обработчиках событий, после setTimeout или асинхронных операциях), не перехватываются границами обработки ошибок.

Параметры

Чтобы граница выполняла свою функцию, должен быть предоставлен хотя бы один из следующих элементов.

pending

Этот сниппет будет показан при первом создании границы и останется видимым до тех пор, пока все выражения await внутри границы не разрешатся (демонстрация):

<svelte:boundary>
  <p>{await delayed('привет!')}</p>

  {#snippet pending()}
    <p>загрузка...</p>
  {/snippet}
</svelte:boundary>

failed

Если предусмотрен сниппет failed, он будет отображаться при возникновении ошибки внутри границы, получая доступ к объекту error и функции reset для повторного создания содержимого (демонстрация):

<svelte:boundary>
  <FlakyComponent />

  {#snippet failed(error, reset)}
    <button onclick={reset}>упс! попробовать ещё раз</button>
  {/snippet}
</svelte:boundary>

Заметка

Как и в случае со сниппетами, передаваемыми в компоненты, сниппет failed может быть передан явно как свойство…

<svelte:boundary {failed}>...</svelte:boundary>

…или неявно, объявив его непосредственно внутри границы, как в примере выше.

onerror

Если предоставлена функция onerror, она будет вызвана с теми же двумя аргументами: error и reset. Это полезно для отслеживания ошибок с помощью сервиса отчётов об ошибках…

<svelte:boundary onerror={(e) => report(e)}>
  ...
</svelte:boundary>

…или для использования error и reset за пределами самой границы:

<script>
  let error = $state(null);
  let reset = $state(() => {});

  function onerror(e, r) {
    error = e;
    reset = r;
  }
</script>

<svelte:boundary {onerror}>
  <FlakyComponent />
</svelte:boundary>

{#if error}
  <button onclick={() => {
    error = null;
    reset();
  }}>
    упс! попробовать ещё раз
  </button>
{/if}

Если ошибка происходит внутри функции onerror (или если вы повторно выбрасываете ошибку), она будет обработана родительской границей, если таковая существует.

Использование transformError

По умолчанию границы ошибок никак не влияют на сервер — если во время рендеринга возникает ошибка, весь рендеринг завершится неудачей.

Начиная с версии 5.51 вы можете управлять этим поведением для границ ошибок с помощью сниппета failed, вызвав функцию render(...) с параметром transformError.

Заметка

Если вы используете Svelte через фреймворк, такой как SvelteKit, то, скорее всего, у вас нет прямого доступа к вызову render(...) — фреймворк должен настроить transformError за вас. SvelteKit добавит поддержку этого в ближайшем будущем через хук handleError.

Функция transformError должна возвращать объект, который можно сериализовать в JSON. Этот объект будет использован для рендеринга сниппета failed. Он будет сериализован и применён для гидратации сниппета в браузере:

import { render } from 'svelte/server';
import App from './App.svelte';

const { head, body } = await render(App, {
  transformError: (error) => {
    // логируем оригинальную ошибку вместе со стек-трейсом...
    console.error(error);

    // ...и возвращаем очищенную, удобную для пользователя ошибку,
    // которая будет отображена в сниппете `failed`
    return {
      message: 'An error occurred!'
    };
  };
});

Если transformError выбросит исключение (или перевыбросит ошибку), то вызов render(...) в целом завершится неудачей с этой ошибкой.

Заметка

Ошибки, возникающие во время серверного рендеринга, могут содержать конфиденциальную информацию в полях message и stack. Рекомендуется очищать (редактировать) эти данные, а не отправлять их в браузер в неизменённом виде.

Если у границы ошибок задан обработчик onerror, он будет вызван во время гидратации с десериализованным объектом ошибки.

Функции mount и hydrate также принимают опцию transformError, которая по умолчанию является функцией идентичности (возвращает переданное значение без изменений). Как и в случае с render, эта функция преобразует ошибку времени рендеринга перед тем, как она будет передана в сниппет failed или обработчик onerror.