VueCraft NPM

Состояние плейсхолдера ​

usePlaceholder() (hazehash-vue) — реактивное состояние, на котором построен <PlaceholderImage>, для заданного хеша: ref canvas для рисования, средний цвет, соотношение сторон и флаг, который сообщает, что страница уже на клиенте. Используйте его, чтобы собрать собственную разметку вокруг плейсхолдера.

ts
function usePlaceholder(
  hash: MaybeRefOrGetter<string | Uint8Array | undefined | null>,
  options?: UsePlaceholderOptions,
): UsePlaceholderReturn
vue
<script setup lang="ts">
import { usePlaceholder } from 'hazehash-vue'

const props = defineProps<{ hash: string }>()
const { canvas, backgroundColor, aspectRatio } = usePlaceholder(() => props.hash)
</script>

<template>
  <div class="card" :style="{ backgroundColor, aspectRatio }">
    <canvas ref="canvas" aria-hidden="true" />
  </div>
</template>

На сервере значения есть только у backgroundColor и aspectRatio. Canvas рисуется после монтирования компонента, поэтому серверная разметка и первый клиентский рендер никогда не различаются. Хеш может быть обычным значением, ref или геттером, а при его изменении canvas перерисовывается. В Nuxt composable импортируется автоматически.

Параметры ​

hash ​

MaybeRefOrGetter<string | Uint8Array | undefined | null>

Хеш для показа. undefined, null и пустая строка означают «плейсхолдера пока нет»: все значения остаются пустыми. Недопустимый хеш не бросает исключение; значения остаются пустыми, а в консоль один раз за страницу выводится предупреждение [hazehash-vue] invalid placeholder hash:.

options ​

UsePlaceholderOptions · необязательно

Объект с одним полем:

  • size — MaybeRefOrGetter<number | undefined> · по умолчанию: 32. Длинная сторона декодированного превью, ограниченная диапазоном 4–128, как и опция size у decode(). Может быть реактивной, а её изменение перерисовывает canvas.

Возвращаемое значение ​

canvas ​

Ref<HTMLCanvasElement | null>

Ref шаблона. Поставьте ref="canvas" на <canvas>, и composable нарисует превью в него после монтирования и при каждом изменении хеша или size. Canvas получает пиксельный размер превью, поэтому задайте ему CSS-размер, заполняющий вашу рамку.

mounted ​

Ref<boolean>

false на сервере и при первом клиентском рендере, true после монтирования компонента. Используйте, чтобы рендерить <canvas> только на клиенте, как это делает компонент.

average ​

ComputedRef<{ r: number; g: number; b: number; a: number } | undefined>

Средний цвет хеша в том виде, как его возвращает getAverageColor(), либо undefined, если допустимого хеша нет. Доступен и на сервере.

backgroundColor ​

ComputedRef<string | undefined>

Средний цвет в виде CSS-строки rgba(r, g, b, a), готовой для background-color, либо undefined.

aspectRatio ​

ComputedRef<number | undefined>

Соотношение сторон хеша числом, как его возвращает getAspectRatio(), либо undefined. Передайте его в CSS-свойство aspect-ratio.

Пример — плейсхолдер только на клиенте, с превью покрупнее:

vue
<script setup lang="ts">
import { usePlaceholder } from 'hazehash-vue'

const props = defineProps<{ hash: string; src: string }>()
const { canvas, mounted, backgroundColor, aspectRatio } = usePlaceholder(() => props.hash, {
  size: 64,
})
</script>

<template>
  <div class="frame" :style="{ backgroundColor, aspectRatio }">
    <canvas v-if="mounted" ref="canvas" aria-hidden="true" />
    <img :src="src" alt="" />
  </div>
</template>