{@attach ...}

Привязки (attachments) — это функции, которые выполняются при монтировании элемента в DOM. При необходимости они могут возвращать функцию, которая будет вызвана при удалении элемента из DOM.

Заметка

Привязки доступны в Svelte 5.29 и новее.

JS

App.svelte

<script>
  /** @type {import('svelte/attachments').Attachment} */
  function myAttachment(element) {
    console.log(element.nodeName); // 'DIV'

    return () => {
      console.log('cleaning up');
    };
  }
</script>

<div {@attach myAttachment}>...</div>

TS

App.svelte

<script lang="ts">
  import type { Attachment } from 'svelte/attachments';


  const myAttachment: Attachment = (element) => {
    console.log(element.nodeName); // 'DIV'

    return () => {
      console.log('cleaning up');
    };
  };
</script>

<div {@attach myAttachment}>...</div>

Элемент может иметь любое количество привязок.

Фабрики привязок

Полезный паттерн — когда функция (например, tooltip в этом примере) возвращает привязку (демонстрация):

JS

App.svelte

<script>
  import tippy from 'tippy.js';

  let content = $state('Hello!');

  /**
   * @param {string} content
   * @returns {import('svelte/attachments').Attachment}
   */
  function tooltip(content) {
    return (element) => {
      const tooltip = tippy(element, { content });
      return tooltip.destroy;
    };
  }
</script>

<input bind:value={content} />

<button {@attach tooltip(content)}>
  Наведи курсор
</button>

TS

App.svelte

<script lang="ts">
  import tippy from 'tippy.js';
  import type { Attachment } from 'svelte/attachments';

  let content = $state('Hello!');

  function tooltip(content: string): Attachment {
    return (element) => {
      const tooltip = tippy(element, { content });
      return tooltip.destroy;
    };
  }
</script>

<input bind:value={content} />

<button {@attach tooltip(content)}>
  Наведи курсор
</button>

Поскольку выражение tooltip(content) выполняется внутри эффекта, привязка будет уничтожаться и создаваться заново при каждом изменении content.

Встроенные привязки

Привязки также можно создавать встроенным способом (демонстрация):

JS

App.svelte

<script>
  import { paint } from './gradient.js';
</script>

<canvas
  width={32}
  height={32}
  {@attach (canvas) => {
    const context = canvas.getContext('2d');

    $effect(() => {
      let frame = requestAnimationFrame(function loop(t) {
        frame = requestAnimationFrame(loop);
        paint(context, t);
      });

      return () => {
        cancelAnimationFrame(frame);
      };
    });
  }}
></canvas>

TS

App.svelte

<script lang="ts">
  import { paint } from './gradient.js';
</script>

<canvas
  width={32}
  height={32}
  {@attach (canvas) => {
    const context = canvas.getContext('2d');

    $effect(() => {
      let frame = requestAnimationFrame(function loop(t) {
        frame = requestAnimationFrame(loop);
        paint(context, t);
      });

      return () => {
        cancelAnimationFrame(frame);
      };
    });
  }}
></canvas>

Заметка

Вложенный эффект выполняется при каждом изменении color, тогда как внешний эффект (где вызывается canvas.getContext(...)) выполняется только один раз, так как не зависит от реактивного состояния.

Передача привязок в компоненты

При использовании {@attach ...} на компоненте создаётся проп с ключом-Symbol. Если компонент затем распространяет пропсы на элемент, этот элемент получит привязки.

Это позволяет создавать обёрточные компоненты, расширяющие функциональность элементов (демонстрация):

JS

Button.svelte

<script>
  /** @type {import('svelte/elements').HTMLButtonAttributes} */
  let { children, ...props } = $props();
</script>

<!-- `props` включает привязки -->
<button {...props}>
  {@render children?.()}
</button>

TS

Button.svelte

<script lang="ts">
  import type { HTMLButtonAttributes } from 'svelte/elements';

  let { children, ...props }: HTMLButtonAttributes = $props();
</script>

<!-- `props` включает привязки -->
<button {...props}>
  {@render children?.()}
</button>

JS

App.svelte

<script>
  import tippy from 'tippy.js';
  import Button from './Button.svelte';

  let content = $state('Hello!');

  /**
   * @param {string} content
   * @returns {import('svelte/attachments').Attachment}
   */
  function tooltip(content) {
    return (element) => {
      const tooltip = tippy(element, { content });
      return tooltip.destroy;
    };
  }
</script>

<input bind:value={content} />

<Button {@attach tooltip(content)}>
  Наведи курсор
</Button>

TS

App.svelte

<script lang="ts">
  import tippy from 'tippy.js';
  import Button from './Button.svelte';
  import type { Attachment } from 'svelte/attachments';

  let content = $state('Hello!');

  function tooltip(content: string): Attachment {
    return (element) => {
      const tooltip = tippy(element, { content });
      return tooltip.destroy;
    };
  }
</script>

<input bind:value={content} />

<Button {@attach tooltip(content)}>
  Наведи курсор
</Button>

Программное создание привязок

Для добавления привязок к объекту, который будет распространён на компонент или элемент, используйте createAttachmentKey.

Преобразование действий в привязки

Если вы используете библиотеку, которая предоставляет только действия, вы можете преобразовать их в привязки с помощью fromAction, что позволяет, например, использовать их с компонентами.