VueCraft NPM

Ленивые фоновые изображения ​

v-lazy-img — директива для установки background-image на любой элемент после его появления во вьюпорте. Используйте, когда нельзя применить компонент <VImage> — CSS-фоны, обёртки сторонних библиотек и т. д.

vue
<!-- Простая строка -->
<div v-lazy-img="'/background.jpg'" class="hero" />

<!-- Объект с опциями -->
<div
  v-lazy-img="{
    src: '/background.jpg',
    placeholder: 'data:image/jpeg;base64,...',
    rootMargin: '100px',
    onLoad: () => console.log('loaded'),
    onError: (e) => console.error(e),
  }"
  class="hero"
/>

Опции ​

src ​

string, обязателен. URL фонового изображения.

placeholder ​

string, опционален. Base64 или URL, показываемый сразу; заменяется после загрузки.

rootMargin ​

string · по умолчанию: "200px". rootMargin для IO.

threshold ​

number · по умолчанию: 0. threshold для IO.

onLoad ​

() => void, опционален. Вызывается при завершении загрузки изображения.

onError ​

(e: Event) => void, опционален. Вызывается при неудаче загрузки изображения.

Плейсхолдеры из манифеста ​

Если у директивы нет собственного placeholder, она ищет свой src в манифесте плейсхолдеров, зарегистрированном в приложении, и сразу после монтирования рисует на элементе декодированное размытие и доминирующий цвет записи — ещё до того, как изображение окажется рядом с областью просмотра. Цвет убирается после загрузки изображения. Явный placeholder всегда главнее, а изображение без записи остаётся как было.

Поведение ​

  1. При монтировании — получает observer из общего пула (IntersectionObserver, разделяемого с useLazyLoad/useImage/<VImage>/useBackgroundImage, с ключом по rootMargin/threshold) и начинает наблюдать за элементом
  2. Когда элемент попадает во вьюпорт — если задан placeholder, он немедленно применяется как background-image
  3. Новый объект Image загружает src в фоне
  4. При загрузке — background-image обновляется на src; вызывается onLoad
  5. При ошибке — вызывается onError; background-image остаётся плейсхолдером (если он был)
  6. При размонтировании — observer отключается
  7. При обновлении биндинга — observer пересоздаётся с новыми опциями

Регистрация директивы вручную ​

Директива регистрируется автоматически вместе с VImageKitPlugin. Чтобы зарегистрировать её в одном компоненте:

vue
<script setup lang="ts">
import { vLazyImg } from '@macrulez/vue-image-kit'
</script>

<template>
  <div v-lazy-img="'/bg.jpg'" style="width:100%;height:400px" />
</template>

Или глобально без плагина:

ts
import { vLazyImg } from '@macrulez/vue-image-kit'

app.directive('lazy-img', vLazyImg)

Пример — карточка с ленивым фоном ​

vue
<script setup lang="ts">
import { vLazyImg } from '@macrulez/vue-image-kit'

const cards = [
  { id: 1, bg: '/card-1.jpg', placeholder: 'data:image/jpeg;base64,/9j/...' },
  { id: 2, bg: '/card-2.jpg', placeholder: 'data:image/jpeg;base64,/9j/...' },
]
</script>

<template>
  <div
    v-for="card in cards"
    :key="card.id"
    v-lazy-img="{ src: card.bg, placeholder: card.placeholder }"
    class="card"
  />
</template>

<style scoped>
.card {
  width: 300px;
  height: 200px;
  background-size: cover;
  background-position: center;
  border-radius: 12px;
}
</style>

Нужен srcset/image-set() для адаптивных фонов? См. Адаптивные ленивые фоны — composable-аналог.